xex
v0.1.0
Published
Lightweight and extensible math-like expression parser and compiler.
Downloads
1
Maintainers
Readme
xex.js
Lightweight and extensible math-like expression parser and compiler.
- Official Repository (exjs/xex)
- Official Chat (gitter)
- Official Fiddler
- Public Domain (https://unlicense.org)
Introduction
xex.js is a lightweight library that provides API to parse mathematic-like expressions and to compile them into javascript functions of user-provided signatures. The library was designed to be small, hackable, and embeddable in other projects - it has no dependencies and all functionality fits into a single file. It was primarily designed for xschema library to provide support for expression constraints and access control rules, but since the library has much more use-cases it was separated from the original project.
The expression is internally represented as AST, unlike many other expression evaluators that use postfix notation. The reason to use AST was to make the library friendly for implementing new features. The library currently provides nearly full access to JS Math
functionality with some additional features. It treats all variables as numbers and is currently designed to work only with numbers - that's it, no user-defined types, objects, etc...
The library can be probably extended in the future to provide more built-in functions and features - pull requests that add useful functionality to xex
are more than welcome!
Basic Usage
Simple example:
const xex = require("xex");
// Create the `Expression` instance:
const exp = xex.exp("sin(x) * cos(y)");
console.log(exp instanceof xex.Expression);
// Root node of the expression's AST.
// {
// type: "Binary",
// name: "*",
// info: {...},
// left: {
// type: "Call",
// name: "sin" ,
// info: {...} ,
// args: [...] }
// },
// right: {
// type: "Call",
// name: "cos" ,
// info: {...} ,
// args: [...] }
// }
// }
console.log(exp.root);
// Map of all variables the expression uses:
// {
// x: <node> ,
// y: <node>
// }
console.log(exp.vars);
// Call the compiled function with `args`:
// 0.46452135963892854
const args = { x: 0.5, y: 0.25 };
console.log(exp.eval(args));
// The default compiled function is not bound to the
// expression, you can steal it and use it anywhere:
// 0.46452135963892854
const f = exp.eval;
console.log(f({ x: 0.5, y: 0.25 }));
By default the compiled expression expects a single argument, which is an object where each property describes a variable inside the expression. Expressions are not static in most cases and there are currently two ways of checking whether the expression contains invalid variables:
- Validating
exp.vars
after the expression was parsed (ideal for inspecting) - Using a variable whitelist (ideal for compiling user-defined expressions)
For example if the expression can use only variables x
and y
it's better to use the whitelise:
// Values don't matter, only keys are important.
const whitelist = { x: true, y: 0 };
const exp0 = xex.exp("sin(x) * cos(y)", { varsWhitelist: whitelist }); // Ok.
const exp1 = xex.exp("sin(z) * cos(w)", { varsWhitelist: whitelist }); // Throws ExpressionError.
If you need a different signature, for example a function where the first parameter is x
and the second parameter y
, you can compile it as well:
const exp = xex.exp("sin(x) * cos(y)");
const fn = exp.compile(["x", "y"]);
console.log(fn(0.5, 0.25));
When the expression is compiled this way it checks all variables and will throw if it uses a variable that is not provided. The xex.exp()
may throw as well, so it's always a good practice to enclose it in try-catch
block:
var fn;
try {
fn = xex.exp("sin(x) * cos(y) + z").compile(["x", "y"]);
}
catch (ex) {
// Exception should always be `ExpressionError` instance.
console.log(ex instanceof xex.ExpressionError);
// ERROR: Variable 'z' used, but no mapping provided
console.log(`ERROR: ${ex.message}`);
}
The ExpressionError
instance also contains a position
, which describes where the error happened if it was a parser error:
try {
xex.exp("a : b");
}
catch (ex) {
// ERROR: Unexpected token ':' at 2
console.log(`ERROR: ${ex.message} at ${ex.position}`);
}
The position
describes an index of the first token character from the beginning of the input. If the expression has multiple lines then you have to count lines and columns manually.
By default the expression is simplified (constant folding). If you intend to process the expression tree and would like to see all nodes you can disable it, or trigger it manually:
// Create the `Expression` instance without a constant folding pass.
const exp = xex.exp("sin(0.6) + cos(0.5) + x", { noFolding: true });
// Traverse the parsed expression tree.
// {
// ...
// }
console.log(JSON.stringify(exp.root, null, 2));
// Trigger constant folding manually - you can substitude variables with constants.
exp.fold({ x: 1 });
// 2.442225035285408
console.log(JSON.stringify(exp.root, null, 2));
Extending Guide
The library can be extended by user-defined constants, operators, and functions. The base environment xex
is frozen and cannot be extended, however, it can be cloned and the clone can be then used the same way as xex
:
// Clone the base environment and add some constants (can be chained).
const env = xex.clone()
.addConstant({ name: "ONE", value: 0 })
.addConstant("ANSWER_TO_LIFE", 42) // Simplified syntax.
// Adding functions always require passing the definition:
env.addFunction({
name: "sum" // Required: Function name, must be a valid identifier name.
args: 1, // Required: Number of arguments or minimum number of arguments.
amax: Infinity // Optional: Maximum number of arguments, can be Infinity.
safe: true, // Optional: Evaluation has no side effects (default false).
eval: function() {
var x = 0;
for (var i = 0; i < arguments.length; i++)
x += arguments[i];
return x;
}
});
// The custom environment `env` acts as `xex`:
// 43
const exp = env.exp("sum(ANSWER_TO_LIFE, ONE)")
console.log(exp.eval());
The safe
option is pessimistic by default (false), so it's a good practice to always provide it depending on the function you are adding. If your custom function has side effects or returns a different answer every time it's called (like Math.random()
) then it must not be considered safe. Safe functions can be evaluated by constant folding of all their arguments are known (constants or already folded expressions).
Extending operators is similar to extending functions with some minor differences: operators associativity and precedence:
const env = xex.clone();
// Use addUnary() or addBinary() to add new operators.
env.addBinary({
name: "**", // Required: Name - Cannot conflict with identifier characters.
prec: 2, // Required: Precedence - less means higher precedence.
rtl : true, // Optional: Associativity - Right (true) or left (false, default).
safe: true, // Optional: Evaluation has no side effects (default false).
eval: Math.pow
});
console.log(env.exp("2 ** 3" ).eval()); // 8
console.log(env.exp("2 ** 3 ** 2" ).eval()); // 512
console.log(env.exp("(2 ** 3) ** 2").eval()); // 64
Built-In Features
- Unary operators:
- Negate
-(x)
- Not
!(x)
- Negate
- Arithmetic operators:
- Assignment
x = y
- Addition
x + y
- Subtraction
x - y
- Multiplication
x * y
- Division
x / y
- Modulo
x % y
- Assignment
- Comparison operators:
- Equal
x == y
- Not equal
x != y
- Greater
x > y
- Greater or equal
x >= y
- Lesser
x < y
- Lesser or equal
x <= y
- Equal
- Language constructs:
- Ternary if-else
condition ? taken : not-taken
- Ternary if-else
- Functions:
- Check for NaN
isnan(x)
- Check for infinity
isinf(x)
- Check for finite number
isfinite(x)
- Check for integer
isint(x)
- Check for safe integer
issafeint(x)
- Check for binary equality
isequal(x, y)
isequal(0, -0)
->0
isequal(42, 42)
->1
isequal(NaN, NaN)
->1
- Check between
isbetween(x, min, max)
- returns
0
ifx
isNaN
- returns
- Clamp
clamp(x, min, max)
- returns
NaN
ifx
isNaN
- returns
- Sign
sign(x)
sign(0)
->0
sign(-0)
->-0
sign(NaN)
->NaN
- Round to nearest
round(x)
round(2.5)
->3
- Truncate
trunc(x)
- Floor
floor(x)
- Ceil
ceil(x)
- Absolute value
abs(x)
- Exponential
exp(x)
- Exponential minus one
expm1(x)
- the same as
exp(x) - 1
, but more precise.
- the same as
- Logarithm
log(x)
- Logarithm plus one
logp1(x)
- the same as
log(x + 1)
, but more precise.
- the same as
- Logarithm of base 2
log2(x)
- Logarithm of base 10
log10(x)
- Square root
sqrt(x)
- Cube root
cbrt(x)
- Fraction
frac(x)
- Sine
sin(x)
- Cosine
cos(x)
- Tangent
tan(x)
- Hyperbolic sine
sinh(x)
- Hyperbolic cosine
cosh(x)
- Hyperbolic tangent
tanh(x)
- Arcsine
asin(x)
- Arccosine
acos(x)
- Arctangent
atan(x)
- Arctangent
atan2(x, y)
- Hyperbolic arcsine
asinh(x)
- Hyperbolic arccosine
acosh(x)
- Hyperbolic arctangent
atanh(x)
- Power
pow(x, y)
- Square root of the sum of squares
hypot(x, y)
- Min/max
min(x, y...)
andmax(x, y...)
- returns
NaN
if one or more argument isNaN
- returns
- Min/max value
minval(x, y...)
andmaxval(x, y...)
- skips
NaN
values, only returnsNaN
if all values areNaN
- skips
- Check for NaN
- Constants:
- Infinity
Infinity
- Not a Number
NaN
- PI
PI = 3.14159265358979323846
- Infinity