# Configuring Jexl operators

Many lenses allow one to write a Jexl script as part of their configuration. Jexl is a friendly language offering a number of operators which can be applied to transform data (typically the `payload` fields ) or do comparison, and so on.

Here are a selection, there are further details at the Jexl GitHub page.

Operators.

Use these operators to perform mathematical operations on values

Operation Symbol Example

Negate

`!`

`!true``false`

`+`

`3 + 4``7`

Subtract

`-`

`4 - 3``1`

Multiply

`*`

`3 * 8``24`

Divide

`/`

`15 / 4``3.75`

Divide and Floor

`//`

`15 // 4``3`

Modulus

`%`

`23 % 2``1`

Power of

`^`

`2^3``8`

Logical AND

`&&`

`true && true``true`

Logical OR

`+

Comparisons.

Use these expressions to compare two values, the Boolean results can be used for, for example filtering.

Operation Symbol Example

Equal

`==`

`1 == 2``false`

Not Equal

`!=`

`1 != 2``true`

Greater Than

`>`

`2 > 3``false`

Greater Than or Equal

`>=`

`3 >= 3``true`

Less Than

`<`

`2 < 3``true`

Less Than or Equal

`<=`

`2 ⇐ 4``true`

Element in array or string

`in`

`"cat" in ["cat", "dog", "mouse"]``true`

Conditional Operators.

Conditional operators return the second or third expression based on the result of the first expression. If the first expression (`"Bob" in ["Bob", "Mary"]` below) return `true`, "Yes" is returned. If it returns false, "No" is returned.

Example Result

"Bob" `in` ["Bob", "Mary"] ? "Yes" : "No"

"Yes"

Identifiers.

Access variables in the payload with dot notation or by using brackets, for example:

```{
name: {
first: 'John'
last: 'Smith'
},
age: 55,
colleagues: [
'Mary',
'Bob',
'Ted'
],
teammate: 2
}```
Example Result

name.first

"John"

colleagues[teammate]

"Ted"

name['la' + 'st']

"Smith"

Collection filtering.

Arrays of objects (Collections) can be filtered by including a filter expression in brackets. Properties of each collection can be referenced by prefixing them with a leading dot. The result is an array of objects for which the filter returns a truthy value.

```{
users: [
{ first: 'John', last: 'Smith', age: 20},
{ first: 'Mary', last: 'Jones', age: 46},
{ first: 'Ted', last: 'Cotter', age: 16},
{ first: 'Bob', last: 'White', age: 66}
],
}```
Example Result

users[.last == 'Jones']

[\{ first: 'Mary', last: 'Jones', age: 46}]

[\{ first: 'John', last: 'Smith', age: 20}, first: 'Ted', last: 'Cotter', age: 16}]

users[first == 'John'].last

"Smith"

Lens Expression Functions

In addition to the general Jexl parsing functionality, Siren Investigate also exposes a number of JavaScript-like functions for use in Lens Expressions. Payload values (or the results from earlier parsing) are piped into the function using the `|` character. These values become the `val` parameter for the functions below - meaning the `val` does not need to be added in the `()` after the function name. In some cases, this value is all that is needed by the function and some functions require extra parameters.

Some functions require string inputs and some require integer or floating-point inputs

Table 1. String Lens Expressions
Function Example Explanation

`payload.IP | split('.', 3)`

Splits an IP address by the '.' and returns the first 3 entries as an array

`payload.name | endsWith('smith', 10)`

Returns true if `val` ends with `substring`, if `length` is added, that number of characters from the beginning of `val` is checked.

`payload.name | startsWith('smith', 10)`

Returns true if `val` begins with `substring`, if `position` is added, the substring from that position to the end of `val` is checked.

`payload.name | indexOf('smith', 10)`

Returns the position of the first character of `substring` if `val` contains `substring`, if `length` is added, `val` is checked from that position.

upper(val)

`payload.name | upper`

Returns `val` in upper case.

lower(val)

`payload.name | lower`

Returns `val` in lower case.

substring(val, start, end)

`payload.name | substring(5, 10)`

Returns the string within `val` found between `start` and `end`.

replace(val, substring, newSubString)

`payload.name | replace('smith', 'jones')`

Replaces `substring` with `newSubString` in `val`.

Table 2. Number lens Expressions
Function Example Explanation

round(val)

`payload.range | round`

Returns `val` rounded to the nearest integer.

trunc(val)

`payload.range | trunc`

Returns the integer part of `val`.

sqrt(val)

`payload.range | sqrt`

Returns `√val`.

sign(val)

`payload.range | sign`

Returns 1 if `val` is positive, -1 if `val` is negative or 0 if `val` equals 0.

ceil(val)

`payload.price | ceil`

Returns the nearest integer greater than `val`

floor(val)

`payload.price | floor`

Returns the nearest integer less than `val`

abs(val)

`payload.temperature_change | abs`

Returns the absolute value for a Number or 0 if the number is `null`

exp(val)

`payload.difference | exp`

Returns `ℯval`

log(val)

`payload.difference | log`

Returns the natural logarithm of `val`, for example `ln(val)`

random(val)

`payload.range | random`

Returns `val` multiplied by a floating-point, pseudo-random number between 0 (inclusive) and 1 (exclusive).