@jbrowse/jexl 2.3.1

package/src/parser/handlers.ts

@@ -0,0 +1,309 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import type { AstNode, Token } from '../types.ts'
+import type Parser from './Parser.ts'
+
+/**
+ * Handles a subexpression that's used to define a transform argument's value.
+ * @param {{type: <string>}} ast The subexpression tree
+ */
+export function argVal(this: Parser, ast: AstNode | null) {
+  if (ast) {
+    ;(this._cursor as any).args.push(ast)
+  }
+}
+
+/**
+ * Handles new array literals by adding them as a new node in the AST,
+ * initialized with an empty array.
+ */
+export function arrayStart(this: Parser) {
+  this._placeAtCursor({
+    type: 'ArrayLiteral',
+    value: []
+  } as any)
+}
+
+/**
+ * Handles a subexpression representing an element of an array literal.
+ * @param {{type: <string>}} ast The subexpression tree
+ */
+export function arrayVal(this: Parser, ast: AstNode | null) {
+  if (ast) {
+    ;(this._cursor as any).value.push(ast)
+  }
+}
+
+/**
+ * Handles tokens of type 'binaryOp', indicating an operation that has two
+ * inputs: a left side and a right side.
+ * @param {{type: <string>}} token A token object
+ */
+export function binaryOp(this: Parser, token: Token) {
+  if (token.value === '=') {
+    if (this._cursor?.type !== 'Identifier') {
+      throw new Error('Left side of assignment must be a variable name')
+    }
+
+    const node: any = {
+      type: 'AssignmentExpression',
+      operator: '=',
+      left: this._cursor
+    }
+    this._cursor = this._cursor._parent
+    this._placeAtCursor(node)
+    return
+  }
+
+  const precedence = this._grammar.elements[token.value].precedence || 0
+  let parent = this._cursor?._parent
+  while (
+    parent &&
+    (parent as any).operator &&
+    this._grammar.elements[(parent as any).operator].precedence >= precedence
+  ) {
+    this._cursor = parent
+    parent = parent._parent
+  }
+  const node: any = {
+    type: 'BinaryExpression',
+    operator: token.value,
+    left: this._cursor
+  }
+  this._setParent(this._cursor!, node)
+  this._cursor = parent
+  this._placeAtCursor(node)
+}
+
+/**
+ * Handles successive nodes in an identifier chain.  More specifically, it
+ * sets values that determine how the following identifier gets placed in the
+ * AST.
+ */
+export function dot(this: Parser) {
+  const isBinaryExprWithRight = (node: AstNode) =>
+    node.type === 'BinaryExpression' && (node as any).right
+
+  this._nextIdentEncapsulate =
+    this._cursor &&
+    this._cursor.type !== 'UnaryExpression' &&
+    (this._cursor.type !== 'BinaryExpression' ||
+      isBinaryExprWithRight(this._cursor))
+
+  this._nextIdentRelative = !this._cursor || !this._nextIdentEncapsulate
+  if (this._nextIdentRelative) {
+    this._relative = true
+  }
+}
+
+/**
+ * Handles a subexpression used for filtering an array returned by an
+ * identifier chain.
+ * @param {{type: <string>}} ast The subexpression tree
+ */
+export function filter(this: Parser, ast: AstNode | null) {
+  this._placeBeforeCursor({
+    type: 'FilterExpression',
+    expr: ast,
+    relative: this._subParser!.isRelative(),
+    subject: this._cursor
+  } as any)
+}
+
+/**
+ * Handles identifier tokens when used to indicate the name of a function to
+ * be called.
+ * @param {{type: <string>}} token A token object
+ */
+export function functionCall(this: Parser) {
+  this._placeBeforeCursor({
+    type: 'FunctionCall',
+    name: (this._cursor as any).value,
+    args: [],
+    pool: 'functions'
+  } as any)
+}
+
+/**
+ * Handles identifier tokens by adding them as a new node in the AST.
+ * @param {{type: <string>}} token A token object
+ */
+export function identifier(this: Parser, token: Token) {
+  const node: any = {
+    type: 'Identifier',
+    value: token.value
+  }
+  if (this._nextIdentEncapsulate) {
+    node.from = this._cursor
+    this._placeBeforeCursor(node)
+    this._nextIdentEncapsulate = false
+  } else {
+    if (this._nextIdentRelative) {
+      node.relative = true
+      this._nextIdentRelative = false
+    }
+    this._placeAtCursor(node)
+  }
+}
+
+/**
+ * Handles literal values, such as strings, booleans, and numerics, by adding
+ * them as a new node in the AST.
+ * @param {{type: <string>}} token A token object
+ */
+export function literal(this: Parser, token: Token) {
+  this._placeAtCursor({
+    type: 'Literal',
+    value: token.value
+  } as any)
+}
+
+/**
+ * Handles template string tokens by parsing their interpolation expressions
+ * and creating a TemplateLiteral AST node.
+ * @param {{type: <string>}} token A token object
+ */
+export function templateString(this: Parser, token: Token) {
+  const parts: { type: 'static' | 'expression'; value: string | AstNode }[] = []
+
+  for (const part of token.value) {
+    if (part.type === 'static') {
+      parts.push({
+        type: 'static',
+        value: this._lexer._unescapeTemplateString(part.value)
+      })
+    } else {
+      const subTokens = this._lexer.tokenize(part.value)
+      const subParser = new (this.constructor as any)(
+        this._grammar,
+        this._lexer
+      )
+      subParser.addTokens(subTokens)
+      const subAst = subParser.complete()
+
+      if (!subAst) {
+        throw new Error('Empty interpolation in template string')
+      }
+
+      parts.push({
+        type: 'expression',
+        value: subAst
+      })
+    }
+  }
+
+  this._placeAtCursor({
+    type: 'TemplateLiteral',
+    parts: parts
+  } as any)
+}
+
+/**
+ * Queues a new object literal key to be written once a value is collected.
+ * @param {{type: <string>}} token A token object
+ */
+export function objKey(this: Parser, token: Token) {
+  this._curObjKey = token.value
+}
+
+/**
+ * Handles new object literals by adding them as a new node in the AST,
+ * initialized with an empty object.
+ */
+export function objStart(this: Parser) {
+  this._placeAtCursor({
+    type: 'ObjectLiteral',
+    value: {}
+  } as any)
+}
+
+/**
+ * Handles an object value by adding its AST to the queued key on the object
+ * literal node currently at the cursor.
+ * @param {{type: <string>}} ast The subexpression tree
+ */
+export function objVal(this: Parser, ast: AstNode | null) {
+  ;(this._cursor as any).value[this._curObjKey!] = ast
+}
+
+/**
+ * Handles traditional subexpressions, delineated with the groupStart and
+ * groupEnd elements.
+ * @param {{type: <string>}} ast The subexpression tree
+ */
+export function subExpression(this: Parser, ast: AstNode | null) {
+  this._placeAtCursor(ast!)
+}
+
+/**
+ * Handles a completed alternate subexpression of a ternary operator.
+ * @param {{type: <string>}} ast The subexpression tree
+ */
+export function ternaryEnd(this: Parser, ast: AstNode | null) {
+  ;(this._cursor as any).alternate = ast
+}
+
+/**
+ * Handles a completed consequent subexpression of a ternary operator.
+ * @param {{type: <string>}} ast The subexpression tree
+ */
+export function ternaryMid(this: Parser, ast: AstNode | null) {
+  ;(this._cursor as any).consequent = ast
+}
+
+/**
+ * Handles the start of a new ternary expression by encapsulating the entire
+ * AST in a ConditionalExpression node, and using the existing tree as the
+ * test element.
+ */
+export function ternaryStart(this: Parser) {
+  this._tree = {
+    type: 'ConditionalExpression',
+    test: this._tree
+  } as any
+  this._cursor = this._tree
+}
+
+/**
+ * Handles identifier tokens when used to indicate the name of a transform to
+ * be applied.
+ * @param {{type: <string>}} token A token object
+ */
+export function transform(this: Parser, token: Token) {
+  this._placeBeforeCursor({
+    type: 'FunctionCall',
+    name: token.value,
+    args: [this._cursor],
+    pool: 'transforms'
+  } as any)
+}
+
+/**
+ * Handles token of type 'unaryOp', indicating that the operation has only
+ * one input: a right side.
+ * @param {{type: <string>}} token A token object
+ */
+export function unaryOp(this: Parser, token: Token) {
+  this._placeAtCursor({
+    type: 'UnaryExpression',
+    operator: token.value
+  } as any)
+}
+
+/**
+ * Handles semicolon separator between expressions
+ */
+export function semicolon(this: Parser) {
+  if (!this._sequenceExpressions) {
+    this._sequenceExpressions = [this._tree!]
+  } else {
+    this._sequenceExpressions.push(this._tree!)
+  }
+
+  this._tree = null
+  this._cursor = null
+  this._state = 'expectOperand'
+}

package/src/parser/states.ts

@@ -0,0 +1,177 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+import * as h from './handlers.ts'
+
+import type { AstNode } from '../types.ts'
+import type Parser from './Parser.ts'
+
+interface TokenTypeOptions {
+  toState?: string
+  handler?: (this: Parser, ...args: any[]) => void
+}
+
+interface StateDefinition {
+  tokenTypes?: Record<string, TokenTypeOptions>
+  subHandler?: (this: Parser, ast: AstNode | null) => void
+  endStates?: Record<string, string>
+  completable?: boolean
+}
+
+type States = Record<string, StateDefinition>
+
+/**
+ * A mapping of all states in the finite state machine to a set of instructions
+ * for handling or transitioning into other states. Each state can be handled
+ * in one of two schemes: a tokenType map, or a subHandler.
+ *
+ * Standard expression elements are handled through the tokenType object. This
+ * is an object map of all legal token types to encounter in this state (and
+ * any unexpected token types will generate a thrown error) to an options
+ * object that defines how they're handled.  The available options are:
+ *
+ *      {string} toState: The name of the state to which to transition
+ *          immediately after handling this token
+ *      {string} handler: The handler function to call when this token type is
+ *          encountered in this state.  If omitted, the default handler
+ *          matching the token's "type" property will be called. If the handler
+ *          function does not exist, no call will be made and no error will be
+ *          generated.  This is useful for tokens whose sole purpose is to
+ *          transition to other states.
+ *
+ * States that consume a subexpression should define a subHandler, the
+ * function to be called with an expression tree argument when the
+ * subexpression is complete. Completeness is determined through the
+ * endStates object, which maps tokens on which an expression should end to the
+ * state to which to transition once the subHandler function has been called.
+ *
+ * Additionally, any state in which it is legal to mark the AST as completed
+ * should have a 'completable' property set to boolean true.  Attempting to
+ * call {@link Parser#complete} in any state without this property will result
+ * in a thrown Error.
+ *
+ * @type {{}}
+ */
+export const states: States = {
+  expectOperand: {
+    tokenTypes: {
+      literal: { toState: 'expectBinOp' },
+      templateString: { toState: 'expectBinOp' },
+      identifier: { toState: 'identifier' },
+      unaryOp: {},
+      openParen: { toState: 'subExpression' },
+      openCurl: { toState: 'expectObjKey', handler: h.objStart },
+      dot: { toState: 'traverse' },
+      openBracket: { toState: 'arrayVal', handler: h.arrayStart }
+    }
+  },
+  expectBinOp: {
+    tokenTypes: {
+      binaryOp: { toState: 'expectOperand' },
+      pipe: { toState: 'expectTransform' },
+      dot: { toState: 'traverse' },
+      question: { toState: 'ternaryMid', handler: h.ternaryStart },
+      semicolon: { handler: h.semicolon }
+    },
+    completable: true
+  },
+  expectTransform: {
+    tokenTypes: {
+      identifier: { toState: 'postTransform', handler: h.transform }
+    }
+  },
+  expectObjKey: {
+    tokenTypes: {
+      literal: { toState: 'expectKeyValSep', handler: h.objKey },
+      identifier: { toState: 'expectKeyValSep', handler: h.objKey },
+      closeCurl: { toState: 'expectBinOp' }
+    }
+  },
+  expectKeyValSep: {
+    tokenTypes: {
+      colon: { toState: 'objVal' }
+    }
+  },
+  postTransform: {
+    tokenTypes: {
+      openParen: { toState: 'argVal' },
+      binaryOp: { toState: 'expectOperand' },
+      dot: { toState: 'traverse' },
+      openBracket: { toState: 'filter' },
+      pipe: { toState: 'expectTransform' },
+      question: { toState: 'ternaryMid', handler: h.ternaryStart }
+    },
+    completable: true
+  },
+  postArgs: {
+    tokenTypes: {
+      binaryOp: { toState: 'expectOperand' },
+      dot: { toState: 'traverse' },
+      openBracket: { toState: 'filter' },
+      pipe: { toState: 'expectTransform' },
+      question: { toState: 'ternaryMid', handler: h.ternaryStart }
+    },
+    completable: true
+  },
+  identifier: {
+    tokenTypes: {
+      binaryOp: { toState: 'expectOperand' },
+      dot: { toState: 'traverse' },
+      openBracket: { toState: 'filter' },
+      openParen: { toState: 'argVal', handler: h.functionCall },
+      pipe: { toState: 'expectTransform' },
+      question: { toState: 'ternaryMid', handler: h.ternaryStart }
+    },
+    completable: true
+  },
+  traverse: {
+    tokenTypes: {
+      identifier: { toState: 'identifier' }
+    }
+  },
+  filter: {
+    subHandler: h.filter,
+    endStates: {
+      closeBracket: 'identifier'
+    }
+  },
+  subExpression: {
+    subHandler: h.subExpression,
+    endStates: {
+      closeParen: 'expectBinOp'
+    }
+  },
+  argVal: {
+    subHandler: h.argVal,
+    endStates: {
+      comma: 'argVal',
+      closeParen: 'postArgs'
+    }
+  },
+  objVal: {
+    subHandler: h.objVal,
+    endStates: {
+      comma: 'expectObjKey',
+      closeCurl: 'expectBinOp'
+    }
+  },
+  arrayVal: {
+    subHandler: h.arrayVal,
+    endStates: {
+      comma: 'arrayVal',
+      closeBracket: 'expectBinOp'
+    }
+  },
+  ternaryMid: {
+    subHandler: h.ternaryMid,
+    endStates: {
+      colon: 'ternaryEnd'
+    }
+  },
+  ternaryEnd: {
+    subHandler: h.ternaryEnd,
+    completable: true
+  }
+}

package/src/types.ts

@@ -0,0 +1,107 @@
+/*
+ * Jexl
+ * Copyright 2020 Tom Shawver
+ */
+
+export interface Token {
+  type: string
+  value: any
+  raw: string
+}
+
+export interface AstNode {
+  type: string
+  _parent?: AstNode
+}
+
+export interface Literal extends AstNode {
+  type: 'Literal'
+  value: string | number | boolean
+}
+
+export interface Identifier extends AstNode {
+  type: 'Identifier'
+  value: string
+  from?: AstNode
+  relative?: boolean
+}
+
+export interface BinaryExpression extends AstNode {
+  type: 'BinaryExpression'
+  operator: string
+  left: AstNode
+  right?: AstNode
+}
+
+export interface UnaryExpression extends AstNode {
+  type: 'UnaryExpression'
+  operator: string
+  right?: AstNode
+}
+
+export interface ArrayLiteral extends AstNode {
+  type: 'ArrayLiteral'
+  value: AstNode[]
+}
+
+export interface ObjectLiteral extends AstNode {
+  type: 'ObjectLiteral'
+  value: Record<string, AstNode>
+}
+
+export interface TemplateLiteral extends AstNode {
+  type: 'TemplateLiteral'
+  parts: {
+    type: 'static' | 'expression'
+    value: string | AstNode
+  }[]
+}
+
+export interface FunctionCall extends AstNode {
+  type: 'FunctionCall'
+  name: string
+  args: AstNode[]
+  pool: 'functions' | 'transforms'
+}
+
+export interface FilterExpression extends AstNode {
+  type: 'FilterExpression'
+  expr: AstNode
+  relative: boolean
+  subject: AstNode
+}
+
+export interface ConditionalExpression extends AstNode {
+  type: 'ConditionalExpression'
+  test: AstNode
+  consequent?: AstNode
+  alternate?: AstNode
+}
+
+export interface SequenceExpression extends AstNode {
+  type: 'SequenceExpression'
+  expressions: AstNode[]
+}
+
+export interface AssignmentExpression extends AstNode {
+  type: 'AssignmentExpression'
+  operator: '='
+  left: Identifier
+  right: AstNode
+}
+
+export type AstNodeUnion =
+  | Literal
+  | Identifier
+  | BinaryExpression
+  | UnaryExpression
+  | ArrayLiteral
+  | ObjectLiteral
+  | TemplateLiteral
+  | FunctionCall
+  | FilterExpression
+  | ConditionalExpression
+  | SequenceExpression
+  | AssignmentExpression
+
+export type NodeByType<T extends AstNodeUnion['type']> = Extract<AstNodeUnion, { type: T }>