@nbxx/nb-expr-eval v2.0.2001

JavaScript Expression Evaluator

This is a modified version of https://github.com/silentmatt/expr-eval 这是基于Matthew Crumley的expr-eval修改而成。

Description

处理数学表达式和有限的字符串、日期

支持的运算符、函数见后表

安装

npm install @nbxx/nb-expr-eval

基本用法

    var Parser = require('@nbxx/nb-expr-eval').Parser;

    var parser = new Parser();
    var expr = parser.parse('2 * x + 1');
    console.log(expr.evaluate({ x: 3 })); // 7

    // or
    Parser.evaluate('6 * x', { x: 7 }) // 42

使用文档

• Parser
  • Parser()
  • parse(expression: string)
  • Parser.parse(expression: string)
  • Parser.evaluate(expression: string, variables?: object)
• Expression
  • evaluate(variables?: object)
  • substitute(variable: string, expression: Expression | string | number)
  • simplify(variables: object)
  • variables(options?: object)
  • symbols(options?: object)
  • toString()
  • toJSFunction(parameters: array | string, variables?: object)
• Expression Syntax
  • Operator Precedence
  • Unary operators
  • Array literals
  • Pre-defined functions
  • Custom JavaScript functions
  • Constants

解析器

核心，包含 parse 方法及一些静态方法用于解析表达式。

Parser()

构造一个新的 Parser 实例。

构造器可以接受一个可选的 options 参数。

下面的例子会创建一个不允许比较，也不允许逻辑运算符，但允许 in 运算符的解析器：

    var parser = new Parser({
      operators: {
        // 默认开启，也可以手动关闭
        add: true,
        concatenate: true,
        conditional: true,
        divide: true,
        factorial: true,
        multiply: true,
        power: true,
        remainder: true,
        subtract: true,

        // 关闭逻辑运算，包含： and, or, not, <, ==, !=, 等等
        logical: false,
        comparison: false,

        // 关闭 in 以及 = 操作符
        'in': false,
        assignment: false
      }
    });

parse(expression: string)

把表达式解析为 Expression 对象

Parser.parse(expression: string)

new Parser().parse(expression) 的静态等价方法

Parser.evaluate(expression: string, variables?: object)

使用 variables 对象中的变量和方法来解析、计算表达式

Parser.evaluate(expr, vars) 等价于 Parser.parse(expr).evaluate(vars).

Expression

Parser.parse(str) 返回一个 Expression 对象， Expression 对象与 js 函数很相似，实际上也可以被直接转换为函数。

evaluate(variables?: object)

使用 variables 中的变量来计算 expression 对象, 如果有变量未被解析，则抛出异常。

    js> expr = Parser.parse("2 ^ x");
    (2^x)
    js> expr.evaluate({ x: 3 });
    8

substitute(variable: string, expression: Expression | string | number)

使用 expression 来替换原有 expression 中的 variable。

    js> expr = Parser.parse("2 * x + 1");
    ((2*x)+1)
    js> expr.substitute("x", "4 * x");
    ((2*(4*x))+1)
    js> expr2.evaluate({ x: 3 });
    25

simplify(variables: object)

使用 variables 来替换表达式中的变量，从而简化表达式。函数不会被替换和简化。

实际上simplify只是简单的把变量替换了一下，然后将常数直接计算出结果。 所以 ((2*(4*x))+1) 是没法直接简化的，除非替换 x 。但是 2*4*x+1 是可以简化的， 因为它等价于(((2*4)*x)+1), 所以 (2*4) 会被简化为 "8", 生成结果 ((8*x)+1).

    js> expr = Parser.parse("x * (y * atan(1))").simplify({ y: 4 });
    (x*3.141592653589793)
    js> expr.evaluate({ x: 2 });
    6.283185307179586

variables(options?: object)

列出当前表达式中尚未被简化替换的变量。.

    js> expr = Parser.parse("x * (y * atan(1))");
    (x*(y*atan(1)))
    js> expr.variables();
    x,y
    js> expr.simplify({ y: 4 }).variables();
    x

variables 默认只返回最顶层的变量，例如 Parser.parse(x.y.z).variables() 返回 ['x']。 如果希望获得细节，可以使用 { withMembers: true }，随后 Parser.parse(x.y.z).variables({ withMembers: true }) 将会返回['x.y.z'].

symbols(options?: object)

获取尚未简化的变量，以及所有函数

    js> expr = Parser.parse("min(x, y, z)");
    (min(x, y, z))
    js> expr.symbols();
    min,x,y,z
    js> expr.simplify({ y: 4, z: 5 }).symbols();
    min,x

与 variables 相似, symbols 接受可选参数 { withMembers: true } 来显示对象成员.

toString()

将表达式转化为字符串 toString() 将自动添加括号。.

toJSFunction(parameters: array | string, variables?: object)

把 Expression 转换为js函数。 parameters 是参数名列表（Array），或者参数名字符串（逗号分隔的列表）

如果提供了可选参数 variables 表达式将会被简化。

    js> expr = Parser.parse("x + y + z");
    ((x + y) + z)
    js> f = expr.toJSFunction("x,y,z");
    [Function] // function (x, y, z) { return x + y + z; };
    js> f(1, 2, 3)
    6
    js> f = expr.toJSFunction("y,z", { x: 100 });
    [Function] // function (y, z) { return 100 + y + z; };
    js> f(2, 3)
    105

表达式语法

基本上和js语法差不多，除了部分运算符为数学表达式外。例如： ^ 运算符代表指数函数，而不是异或。

运算符优先级（从上到下依次递减）

"in" 和 = 两个运算符默认关闭，需要显式开启才能使用

    const parser = new Parser({
      operators: {
        'in': true,
        'assignment': true
      }
    });
    // 现在可以使用 'x in array' 和 'y = 2*x' 两种表达式了

一元运算符

解析器包含一些内置函数，实际上会作为一元运算符来使用。他们和预定义函数的区别是他们只接受一个参数， 而且不需要括号包围起来。包含括号的一元运算符优先级和函数一致，不包含括号的一元运算符优先级按运算符优先级来计算（低于 '^'）。 例如，sin(x)^2 等价于 (sin x)^2, 而 sin x^2 等价于 sin(x^2)。 + 和 - 两种一元运算符是例外，因为不存在对应的函数，所以优先级始终按运算符优先级来计算。

预定义函数

除了运算符外，还有一些预定义的函数。预定义函数不会被 simplify 处理

列表处理

列表能直接使用 [] 定义，例如： 1, 2, 3, 2+2, 10/2, 3!

自定义函数

可以使用 name(params) = expression 的格式来自定义函数。函数支持多参数

Examples:

    square(x) = x*x
    add(a, b) = a + b
    factorial(x) = x < 2 ? 1 : x * factorial(x - 1)

自定义 js 函数

parser 有一个属性 functions ，记录了所有的函数。如果想要在全局的角度自定义函数，只需要添加即可

    const parser = new Parser();

    // Add a new function
    parser.functions.customAddFunction = function (arg1, arg2) {
      return arg1 + arg2;
    };

    // Remove the factorial function
    delete parser.functions.fac;

    parser.evaluate('customAddFunction(2, 4) == 6'); // true
    //parser.evaluate('fac(3)'); // This will fail

预定义常量

以下是预定义的常量:

与函数类似，预定义常量也保存在 parser 属性中。可以随意在 parser.consts 中添加自定义的常量。比如：

    const parser = new Parser();
    parser.consts.R = 1.234;

    console.log(parser.parse('A+B/R').toString());  // ((A + B) / 1.234)

To disable the pre-defined constants, you can replace or delete parser.consts:

    const parser = new Parser();
    parser.consts = {};

Tests

1. cd to the project directory
2. Install development dependencies: npm install
3. Run the tests: npm test