@jbrowse/jexl 3.0.1 → 3.1.0

package/src/Jexl.ts

@@ -4,12 +4,16 @@
  */
 
 import Expression from './Expression.ts'
+import Lexer from './Lexer.ts'
 import { getGrammar } from './grammar.ts'
 
-interface Grammar {
-  elements: Record<string, any>
-  functions: Record<string, (...args: any[]) => any>
-}
+import type {
+  BinaryOpEval,
+  BinaryOpEvalOnDemand,
+  Grammar,
+  GrammarElement
+} from './grammar.ts'
+import type { JexlValue } from './types.ts'
 
 /**
  * Jexl is the Javascript Expression Language, capable of parsing and
@@ -19,9 +23,13 @@ interface Grammar {
  */
 class Jexl {
   _grammar: Grammar
+  // shared by every Expression this instance creates, so that the expensive
+  // element-splitting regex is built once rather than per compile
+  _lexer: Lexer
 
   constructor() {
     this._grammar = getGrammar()
+    this._lexer = new Lexer(this._grammar)
     this.expr = this.expr.bind(this)
   }
 
@@ -47,14 +55,33 @@ class Jexl {
   addBinaryOp(
     operator: string,
     precedence: number,
-    fn: (left: any, right: any) => any,
+    fn: BinaryOpEval,
+    manualEval?: false
+  ): void
+  addBinaryOp(
+    operator: string,
+    precedence: number,
+    fn: BinaryOpEvalOnDemand,
+    manualEval: true
+  ): void
+  addBinaryOp(
+    operator: string,
+    precedence: number,
+    fn: BinaryOpEval | BinaryOpEvalOnDemand,
     manualEval?: boolean
   ) {
-    this._addGrammarElement(operator, {
-      type: 'binaryOp',
-      precedence: precedence,
-      [manualEval ? 'evalOnDemand' : 'eval']: fn
-    })
+    // the overloads above pair `fn` with `manualEval`; the implementation
+    // signature can't express that correlation, hence the assertions
+    this._addGrammarElement(
+      operator,
+      manualEval
+        ? {
+            type: 'binaryOp',
+            precedence,
+            evalOnDemand: fn as BinaryOpEvalOnDemand
+          }
+        : { type: 'binaryOp', precedence, eval: fn as BinaryOpEval }
+    )
   }
 
   /**
@@ -65,7 +92,7 @@ class Jexl {
    *      expression function is invoked. It will be provided with each argument
    *      supplied in the expression, in the same order.
    */
-  addFunction(name: string, fn: (...args: any[]) => any) {
+  addFunction(name: string, fn: (...args: JexlValue[]) => JexlValue) {
     this._grammar.functions[name] = fn
   }
 
@@ -75,7 +102,7 @@ class Jexl {
    * function counterpart.
    * @param {{}} map A map of expression function names to javascript functions
    */
-  addFunctions(map: Record<string, (...args: any[]) => any>) {
+  addFunctions(map: Record<string, (...args: JexlValue[]) => JexlValue>) {
     Object.assign(this._grammar.functions, map)
   }
 
@@ -87,10 +114,10 @@ class Jexl {
    *      will be called with one argument: the literal value to the right of the
    *      operator. It should return the resulting value.
    */
-  addUnaryOp(operator: string, fn: (right: any) => any) {
+  addUnaryOp(operator: string, fn: (right: JexlValue) => JexlValue) {
     this._addGrammarElement(operator, {
       type: 'unaryOp',
-      weight: Infinity,
+      precedence: Infinity,
       eval: fn
     })
   }
@@ -115,7 +142,7 @@ class Jexl {
    * @returns {Expression} The Expression object representing the given string
    */
   createExpression(expression: string) {
-    return new Expression(this._grammar, expression)
+    return new Expression(this._grammar, expression, this._lexer)
   }
 
   /**
@@ -146,12 +173,21 @@ class Jexl {
    * @param {Array<string>} strs
    * @param  {...any} args
    */
-  expr(strs: TemplateStringsArray, ...args: any[]) {
+  expr(strs: TemplateStringsArray, ...args: JexlValue[]) {
     let exprStr = ''
-    for (let idx = 0; idx < strs.length; idx++) {
-      exprStr += strs[idx]
+    for (const [idx, str] of strs.entries()) {
+      exprStr += str
       if (idx < args.length) {
-        exprStr += args[idx]
+        const arg = args[idx]
+        if (
+          typeof arg === 'string' ||
+          typeof arg === 'number' ||
+          typeof arg === 'boolean'
+        ) {
+          exprStr += String(arg)
+        } else if (arg != null) {
+          exprStr += JSON.stringify(arg)
+        }
       }
     }
     return this.createExpression(exprStr)
@@ -163,8 +199,9 @@ class Jexl {
    */
   removeOp(operator: string) {
     const elem = this._grammar.elements[operator]
-    if (elem && (elem.type === 'binaryOp' || elem.type === 'unaryOp')) {
+    if (elem?.type === 'binaryOp' || elem?.type === 'unaryOp') {
       Reflect.deleteProperty(this._grammar.elements, operator)
+      this._lexer._clearCache()
     }
   }
 
@@ -175,8 +212,9 @@ class Jexl {
    *      grammar element
    * @private
    */
-  _addGrammarElement(str: string, obj: any) {
+  _addGrammarElement(str: string, obj: GrammarElement) {
     this._grammar.elements[str] = obj
+    this._lexer._clearCache()
   }
 }
 

package/src/Lexer.ts

@@ -3,12 +3,13 @@
  * Copyright 2020 Tom Shawver
  */
 
-import type { Token } from './types.ts'
+import type { Grammar } from './grammar.ts'
+import type { TemplatePart, Token } from './types.ts'
 
 const numericRegex = /^-?(?:(?:[0-9]*\.[0-9]+)|[0-9]+)$/
 const identRegex =
   /^[a-zA-Zа-яА-Я_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF$][a-zA-Zа-яА-Я0-9_\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF$]*$/
-const escEscRegex = /\\\\/
+const escEscRegex = /\\\\/g
 const whitespaceRegex = /^\s*$/
 const preOpRegexElems = [
   // Template strings
@@ -28,19 +29,22 @@ const postOpRegexElems = [
   // Numerics (without negative symbol)
   String.raw`(?:(?:[0-9]*\.[0-9]+)|[0-9]+)`
 ]
+const unaryMinusToken = (): Token => ({
+  type: 'unaryOp',
+  value: '-',
+  raw: '-'
+})
 const minusNegatesAfter = new Set([
   'binaryOp',
   'unaryOp',
   'openParen',
   'openBracket',
   'question',
-  'colon'
+  'colon',
+  'comma',
+  'semicolon'
 ])
 
-interface Grammar {
-  elements: Record<string, any>
-}
-
 /**
  * Lexer is a collection of stateless, statically-accessed functions for the
  * lexical parsing of a Jexl string.  Its responsibility is to identify the
@@ -60,6 +64,15 @@ class Lexer {
     this._grammar = grammar
   }
 
+  /**
+   * Discards the memoized split regex, so that it is rebuilt on the next
+   * tokenize. Must be called whenever the grammar's elements change, since the
+   * regex is derived from their keys.
+   */
+  _clearCache() {
+    this._splitRegex = undefined
+  }
+
   /**
    * Splits a Jexl expression string into an array of expression elements.
    * @param {string} str A Jexl expression string
@@ -84,19 +97,31 @@ class Lexer {
   getTokens(elements: string[]) {
     const tokens: Token[] = []
     let negate = false
-    for (let i = 0; i < elements.length; i++) {
-      if (this._isWhitespace(elements[i])) {
-        if (tokens.length) {
-          tokens[tokens.length - 1].raw += elements[i]
+    for (const element of elements) {
+      if (this._isWhitespace(element)) {
+        const last = tokens.at(-1)
+        if (last) {
+          last.raw += element
         }
-      } else if (elements[i] === '-' && this._isNegative(tokens)) {
-        negate = true
-      } else {
+      } else if (element === '-' && this._isNegative(tokens)) {
+        // a second prefix minus in a row ("- -x"): emit the pending one as a
+        // unary operator so this one can negate whatever comes next
         if (negate) {
-          elements[i] = '-' + elements[i]
-          negate = false
+          tokens.push(unaryMinusToken())
+        }
+        negate = true
+      } else if (negate) {
+        negate = false
+        if (numericRegex.exec(element)) {
+          // fold the sign into the number, so "-1" stays a single literal
+          tokens.push(this._createToken('-' + element))
+        } else {
+          // anything else gets a standalone prefix operator, letting "-x",
+          // "-(a + b)" and "-foo.bar" negate a computed value
+          tokens.push(unaryMinusToken(), this._createToken(element))
         }
-        tokens.push(this._createToken(elements[i]))
+      } else {
+        tokens.push(this._createToken(element))
       }
     }
     // Catch a - at the end of the string. Let the parser handle that issue.
@@ -164,8 +189,8 @@ class Lexer {
       token.value = parseFloat(element)
     } else if (element === 'true' || element === 'false') {
       token.value = element === 'true'
-    } else if (this._grammar.elements[element]) {
-      token.type = this._grammar.elements[element].type
+    } else if (Object.hasOwn(this._grammar.elements, element)) {
+      token.type = this._grammar.elements[element]!.type
     } else if (identRegex.exec(element)) {
       token.type = 'identifier'
     } else {
@@ -232,7 +257,7 @@ class Lexer {
     if (!tokens.length) {
       return true
     }
-    return minusNegatesAfter.has(tokens[tokens.length - 1].type)
+    return minusNegatesAfter.has(tokens[tokens.length - 1]!.type)
   }
 
   /**
@@ -259,7 +284,7 @@ class Lexer {
    * @private
    */
   _unquote(str: string) {
-    const quote = str[0]
+    const quote = str[0]!
     let escQuoteRegex = this._escQuoteRegexCache.get(quote)
     if (!escQuoteRegex) {
       escQuoteRegex = new RegExp('\\\\' + quote, 'g')
@@ -267,12 +292,12 @@ class Lexer {
     }
     return str
       .slice(1, -1)
-      .replace(escQuoteRegex, quote)
-      .replace(escEscRegex, '\\')
+      .replaceAll(escQuoteRegex, quote)
+      .replaceAll(escEscRegex, '\\')
   }
 
   _parseTemplateString(str: string) {
-    const parts: { type: 'static' | 'interpolation'; value: string }[] = []
+    const parts: TemplatePart[] = []
     let current = 1
     let staticStart = 1
 
@@ -295,14 +320,24 @@ class Lexer {
         current += 2
 
         while (current < str.length && braceDepth > 0) {
-          if (str[current] === '\\') {
+          const char = str[current]
+          if (char === '\\') {
             current += 2
             continue
           }
-          if (str[current] === '{') {
-            braceDepth++
+          // skip over string literals so that braces inside them, as in
+          // `${ f('}') }`, don't unbalance the depth count
+          if (char === '"' || char === "'") {
+            current++
+            while (current < str.length && str[current] !== char) {
+              current += str[current] === '\\' ? 2 : 1
+            }
+            current++
+            continue
           }
-          if (str[current] === '}') {
+          if (char === '{') {
+            braceDepth++
+          } else if (char === '}') {
             braceDepth--
           }
           current++

package/src/evaluator/Evaluator.ts

@@ -3,23 +3,23 @@
  * Copyright 2020 Tom Shawver
  */
 
-import * as handlers from './handlers.ts'
+import { compileAst } from './compile.ts'
 
-import type { AstNode } from '../types.ts'
-
-interface Grammar {
-  elements: Record<string, any>
-  [key: string]: any
-}
+import type { Grammar } from '../grammar.ts'
+import type { AstNode, JexlValue } from '../types.ts'
 
 /**
- * The Evaluator takes a Jexl expression tree as generated by the
- * {@link Parser} and calculates its value within a given context. The
- * collection of transforms, context, and a relative context to be used as the
- * root for relative identifiers, are all specific to an Evaluator instance.
- * When any of these things change, a new instance is required.  However, a
- * single instance can be used to simultaneously evaluate many different
+ * The Evaluator carries everything an expression is evaluated against: the
+ * grammar, the context, and a relative context to be used as the root for
+ * relative identifiers. When any of these change, a new instance is required.
+ * However, a single instance can be used to evaluate many different
  * expressions, and does not have to be reinstantiated for each.
+ *
+ * The work of evaluation itself lives in {@link compileAst}, which lowers a
+ * tree to closures. Prefer compiling once and reusing the result — that is what
+ * {@link Expression} does — over calling {@link #eval}, which compiles the tree
+ * it is given every time.
+ *
  * @param {{}} grammar A grammar object against which to evaluate the expression
  *      tree
  * @param {{}} [context] A map of variable keys to their values. This will be
@@ -29,46 +29,29 @@ interface Grammar {
  */
 class Evaluator {
   _grammar: Grammar
-  _context: any
-  _relContext: any
-
-  constructor(grammar: Grammar, context?: any, relativeContext?: any) {
+  _context: Record<string, JexlValue>
+  _relContext: Record<string, JexlValue>
+
+  constructor(
+    grammar: Grammar,
+    context?: Record<string, JexlValue>,
+    relativeContext?: Record<string, JexlValue>
+  ) {
     this._grammar = grammar
     this._context = context || {}
     this._relContext = relativeContext || this._context
   }
 
   /**
-   * Evaluates an expression tree within the configured context.
+   * Compiles and evaluates an expression tree within the configured context.
+   * Convenient for a one-shot evaluation; for repeated evaluation of the same
+   * tree, hold onto the closure from {@link compileAst} instead so the tree is
+   * only lowered once.
    * @param {{}} ast An expression tree object
    * @returns {*} the resulting value of the expression.
    */
-  eval(ast: AstNode) {
-    return (handlers as any)[ast.type].call(this, ast)
-  }
-
-  /**
-   * Evaluates each expression within an array, and delivers the response as an
-   * array with the resulting values at the same indexes as their originating
-   * expressions.
-   * @param {Array<string>} arr An array of expression strings to be evaluated
-   * @returns {Array<{}>} the result array
-   */
-  evalArray(arr: AstNode[]) {
-    return arr.map((elem: AstNode) => this.eval(elem))
-  }
-
-  /**
-   * Evaluates each expression within a map, and delivers the response as a map
-   * with the same keys, but with the evaluated result for each as their value.
-   * @param {{}} map A map of expression names to expression trees to be
-   *      evaluated
-   * @returns {{}} the result map.
-   */
-  evalMap(map: Record<string, AstNode>) {
-    const entries = Object.entries(map)
-    const vals = entries.map(([_, ast]) => this.eval(ast))
-    return Object.fromEntries(entries.map(([key], idx) => [key, vals[idx]]))
+  eval(ast: AstNode): JexlValue {
+    return compileAst(ast, this._grammar)(this)
   }
 }