edwardanthony/array-expression

Formatter declaration that can be transported through network and executed securely.

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:

[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

boolean

Converts value into boolean.

['boolean', value]: boolean

string

Converts value into string.

['string', value]: string

---

Math expressions

+

Performs addition and return the resulting number.

['+', number1, number2]: number

-

Performs subtraction and return the resulting number.

['-', number1, number2]: number

*

Performs multiplication and return the resulting number.

['*', number1, number2]: number

/

Performs division and return the resulting number.

['/', number1, number2]: number

%

Performs remainder operation and return the resulting number.

['%', number1, number2]: number

^

Returns number1 to the power of number2.

['^', number1, number2]: number

sqrt

Returns the square root of a number.

['sqrt', number]: number

abs

Returns the absolute value of a number.

['abs', number]: number

sin

Returns the sine of a number.

['sin', number]: number

cos

Returns the cosine of a number.

['cos', number]: number

tan

Returns the tangent of a number.

['tan', number]: number

log

Returns natural logarithm (base e) of a number.

['log', number]: number

floor

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

['floor', number]: number

ceil

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

['ceil', number]: number

round

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

['round', number]: number

min

Returns the lowest number in the arguments.

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

max

Returns the highest number in the arguments.

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

---

String expressions

concat

Concatenate the arguments into one single string.

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

downcase

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

['downcase', string]: string

upcase

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

['upcase', string]: string

number-format

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

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

---

Decision expressions

!

Negates a value and return the resulting boolean.

['!', value]: boolean

==

Performs strict equality operation and return the resulting boolean.

['==', value]: boolean

!=

Performs strict inequality operation and return the resulting boolean.

['!=', value]: boolean

<

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

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

<=

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

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

>

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

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

>=

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

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

all

Returns true if all the values evaluate to true.

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

any

Returns true if any of the values evaluate to true.

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

if

Perform if else operation.

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

---

Expression can be nested

Please see the example below:

// 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:

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.

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.