Name: vega-expression
Owner: UW Interactive Data Lab
Description: Vega expression parser and code generator.
Forked from: vega/vega-expression
Created: 2016-07-08 16:02:06.0
Updated: 2016-11-26 05:57:25.0
Pushed: 2016-08-10 23:00:43.0
Size: 101
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Vega expression parser and code generator.
Parses a limited subset of JavaScript expressions into an abstract syntax tree, and provides code generation utilities for generating eval'able output code. The parser recognizes basic JavaScript expressions, but does not allow assignment operators, new expressions, or control flow statements (for, while, switch, etc). The configurable code generator further limits the set of allowable function invocations and variable names. The goal is to provide simple, expressive and security-conscious expression evaluation.
The top-level export includes three methods:
parse(input)
Parse the input JavaScript expression string and return the resulting abstract syntax tree in the ESTree (formerly Mozilla AST) format. The parser is based on a stripped-down version of the Esprima parser.
codegen(options)
Create a new output code generator configured according to the provided options. The resulting generator function accepts a parsed AST as input and returns eval'able JavaScript code as output. The output is an object hash with the properties code (the generated code as a string), fields (a hash of all properties referenced within the fieldvar scope), and globals (a hash of all properties referenced outside a provided whitelist).
The supported options include:
constants: A hash of allowed top-level constant values. This object maps from constant names to constant values. The constant values are strings that will be injected as-is into generated code.
functions: A function that is given a code generator instance as input and returns a hash of allowed top-level functions. The resulting hash maps from function names to function values. The values may either be strings (which will be injected as-is into generated code and subsequently appended with arguments) or functions (which take an array of argument AST nodes as input and return generated code to inject).
blacklist: An array of variable names that may not be referenced within the expression scope. These may correspond to disallowed global variables.
whitelist: An array of variable names that may be referenced within the expression scope. These typically correspond to function parameter names for the expression. Variable names not included in the white list will be collected as global variables (see globalvar below).
fieldvar: The name of the primary data input argument within the generated expression function. For example, in the function function(d) { return d.x * d.y; }, the variable d serves as the field variable, and x and y are it's accessed properties. All properties accessed under the scope of fieldvar will be tracked by the code generator and returned as part of the output. This is necessary to perform dependency tracking of referenced data fields.
globalvar: The name of the variable upon which to lookup global variables. This variable name will be included in the generated code as the scope for any global variable references. Alternatively, this property can be a function that maps from variable names in the source input to generated code to write to the output.