A simple, safe, JavaScript expression engine, allowing end-users to enter arbitrary expressions without p0wning you.
category == "meal" and (calories * weight > 2000.0 or subcategory in ("cake", "pie"))There are many cases where you want a user to be able enter an arbitrary expression through a user interface. e.g.
Sure, you could do that with JavaScript and eval(), but I'm sure I don't have to tell you how stupid that would be.
Filtrex defines a really simple expression language that should be familiar to anyone who's ever used a spreadsheet and compile it into a JavaScript function at runtime.
transactions <= 5 and abs(profit) > 20.5function(item) { return item.transactions <=5 && Math.abs(item.profit) > 20.5; }// Input from user (e.g. search filter)
var expression = 'transactions <= 5 and abs(profit) > 20.5';
// Compile expression to executable function
var myfilter = compileExpression(expression);
// Execute function
myfilter({transactions: 3, profit:-40.5}); // returns 1
myfilter({transactions: 3, profit:-14.5}); // returns 0Under the hood, the above expression gets compiled to a clean and fast JavaScript function, looking something like this:
// Resulting function
function(item) {
return item.transactions <= 5 && Math.abs(item.profit) > 20.5;
}There are only 2 types: numbers and strings. Numbers may be floating point or integers. Boolean logic is applied on the truthy value of values (e.g. any non-zero number is true, any non-empty string is true, otherwise false).
| Values | Description |
|---|---|
| 43, -1.234 | Numbers |
| "hello" | String |
| foo, a.b.c, 'foo-bar' | External data variable defined by application (may be numbers or strings) |
| Numeric arithmetic | Description |
|---|---|
| x + y | Add |
| x - y | Subtract |
| x * y | Multiply |
| x / y | Divide |
| x % y | Modulo |
| x ^ y | Power |
| Comparisons | Description |
|---|---|
| x == y | Equals |
| x < y | Less than |
| x <= y | Less than or equal to |
| x > y | Greater than |
| x >= y | Greater than or equal to |
| x ~= y | Regular expression match |
| x in (a, b, c) | Equivalent to (x == a or x == b or x == c) |
| x not in (a, b, c) | Equivalent to (x != a and x != b and x != c) |
| Boolean logic | Description |
|---|---|
| x or y | Boolean or |
| x and y | Boolean and |
| not x | Boolean not |
| x ? y : z | If boolean x, value y, else z |
| ( x ) | Explicity operator precedence |
| Built-in functions | Description |
|---|---|
| abs(x) | Absolute value |
| ceil(x) | Round floating point up |
| floor(x) | Round floating point down |
| log(x) | Natural logarithm |
| max(a, b, c...) | Max value (variable length of args) |
| min(a, b, c...) | Min value (variable length of args) |
| random() | Random floating point from 0.0 to 1.0 |
| round(x) | Round floating point |
| sqrt(x) | Square root |
Operator precedence follows that of any sane language.
When integrating in to your application, you can add your own custom functions.
// Custom function: Return string length.
function strlen(s) {
return s.length;
}
// Compile expression to executable function
var myfilter = compileExpression(
'strlen(firstname) > 5',
{strlen:strlen}); // custom functions
myfilter({firstname:'Joe'}); // returns 0
myfilter({firstname:'Joseph'}); // returns 1Why the name?
Because it was originally built for FILTeR EXpressions.
What's Jison?
Jison is bundled with Filtrex – it's a JavaScript parser generator that does the underlying hard work of understanding the expression. It's based on Flex and Bison.
License?
Unit tests?
What happens if the expression is malformed?
Calling compileExpression() with a malformed expression will throw an exception. You can catch that and display feedback to the user. A good UI pattern is to attempt to compile on each keystroke and continuously indicate whether the expression is valid.
And follow @joewalnes!