Array Expression

Introduction

This library is created to provide formatter declaration that can be transported through network and executed securely.
The formatter is written in JSON and it's highly configurable. This formatter declaration is called "array expression".

Syntax

Expression array syntax is specified below:

``ts
[expression_name, arg0, arg1, ...]
`

Expression is categorized into 4 different types:

- Type
- boolean
- string
- Math
- +
- -
- \*
- /
- %
- ^
- sqrt
- abs
- sin
- cos
- tan
- log
- floor
- ceil
- round
- min
- max
- String
- concat
- downcase
- upcase
- number-format
- Decision
- !
- ==
- !=
- <
- <=
- >
- >=
- all
- any
- if

---

Type expressions

$3

Converts value into boolean.

`ts
['boolean', value]: boolean
`

$3

Converts value into string.

`ts
['string', value]: string
`

---

Math expressions

$3

Performs addition and return the resulting number.

`ts
['+', number1, number2]: number
`

$3

Performs subtraction and return the resulting number.

`ts
['-', number1, number2]: number
`

$3

Performs multiplication and return the resulting number.

`ts
['*', number1, number2]: number
`

$3

Performs division and return the resulting number.

`ts
['/', number1, number2]: number
`

$3

Performs remainder operation and return the resulting number.

`ts
['%', number1, number2]: number
`

$3

Returns number1 to the power of number2.

`ts
['^', number1, number2]: number
`

$3

Returns the square root of a number.

`ts
['sqrt', number]: number
`

$3

Returns the absolute value of a number.

`ts
['abs', number]: number
`

$3

Returns the sine of a number.

`ts
['sin', number]: number
`

$3

Returns the cosine of a number.

`ts
['cos', number]: number
`

$3

Returns the tangent of a number.

`ts
['tan', number]: number
`

$3

Returns natural logarithm (base e) of a number.

`ts
['log', number]: number
`

$3

Returns the greatest integer less than or equal to a value.

`ts
['floor', number]: number
`

$3

Returns the smallest integer greater than or equal to a value.

`ts
['ceil', number]: number
`

$3

Rounds a number to the nearest integer and return the resulting number.

`ts
['round', number]: number
`

$3

Returns the lowest number in the arguments.

`ts
['min', number1, number2, ...]: number
`

$3

Returns the highest number in the arguments.

`ts
['max', number1, number2, ...]: number
`

---

String expressions

$3

Concatenate the arguments into one single string.

`ts
['concat', value1, value2, ...]: string
`

$3

Converts all the alphabetic characters in a string to lowercase and return the resulting string.

`ts
['downcase', string]: string
`

$3

Converts all the alphabetic characters in a string to uppercase and return the resulting string.

`ts
['upcase', string]: string
`

$3

Format a number by specifying the minimum and maximum fraction digits.

`ts
['number-format', number, minimum_fraction_digits, [maximum_fraction_digits]]: string
`

---

Decision expressions

$3

Negates a value and return the resulting boolean.

`ts
['!', value]: boolean
`

$3

Performs strict equality operation and return the resulting boolean.

`ts
['==', value]: boolean
`

$3

Performs strict inequality operation and return the resulting boolean.

`ts
['!=', value]: boolean
`

$3

Returns true if number1 or string1 is less than number2 or string2, otherwise return false.

`ts
['<', number1 | string1, number2 | string2]: boolean
`

$3

Returns true if number1 or string1 is less than or equal to number2 or string2, otherwise return false.

`ts
['<=', number1 | string1, number2 | string2]: boolean
`

$3

Returns true if number1 or string1 is greater than number2 or string2, otherwise return false.

`ts
['>', number1 | string1, number2 | string2]: boolean
`

$3

Returns true if number1 or string1 is greater than or equal to number2 or string2, otherwise return false.

`ts
['>=', number1 | string1, number2 | string2]: boolean
`

$3

Returns true if all the values evaluate to true.

`ts
['all', value1, value2, ...]: boolean
`

$3

Returns true if any of the values evaluate to true.

`ts
['any', value1, value2, ...]: boolean
`

$3

Perform if else operation.

`ts
['if', condition1, output1, condition2, output2, ..., fallback_output]: boolean
`

---

Expression can be nested

Please see the example below:

`ts
// Returns 'equal to two'
exp(['if', ['==', 5, 1], 'equal to one', ['==', 2, 2], 'equal to two', 'failure']);
`

Expression can be injected with data

By specifying a variable using wildcard, we can inject data into the expression.

Please see the example below:

`ts
const expression: Expression = [
'if',
['==', '$animal', 'cat'],
'meow',
['==', '$animal', 'dog'],
'woof',
'Wa-pa-pa-pa-pa-pa-pow!',
];

// Returns 'meow'
exp(expression, { animal: 'cat' });

// Returns 'woof'
exp(expression, { animal: 'dog' });

// Returns 'Wa-pa-pa-pa-pa-pa-pow!'
exp(expression, { animal: 'fox' });
`

Realworld example

Below, we will convert unit from liter per minute into US gallon per hour.

`ts
const data: Data = {
// value contains liter per minute
value: 5,
};

// Returns '79.3 gallon/hour'
exp(
['concat', ['number-format', ['', ['', '$value', 0.2641722], 60], 0, 1], ' ', 'gallon/hour'],
data
);
`

License

array-expression` is MIT licensed.