JSON-FP comes with built-in operators. These operators are categorized into 5 different groups.
The core group provides the minimum operators for a JSON-FP runtime.
This is the shorthand notation of the "chain operator" which is explained below.
The chain operator can take an array of JSON-FP expressions and sequentially evaluate each expression with each operator taking its input from the output of its predecessor. Its syntax is as: [{op1: option1}, {op2: option2}, ...{opN, optionN}]. The output of a chain operator is the output of the last operator in the chain.
Release 0.0.8 makes '->' the alias of 'chain', so
{chain: [
{getter: 'salary'},
{'>': 100000}
]}
is the same as
{'->': [
{getter: 'salary'},
{'>': 100000}
]}
The convert operator can be used to perform variable substitutions (this is actually JSON-FP's way of suppoting the alpha-conversion in lamda calculus). The convert option has the following properties:
- var: this property value contains the mapping between each substitutable variable and its value.
- formula: the formula expression defined by the formula operator. See below about how to define a formula.
Example:
var f = {
formula: {
var: ['@prop'],
expr: {getter: '@prop'}
}
};
var expr = {
convert: {
var: {'@prop': 'name'},
formula: f
}
},
input = {
name: 'John',
title: 'CEO'
},
result = jsonfp.apply(input, expr);
The above example will take the name property from the input object, so the result will be 'John'.
The formula operator can be used to define a formula. A formula is a JSON-FP expression with substitutable variables. By subsittuting variables in a JSON-FP expression, we'll be able to convert a formula into various expressions suitable for different tasks. A formula expression is usually in the following format:
{
formula: {
var: ['@prop1', '@prop2', ...],
expr: {
op1: '@prop1'
}
}
}
That is the option to the formula operator is another JSON object with var and expr properties. The var property should be an array of substitutable variable names. It's recommended to put a '@' sign in front of the variable name so we can easily identify them as substitutable variables. The expr property is the JSON-FP expression containing variables to be substituted.
This operator will iterate through every property of its option and try to evaluate each property as a JSON-FP expression. Note that JSON-FP will automatically evaluate option so the eval operator is not needed in most cases. It will be used mostly in meta-programming. For example, evaluating a JSON-FP expression produced by alpha-conversion like: {eval: {convert: {...}}.
indicates a conditional statement as described in the option. option should be an array with at least two elements. The first element (JSON-FP expression) in the array is the conditional expression. The second element (JSON-FP expression) is the expression to be evaluated when the condition is true, and the third element (JSON-FP expression) will be evaluated when the condition is false. The third element can be missing if the else statement is not needed.
When the else expression is not needed, the input will be the return value of this if expression.
This operator will take each element of the input array and apply it to the given JSON-FP expression.
This operator will add option to input. The order may be important when adding strings. It's input + option.
The subtract operator subtracts option from input. It only support numeric values.
Multiplying input with option. Both operands should be numeric values.
Dividing input by option.
Returning a random number by calling Math.random().
Returning the minimum of input and option.
Returning the maximum of input and option.
This operator will return the logical "and" of input and option. However, if input is an object and option is an array of strings, each element of the option array will be used as the property key to the input object and logical "and" is applied on property values. For example, consider the following sample code:
var input = {'name: 'David', 'age': 28, 'isMarried': false},
expr = {and: ['age', 'isMarried'];
var result = jsonfp.apply(input, expr);
The result should be false because (28 && false) should yield false.
This operator will return the logical "or" of input and option. Similar to the "and" operator, if input is an object and option is an array of strings, each element of the option array will be used as the property key to the input object and logical "or" is applied on property values.
This operator will return value of bitwise ANDing input and option.
This operator will return value of bitwise ORing input and option.
This operator will return the bitwise exclusive or of input and option.
Returns an array with false values (false, null, 0 or '') removed.
Output an array by excluding all values specified in the option array. Syntax: {difference: [...]}
Flats the input array to be an array of single level.
Intersects the input array with the option array.
This operator returns the first n elements of the input array. n is specified in the option.
Output an array of unique values from the input and option arrays.
Creates an object with keys from the input array and values from the option array.
Cloning the input object.
Returns an array of elements filtered by option. If option is a plain object, the saved element should contain the same property as option. If option is a JSON-FP expression, the input elements will become the input to the JSON-FP expression and the evaluation result will decide if that element will be kept.
Similar to filter except that the first matched element will be returned.
Returns a property value of an input object. For example:
var input = {
project: 'JSON-FP',
language: 'Javascript'
},
expr = {getter: 'language'};
var result = jsonfp.apply(input, expr);
The result is 'Javascript'.
This operator will recursively merge the option object into the input object.
Creates an object by removing properties specified by option from the input object. Besides being a string value, option can also be a JSON-FP expression. If option is a JSON-FP expression, the omit operator will iterate every key/value pair of the input object, and send the pair as input to the JSON-FP expression. Below is an example:
var data = {name: 'David', project: 'newsql', age: 42},
expr = {omit:
{chain: [
{getter: 'key'},
{'==': 'project'}
]}
},
result = jsonfp.apply( data, expr );
In the above example, the {chain: ...} expression will be invoked three times with each time receving input as {key: 'name', value: 'David'}, {key: 'project', value: 'newsql'} and {key: 'age', value: 42} respectively. The execution result will be {name: 'David', age: 42}.
This operator creates a new object with properties specified in the option. Option can be a single string of an array of strings.
retrieves a property from the input. The property name is specified in option.
This operator performs the reduce funtion. option is usually a JSON-FP expression. Starting from v0.0.8, you can simply use an operator name to replace the intended JSON-FP expression. That is:
{reduce:
add: '$reduceValue'
}
is now the same as:
{reduce: 'add'}
This operator returns the size of the input collection (array).
This operator will perform deep comparison on each element with the option object and returns those elements having the equivalent property value as the option object.
This operator compares if input and option is equivalent (don't have to be identical).
Checking if input and option are not equal.
if input is greater than option.
if input is greater than or equal to option.
if input is less than option.
if input is less than or equal to option.
If the above description is too brief, you may want to refer Lo-Dash documentation. Most array and collection operators listed above are realized by Lo-Dash.