Skip to content

Beautiful Open-Source Form Builder

9.5 KB
Raw Blame
import { TokenType, NodeType, FormulaError } from './types.js'
import { Lexer } from './lexer.js'

/**
 * Parser for formula expressions
 * Converts tokens into an Abstract Syntax Tree (AST)
 * 
 * Grammar (precedence from lowest to highest):
 * expression  = comparison
 * comparison  = addition (("=" | "<>" | "<" | ">" | "<=" | ">=") addition)?
 * addition    = multiplication (('+' | '-') multiplication)*
 * multiplication = unary (('*' | '/') unary)*
 * unary       = ('-' | 'NOT') unary | primary
 * primary     = NUMBER | STRING | BOOLEAN | field_ref | function_call | '(' expression ')'
 */
export class Parser {
  constructor(tokens, options = {}) {
    this.tokens = tokens
    this.current = 0
    // Field name lookup for better error messages
    this.fieldNames = options.fieldNames || {}
    // Track the last parsed primary for adjacent operand detection
    this.lastPrimaryToken = null
  }

  /**
   * Parse a formula string into an AST
   * @param {string} formula - The formula to parse
   * @param {Object} options - Parser options
   * @param {Object} options.fieldNames - Map of field IDs to display names
   */
  static parse(formula, options = {}) {
    const lexer = new Lexer(formula)
    const tokens = lexer.tokenize()
    const parser = new Parser(tokens, options)
    return parser.parse()
  }

  /**
   * Parse tokens into AST
   */
  parse() {
    const ast = this.expression()
    
    if (!this.isAtEnd()) {
      const currentToken = this.peek()
      const errorMessage = this.getUnexpectedTokenError(currentToken)
      throw new FormulaError(errorMessage, currentToken.position)
    }
    
    return ast
  }

  /**
   * Get a human-readable name for a field ID
   */
  getFieldDisplayName(fieldId) {
    return this.fieldNames[fieldId] || fieldId
  }

  /**
   * Generate a helpful error message for unexpected tokens
   */
  getUnexpectedTokenError(token) {
    // Check if this looks like an adjacent operand situation
    // (two values without an operator between them)
    if (this.lastPrimaryToken && this.isValueToken(token)) {
      const lastName = this.getTokenDisplayName(this.lastPrimaryToken)
      const currentName = this.getTokenDisplayName(token)
      return `Missing operator between ${lastName} and ${currentName}. Use +, -, *, / or a function like CONCAT().`
    }
    
    // For field refs that look like UUIDs, give a cleaner message
    if (token.type === TokenType.FIELD_REF) {
      const fieldName = this.getFieldDisplayName(token.value)
      return `Unexpected field reference '${fieldName}'`
    }
    
    // For identifiers (which might be function typos)
    if (token.type === TokenType.IDENTIFIER) {
      return `Unexpected identifier '${token.value}'. Did you mean to call a function? Use ${token.value}()`
    }
    
    return `Unexpected token '${token.value}'`
  }

  /**
   * Check if a token represents a value (operand)
   */
  isValueToken(token) {
    return [
      TokenType.NUMBER,
      TokenType.STRING,
      TokenType.BOOLEAN,
      TokenType.FIELD_REF,
      TokenType.IDENTIFIER
    ].includes(token.type)
  }

  /**
   * Get display name for a token
   */
  getTokenDisplayName(token) {
    switch (token.type) {
      case TokenType.FIELD_REF:
        return `'${this.getFieldDisplayName(token.value)}'`
      case TokenType.STRING:
        return `"${token.value}"`
      case TokenType.NUMBER:
        return token.value.toString()
      case TokenType.BOOLEAN:
        return token.value.toString().toUpperCase()
      default:
        return `'${token.value}'`
    }
  }

  /**
   * Check if we've reached the end of tokens
   */
  isAtEnd() {
    return this.peek().type === TokenType.EOF
  }

  /**
   * Get current token without advancing
   */
  peek() {
    return this.tokens[this.current]
  }

  /**
   * Get previous token
   */
  previous() {
    return this.tokens[this.current - 1]
  }

  /**
   * Advance and return current token
   */
  advance() {
    if (!this.isAtEnd()) {
      this.current++
    }
    return this.previous()
  }

  /**
   * Check if current token matches any of the given types
   */
  check(type) {
    if (this.isAtEnd()) return false
    return this.peek().type === type
  }

  /**
   * Check if current token matches type and value
   */
  checkValue(type, value) {
    if (this.isAtEnd()) return false
    const token = this.peek()
    return token.type === type && token.value === value
  }

  /**
   * Consume token if it matches, otherwise throw error
   */
  consume(type, message) {
    if (this.check(type)) return this.advance()
    throw new FormulaError(message, this.peek().position)
  }

  /**
   * Match and consume if current token matches any of the given types/values
   */
  match(type, ...values) {
    if (this.check(type)) {
      if (values.length === 0 || values.includes(this.peek().value)) {
        this.advance()
        return true
      }
    }
    return false
  }

  /**
   * Parse expression (entry point)
   */
  expression() {
    return this.comparison()
  }

  /**
   * Parse comparison operators
   */
  comparison() {
    let left = this.addition()

    if (this.match(TokenType.COMPARISON)) {
      const operator = this.previous().value
      const right = this.addition()
      return {
        type: NodeType.BINARY,
        operator,
        left,
        right
      }
    }

    return left
  }

  /**
   * Parse addition and subtraction
   */
  addition() {
    let left = this.multiplication()

    while (this.match(TokenType.OPERATOR, '+', '-')) {
      const operator = this.previous().value
      const right = this.multiplication()
      left = {
        type: NodeType.BINARY,
        operator,
        left,
        right
      }
    }

    return left
  }

  /**
   * Parse multiplication and division
   */
  multiplication() {
    let left = this.unary()

    while (this.match(TokenType.OPERATOR, '*', '/')) {
      const operator = this.previous().value
      const right = this.unary()
      left = {
        type: NodeType.BINARY,
        operator,
        left,
        right
      }
    }

    return left
  }

  /**
   * Parse unary operators (- and NOT)
   */
  unary() {
    // Unary minus
    if (this.match(TokenType.OPERATOR, '-')) {
      const operand = this.unary()
      return {
        type: NodeType.UNARY,
        operator: '-',
        operand
      }
    }

    // NOT operator
    if (this.check(TokenType.IDENTIFIER) && this.peek().value === 'NOT') {
      this.advance()
      const operand = this.unary()
      return {
        type: NodeType.UNARY,
        operator: 'NOT',
        operand
      }
    }

    return this.primary()
  }

  /**
   * Parse primary expressions
   */
  primary() {
    // Number literal
    if (this.match(TokenType.NUMBER)) {
      this.lastPrimaryToken = this.previous()
      return {
        type: NodeType.NUMBER,
        value: this.previous().value
      }
    }

    // String literal
    if (this.match(TokenType.STRING)) {
      this.lastPrimaryToken = this.previous()
      return {
        type: NodeType.STRING,
        value: this.previous().value
      }
    }

    // Boolean literal
    if (this.match(TokenType.BOOLEAN)) {
      this.lastPrimaryToken = this.previous()
      return {
        type: NodeType.BOOLEAN,
        value: this.previous().value
      }
    }

    // Field reference
    if (this.match(TokenType.FIELD_REF)) {
      this.lastPrimaryToken = this.previous()
      return {
        type: NodeType.FIELD,
        id: this.previous().value
      }
    }

    // Function call or identifier
    if (this.match(TokenType.IDENTIFIER)) {
      const name = this.previous().value
      
      // Check if it's a function call
      if (this.check(TokenType.LPAREN)) {
        const result = this.functionCall(name)
        this.lastPrimaryToken = this.previous() // The closing paren
        return result
      }

      // Otherwise it's an unknown identifier
      throw new FormulaError(
        `Unknown identifier '${name}'. Did you mean to use a field? Use {${name}} or call a function with ${name}()`,
        this.previous().position
      )
    }

    // Parenthesized expression
    if (this.match(TokenType.LPAREN)) {
      const expr = this.expression()
      this.consume(TokenType.RPAREN, "Missing closing parenthesis ')'")
      this.lastPrimaryToken = this.previous()
      return expr
    }

    // Provide a more helpful error for unexpected tokens
    const token = this.peek()
    if (token.type === TokenType.RPAREN) {
      throw new FormulaError(
        "Unexpected ')'. You may have an extra closing parenthesis or missing content.",
        token.position
      )
    }
    
    if (token.type === TokenType.COMMA) {
      throw new FormulaError(
        "Unexpected ','. Commas should only be used to separate function arguments.",
        token.position
      )
    }
    
    if (token.type === TokenType.EOF) {
      throw new FormulaError(
        "Formula is incomplete. Expected a value or expression.",
        token.position
      )
    }

    throw new FormulaError(
      `Unexpected '${token.value}'. Expected a number, text, field, or function.`,
      token.position
    )
  }

  /**
   * Parse function call
   */
  functionCall(name) {
    this.consume(TokenType.LPAREN, `Expected '(' after function name '${name}'`)
    
    const args = []
    
    // Parse arguments
    if (!this.check(TokenType.RPAREN)) {
      do {
        args.push(this.expression())
      } while (this.match(TokenType.COMMA))
    }

    this.consume(TokenType.RPAREN, `Missing closing ')' for function ${name.toUpperCase()}()`)

    return {
      type: NodeType.FUNCTION,
      name,
      args
    }
  }
}