Skip to content

Latest commit

 

History

History
249 lines (177 loc) · 5.95 KB

parser.md

File metadata and controls

249 lines (177 loc) · 5.95 KB

Parser

Audience: Developers integrating expr-eval into their projects.

The Parser class is the main entry point for parsing and evaluating expressions.

Quick Start

import { Parser } from '@pro-fa/expr-eval';

// Create a parser instance
const parser = new Parser();

// Parse and evaluate in one step
const result = Parser.evaluate('2 * x + 1', { x: 3 }); // 7

// Or parse once and evaluate multiple times
const expr = parser.parse('2 * x + 1');
expr.evaluate({ x: 3 }); // 7
expr.evaluate({ x: 5 }); // 11

Constructor

const parser = new Parser(options?);

Options

Option Type Description
operators object Enable/disable specific operators (see table below)

Operator Configuration

All operators default to true (enabled) except where noted:

Option Key Default Operators Affected
add true + (addition)
subtract true - (subtraction)
multiply true * (multiplication)
divide true / (division)
remainder true % (modulo)
power true ^ (exponentiation)
factorial true ! (factorial)
concatenate true | (array/string concatenation)
conditional true ? : (ternary) and ?? (coalesce)
logical true and, or, not
comparison true ==, !=, <, >, <=, >=
in false in, not in
assignment false = (variable assignment)
fndef true Function definitions and arrow functions
conversion false as (type conversion)

Example: Restricted Parser

const parser = new Parser({
  operators: {
    // Disable logical and comparison
    logical: false,
    comparison: false,
    
    // Enable 'in' operator
    in: true,
    
    // Enable assignment
    assignment: true
  }
});

Instance Methods

parse(expression: string)

Convert an expression string into an Expression object.

const expr = parser.parse('x * 2 + y');

Returns an Expression object with methods like evaluate(), simplify(), variables(), etc.

evaluate(expression: string, variables?: object)

Parse and immediately evaluate an expression.

parser.evaluate('x + y', { x: 2, y: 3 }); // 5

Static Methods

Parser.parse(expression: string)

Static equivalent of new Parser().parse(expression).

const expr = Parser.parse('x + 1');

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

Parse and immediately evaluate an expression. Equivalent to Parser.parse(expr).evaluate(vars).

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

Instance Properties

parser.functions

An object containing all available functions. You can add, modify, or remove functions:

const parser = new Parser();

// Add a custom function
parser.functions.double = (x) => x * 2;

// Add a function that returns a Promise (makes evaluate async)
parser.functions.fetchValue = async (id) => {
  const response = await fetch(`/api/values/${id}`);
  return response.json();
};

// Remove a built-in function
delete parser.functions.random;

// Use custom function
parser.evaluate('double(5)'); // 10

// Async evaluation
await parser.evaluate('fetchValue(123) * 2');

parser.consts

An object containing all available constants. You can add, modify, or remove constants:

const parser = new Parser();

// Add custom constants
parser.consts.TAU = Math.PI * 2;
parser.consts.GOLDEN_RATIO = 1.618033988749;

// Use in expressions
parser.evaluate('TAU'); // 6.283185307179586
parser.evaluate('2 * PI'); // 6.283185307179586 (PI is built-in)

// Remove all built-in constants
parser.consts = {};

Built-in Constants:

Constant Value
E Math.E (~2.718)
PI Math.PI (~3.14159)
true true
false false

parser.resolve

A callback for custom variable name resolution. Called when a variable name is not found in the provided variables object.

const parser = new Parser();
const data = { variables: { a: 5, b: 10 } };

// Alias resolution: $v becomes 'variables'
parser.resolve = (name) => {
  if (name === '$v') {
    return { alias: 'variables' };
  }
  return undefined;
};

parser.evaluate('$v.a + $v.b', data); // 15

// Value resolution: return the value directly
parser.resolve = (name) => {
  if (name.startsWith('$')) {
    const key = name.substring(1);
    return { value: data.variables[key] };
  }
  return undefined;
};

parser.evaluate('$a + $b', {}); // 15

The resolve callback should return:

  • { alias: string } - to redirect to another variable name
  • { value: any } - to return a value directly
  • undefined - to use default behavior (throws error for unknown variables)

Advanced Configuration

Type Conversion (as operator)

The as operator is disabled by default. When enabled, it provides basic type conversion:

const parser = new Parser({ operators: { conversion: true } });

parser.evaluate('"1.6" as "number"');   // 1.6
parser.evaluate('"1.6" as "int"');      // 2 (rounded)
parser.evaluate('"1.6" as "integer"');  // 2 (rounded)
parser.evaluate('"1" as "boolean"');    // true

You can override the default as implementation:

parser.binaryOps.as = (value, type) => {
  // Custom conversion logic
  if (type === 'date') {
    return new Date(value);
  }
  return value;
};

Operator Customization

You can customize binary and unary operators via parser.binaryOps and parser.unaryOps:

const parser = new Parser();

// Add a custom binary operator
parser.binaryOps['%%'] = (a, b) => ((a % b) + b) % b; // Positive modulo

// Note: Custom operators must be registered before parsing

See Also