Skip to content

Expression parsing and evaluation, as simple as 1 + 1 = 2

License

Notifications You must be signed in to change notification settings

ouropencode/OpenExpression

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

OpenExpression

Expression parsing and evaluation, as simple as 1 + 1 = 2

While building a sweet little project, we came across a small problem: We needed the ability to take a user input "condition string" and evaluate it against a known object. After countless hours of searching, we came up blank and decided that no existing solution satisfied all three of our criteria and decided to build our own library to fill the gap. So here it is, OpenExpression, a simple expression tokenizer, shunter and evaluator all wrapped into one that is:

  1. Small, light-weight and fast.
  2. Capable of accepting a context object with use of variables/symbols from the expression.
  3. Capable of simple expansion with custom tokens.

Using OpenExpression we can feed in a string like a + b and an object like { a: 5, b: 10 } and receive the value 15.

NOTE: By default, OpenExpression doesn't contain any 'method/function'-like functionality and supports nothing like sin()/cos(). You may be better served by a project like math.js if this is your goal.

Installation & Usage

To install OpenExpression, simply run the following:

npm install openexpression --save

After this, OpenExpression can be used from your code using either of the following usage patterns:

Static Usage - for processing a single expression

const OpenExpression = require('openexpression');
console.log(OpenExpression.evaluate('a + b', {
    a: 5,
    b: 10
})); // => 15

Instance Usage - for processing multiple expressions and other advanced functionality

const OpenExpression = require('openexpression');
let parser = new OpenExpression();
console.log(parser.evaluate('a + b', {
    a: 5,
    b: 10
})); // => 15
console.log(parser.evaluate('a < b && b < 20 && a != 0', {
    a: 5,
    b: 10
})); // => true

Expression Reference

Example Result Precedence
Types Integer 5 5 P_ZERO
Float 1.35 1.35 P_ZERO
String "TEST" "TEST" P_ZERO
RegExp #t[es]{2}t#i /t[es]{2}t/i P_ZERO
Math + (Add) 2 + 4 6 P_TERM
- (Subtract) 5 - 2 3 P_TERM
* (Multiply) 3 * 4 12 P_FACTOR
/ (Divide) 9 / 3 3 P_FACTOR
Comparison == (Equal) 3 == 3 true P_COMP
5 == 3 false
!= (Not Equal) 5 != 3 true P_COMP
5 != 5 false
>= (Greater Than or Equal) 5 >= 3 true P_COMP
3 >= 3 true
1 >= 3 false
<= (Less Than or Equal) 3 <= 5 true P_COMP
3 <= 3 true
5 <= 3 false
~= (RegExp Match) "TEST" ~= #t[es]{2}t#i true P_COMP
&& (Logical AND) true && true true P_BOOL
true && false false
|| (Logical OR) true || false true P_BOOL
false || false false
Brackets ( and ) (3 + 2) * (6 - 4) 10 B_BRACKET

NOTE: Strings are only supporting using double-quotes ("), there is no single-quote support.

Precedence

All expressions are shunted before evaluations to arrange the tokens for execution. During this stage we calculate the order of operations (known as the Precedence). Operators with a lower precedence are evaluated first. Precedence can be modified using brackets, operations within brackets will be evaluated first. Precedence is defined using a set of constant integers (exposed as OpenExpression.Precedence) spaced by 10, this allows any custom tokens to be defined anywhere amongst the existing tokens. Below are the values at time of writing:

Constant Value
P_ZERO 0
P_VALUE 10
P_BRACKET 20
P_BOOL 30
P_COMP 40
P_TERM 50
P_FACTOR 60

API Reference

[mixed] OpenExpression.evaluate(expression, context = {}, deepOuput = false)

  • [string] expression: the expression to evaluate
  • [object] context: an object containing the symbol context
  • [bool] deepOuput: should we return in-depth data, instead of the return value (see below)

A simple interface for one-time evaluation of an expression. This will simply return the response of the expression using the symbol context provided. If multiple expressions are to be evaluated, it's advised to create an instance (const instance = new OpenExpression()) and operate using instance.evaluate.

[mixed] instance.evaluate(expression, context = {}, deepOuput = false)

  • [string] expression: the expression to evaluate
  • [object] context: an object containing the symbol context
  • [bool] deepOuput: should we return in-depth data, instead of the return value

Returns the response of the expression using the symbol context provided. If deepOutput is set to true, you will receive an object as a response, this object will contain the return value alongside additional information:

Key Value
value [mixed] contains the return value
aborted [bool] was the evaluation aborted during execution?
aborted_value [mixed] the value returned when aborting. (this is for non-error aborts, errors throw instead)
stack [array] the full contents of the stack.

[array] instance.tokenize(expression)

  • [string] expression: the expression to tokenize

Parse an expression into an array of tokens.

[array] instance.shunt(tokens)

  • [array] tokens: an array of tokens to shunt

Shunt an array of tokens using an implementation of Edsger Wybe Dijkstra's Shunting Yard Algorithm. This arranges the tokens in a much more useful format for execution.

[array] instance.execute(tokens, context = {}, deepOuput = false)

  • [array] tokens: an array of shunted tokens to execute
  • [object] context: an object containing the symbol context
  • [bool] deepOuput: should we return in-depth data, instead of the return value

Execute and return the response from an array of shunted tokens using the symbol context provided.

[void] instance.addToken(token)

  • [object] token: the token description Add a custom token for parsing/execution. The token must be an instance of a custom class that extends the 'Token' class described below. Additional base classes are available that make this slightly easier: TokenABOperator for creating tokens that operate upon two values in the stack (addition/subtraction/etc make use of this) and TokenValue for creating tokens that are purely values. You should check the existing tokens in the ./src/Tokens/ folder for more examples of how a Token is structured.
import {OpenExpression, Token, Precedence} from 'OpenExpression';

export default class CUSTOM_TOKEN extends Token {

    constructor() {
        super(/regex_pattern_to_match/, Precedence.P_ZERO);
    }

	shunt(token, stack, output) {
        // [.. shunt ..]
	}

    shuntEnd(token, stack, output) {
        // [.. shunt when left on stack ..]
    }

    operate(token, stack, context, abort) {
		// [.. operate ..]
    }

}

// usage:
const OpenExpression = require('openexpression');
let parser = new OpenExpression();
parser.addToken(new CUSTOM_TOKEN());
// now you may use your token in an .evaluate call

Tests

OpenExpression has a test suite that tests all basic functionality works as expected. If you find any exceptional cases that break the library, let us know about it and we'll make another test and try to fix it! Tests are written using the (Buster.JS)[http://busterjs.org] testing toolkit. Tests can be run with the following commands:

npm install openexpression --only=dev
npm test

Contributing

Get involved! OpenExpression is currently a small project, maintained by a small team. We would welcome any contributions to the codebase, either via Issues or Pull Requests.

Maintainers

  • Peter Corcoran (R4wizard)

License, Copyright & Credits

OpenExpression is an open source project licensed under the LGPLv3 licenses, you can find more details regarding this license in the LICENSE.md file.

This library was created using the following resources as inspiration and reference material:

About

Expression parsing and evaluation, as simple as 1 + 1 = 2

Resources

License

Stars

Watchers

Forks

Packages

No packages published