Merge pull request #955 from camunda/release-1.19.0

[Release] 1.19.0

Author: saig0

docs/docs/changelog/changelog.md

@@ -10,9 +10,24 @@ This page contains an overview of the released versions and highlights the major
 point of view (i.e. focus on features). The complete changelog, including the patch
 versions, can be found on the [GitHub release page](https://github.com/camunda/feel-scala/releases).
 
+## 1.19
+
+<MarkerChangelogVersion versionZeebe="8.7.0" versionC7="not yet" />
+
+**Built-in functions:**
+
+* New built-in
+  function `is blank()`
+  to check if a string is blank
+* New built-in
+  function `partition()`
+  to split a list in sublists of the same size
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.19.0).
+
 ## 1.18
 
-<MarkerChangelogVersion versionZeebe="8.6.0" versionC7="not yet" />
+<MarkerChangelogVersion versionZeebe="8.6.0" versionC7="7.23.0" />
 
 **Built-in functions:**
 

docs/docusaurus.config.js

@@ -96,15 +96,18 @@ module.exports = {
           // includes the unreleased version
           includeCurrentVersion: true,
           // the last released (stable) version
-          lastVersion: '1.18',
+          lastVersion: '1.19',
           // override the config for specific versions
           versions: {
             // for the unreleased version
             current: {
               // add the postfix "unreleased"
-              label: '1.19 (unreleased)'
+              label: '1.20 (unreleased)'
             },
             // for all supported versions: disable the "unmaintained version" banner
+            '1.18': {
+              banner: 'none',
+            },
             '1.17': {
               banner: 'none',
             },

docs/versioned_docs/version-1.19/changelog/changelog.md

@@ -0,0 +1,178 @@
+---
+id: changelog 
+title: Changelog 
+slug: /changelog/
+---
+
+import MarkerChangelogVersion from "@site/src/components/MarkerChangelogVersion";
+
+This page contains an overview of the released versions and highlights the major changes from a user
+point of view (i.e. focus on features). The complete changelog, including the patch
+versions, can be found on the [GitHub release page](https://github.com/camunda/feel-scala/releases).
+
+## 1.19
+
+<MarkerChangelogVersion versionZeebe="8.7.0" versionC7="not yet" />
+
+**Built-in functions:**
+
+* New built-in
+  function `is blank()`
+  to check if a string is blank
+* New built-in
+  function `partition()`
+  to split a list in sublists of the same size
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.19.0).
+
+## 1.18
+
+<MarkerChangelogVersion versionZeebe="8.6.0" versionC7="7.23.0" />
+
+**Built-in functions:**
+
+* New built-in
+  function `is empty()`
+  to check if a list is empty
+* New built-in
+  function `trim()`
+  to remove leading and trailing spaces of a string
+* New built-in
+  function `uuid()`
+  to create a UUID (Universally Unique Identifier)
+* New built-in
+  function `to base64()`
+  to encode a string in Base64 format
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.18.0).
+
+## 1.17
+
+<MarkerChangelogVersion versionZeebe="8.3.0" versionC7="7.21.0" />
+
+**Expressions:**
+
+* Overhauled error handling. Instead of failing the evaluation, for example, because of a non-existing
+  variable or context entry, it handles these cases and returns `null`. 
+
+**Built-in functions:**
+
+* New built-in
+  function [duplicate values()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-list#duplicate-valueslist)
+  to find duplicate list items
+* New built-in
+  function [get or else()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-boolean#get-or-elsevalue-default)
+  to handle `null` values
+* New built-in
+  function [assert()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-boolean#assertvalue-condition)
+  to fail the evaluation if a condition is not met
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.17.0).
+
+## 1.16
+
+<MarkerChangelogVersion versionZeebe="8.2.0" versionC7="7.20.0" />
+
+
+**Built-in functions:**
+
+* New built-in function [get value()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-context#get-valuecontext-keys) to access a context with a dynamic path
+* New built-in function [context put()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-context#context-putcontext-keys-value) to insert a nested value in a context
+* New built-in function [last day of month()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-temporal#last-day-of-monthdate) to get the last day of a month
+* New built-in function [date and time()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion#date-and-timedate-timezone) to get a date-time for a timezone
+* New built-in function [random number()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-numeric#random-number) to get a random number
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.16.0).
+
+## 1.15
+
+<MarkerChangelogVersion versionZeebe="8.1.0" versionC7="7.19.0" />
+
+**Expressions:**
+
+* New `@` notation for [temporal literals](https://docs.camunda.io/docs/components/modeler/feel/language-guide/feel-temporal-expressions#literal)
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.15.0).
+
+## 1.14
+
+<MarkerChangelogVersion versionZeebe="1.3.1" versionC7="7.18.0" />
+
+**Built-in functions:**
+
+* New function [extract()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string#extractstring-pattern)
+  that applies a regular expression to a given a string
+* New
+  function [string join()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-list#string-joinlist)
+  that merges a list of strings into a single string
+* New [range functions](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-range) to compare
+  ranges and scalar values
+* New functions to round numeric values:
+  * [round up()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-numeric#round-upn-scale)
+  * [round down()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-numeric#round-downn-scale)
+  * [round half up()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-numeric#round-half-upn-scale)
+  * [round half down()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-numeric#round-half-downn-scale)
+* Extend function [abs()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-temporal#absn) for
+  duration values
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.14.0).
+
+## 1.13
+
+<MarkerChangelogVersion versionZeebe="1.0.0" versionC7="7.15.0" />
+
+**Expressions:**
+
+* Access the property [weekday](https://docs.camunda.io/docs/components/modeler/feel/language-guide/feel-temporal-expressions#properties)
+  of date and date-time values
+* Allow escape sequences in [string literals](https://docs.camunda.io/docs/components/modeler/feel/language-guide/feel-data-types#string)
+
+**Built-in functions:**
+
+* New
+  function [context()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion#contextentries)
+  that creates a context from a given key-value list
+* New function [put()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-context#context-putcontext-key-value) that
+  extends a context by a given entry
+* New
+  function [put all()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-context#context-mergecontexts)
+  that merges the given contexts
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.13.0).
+
+## 1.12
+
+<MarkerChangelogVersion versionZeebe="0.25.0" versionC7="7.14.0" />
+
+**Built-in functions:**
+
+* New function [now()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-temporal#now) that
+  returns the current date-time
+* New function [today()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-temporal#today)
+  that returns the current date
+* New
+  function [week of year()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-temporal#week-of-yeardate)
+  that returns the number of the week within the year
+* New
+  function [month of year()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-temporal#month-of-yeardate)
+  that returns the name of the month
+* New
+  function [day of week()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-temporal#day-of-weekdate)
+  that returns name of the weekday
+* New
+  function [day of year()](https://docs.camunda.io/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-temporal#day-of-yeardate)
+  that returns the number of the day within the year
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.12.0).
+
+
+## 1.11
+
+<MarkerChangelogVersion versionZeebe="0.23.0" versionC7="7.13.0" />
+
+**Expressions:**
+
+* Access the [element of a list](https://docs.camunda.io/docs/components/modeler/feel/language-guide/feel-list-expressions#get-element) using a numeric variable
+* Disable external functions by default for security reasons
+
+See the full changelog [here](https://github.com/camunda/feel-scala/releases/tag/1.11.0).

docs/versioned_docs/version-1.19/developer-guide/bootstrapping.md

@@ -0,0 +1,149 @@
+---
+id: bootstrapping
+title: Bootstrapping
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The FEEL engine can be integrated in two different ways
+* as a library by calling the engine API
+* as a script engine by using the Java's script engine API
+
+:::tip
+
+Have a look at the [FEEL Playground](/playground/playground.mdx) for trying out FEEL expressions quickly in
+development.
+
+:::
+
+### The dependency
+
+Add the engine as dependency to your project's `pom.xml`:
+
+```xml
+<dependency>
+  <groupId>org.camunda.feel</groupId>
+  <artifactId>feel-engine</artifactId>
+  <version>${VERSION}</version>
+</dependency>
+```
+
+Or, download the [JAR file](https://github.com/camunda/feel-scala/releases) _(feel-engine-${VERSION}-complete.jar)_ and copy it into your application.
+
+### Use as a library
+
+The FEEL engine provides APIs to parse and evaluate expressions and unary-tests.
+
+<Tabs
+defaultValue="scala"
+values={[
+{label: 'Scala', value: 'scala'},
+{label: 'Java', value: 'java'},
+]}>
+
+<TabItem value="scala">
+
+Create a new instance of the class `FeelEngine`. 
+
+```scala
+object MyProgram {
+  
+  val engine = new FeelEngine
+  
+  def feel(expression: String, context: Map[String, Any]) {
+    
+    val result: Either[Failure, Boolean] = engine.evalUnaryTests(expression, context)
+    // or    
+    val result: Either[Failure, Any] = engine.evalExpression(expression, context)
+  
+    // handle result
+    result
+        .right.map(value => println(s"result is: $value"))
+        .left.map(failure => println(s"failure: $failure"))
+  }  
+}
+```
+
+Use the constructor arguments to configure the engine.
+
+```scala
+new FeelEngine(configuration = Configuration(externalFunctionsEnabled = true))
+```
+
+</TabItem>
+<TabItem value="java">
+
+Use the builder to create a new instance of the class `FeelEngine`.
+
+```java
+ public class MyProgram {
+
+    public static void main(String[] args) {
+
+        final FeelEngine engine = new FeelEngine.Builder()
+            .valueMapper(SpiServiceLoader.loadValueMapper())
+            .functionProvider(SpiServiceLoader.loadFunctionProvider())
+            .build();
+
+        final Map<String, Object> variables = Map.of("x", 21);
+        final Either<FeelEngine.Failure, Object> result = engine.evalExpression(expression, variables);
+
+        if (result.isRight()) {
+            final Object value = result.right().get();
+            System.out.println("result is " + value);
+        } else {
+            final FeelEngine.Failure failure = result.left().get();
+            throw new RuntimeException(failure.message());
+        }
+    }
+}
+```
+
+Use the builder to configure the engine.
+
+```java
+new FeelEngine.Builder().enableExternalFunctions(true).build()
+```
+
+</TabItem>
+</Tabs>
+
+
+:::danger Security
+External functions are disabled by default. They would allow calling arbitrary
+code or accessing sensitive data. It is recommended to use the
+[FunctionProvider API](function-provider-spi.md) instead.
+:::
+
+### Use as script engine
+
+Calling the FEEL engine via Java's script engine
+API ([JSR 223](https://www.jcp.org/en/jsr/detail?id=223)).
+
+```scala
+object MyProgram {
+
+  val scriptEngineManager = new ScriptEngineManager
+ 
+  def feel(script: String, context: ScriptContext) {
+  
+    val scriptEngine: FeelScriptEngine = scriptEngineManager.getEngineByName("feel")
+    
+    val result: Object = scriptEngine.eval(script, context)
+    // ...
+  }
+
+}
+```
+
+The engine is registered under the following names:
+
+* `feel`
+* `http://www.omg.org/spec/FEEL/20140401` (FEEL namespace)
+* `feel-scala`
+
+To evaluate a unary-tests expression, use one of the following names:
+
+* `feel-unary-tests`
+* `feel-scala-unary-tests`

docs/versioned_docs/version-1.19/developer-guide/developer-guide-introduction.md

@@ -0,0 +1,15 @@
+---
+id: developer-guide-introduction
+title: Introduction
+slug: /developer-guide/
+---
+
+You can embed the FEEL engine in your application in different ways. Have a look
+at [Bootstrapping](bootstrapping.md) to see how.
+
+Afterward, you can extend and customize the FEEL engine by implementing one of the following
+SPIs (Service Provider Interface):
+
+* [Function Provider SPI](function-provider-spi.md)
+* [Value Mapper SPI](value-mapper-spi.md)
+* [Clock SPI](feel-engine-clock-spi.md)