parser

Documentation

Index

• func AnalyzeFastPath(node *types.ASTNode) *types.FastPathInfo
• func Compile(query string, opts ...CompileOption) (*types.Expression, error)
• func Parse(query string) (*types.Expression, error)
• type CompileOption
  • func WithMaxDepth(depth int) CompileOption
  • func WithRecovery(enable bool) CompileOption
• type CompileOptions
• type Lexer
  • func NewLexer(input string) *Lexer
  • func (l *Lexer) Error() error
  • func (l *Lexer) Next(allowRegex bool) Token
• type Parser
  • func NewParser(input string, opts ...CompileOption) *Parser
  • func (p *Parser) Parse() (*types.Expression, error)
• type Token
• type TokenType
  • func (tt TokenType) String() string

Functions

func AnalyzeFastPath

func AnalyzeFastPath(node *types.ASTNode) *types.FastPathInfo

AnalyzeFastPath performs a compile-time static analysis of the AST rooted at node and returns a types.FastPathInfo if the expression can be evaluated zero-copy against raw JSON bytes.

The function recognises three patterns:

• Pure dotted-path navigation ("a.b.c") → types.FastPathPurePath
• Equality/inequality against a literal ("a.b = \"x\"") → types.FastPathComparison
• Supported stdlib function on a pure path ("$exists(a.b)") → types.FastPathFunc

Returns nil when the expression requires full AST evaluation.

func Compile

func Compile(query string, opts ...CompileOption) (*types.Expression, error)

Compile is an alias for Parse, provided for API consistency.

func Parse

func Parse(query string) (*types.Expression, error)

Parse parses a JSONata expression and returns the compiled Expression.

The function tokenizes the input, builds an AST, and validates the syntax. If parsing fails, it returns a detailed error with position information.

Example:

expr, err := parser.Parse("$.name")
if err != nil {
    fmt.Printf("Parse error at position %d\n", err.Position)
    return
}

Types

type CompileOption

type CompileOption func(*CompileOptions)

CompileOption configures compilation behavior.

func WithMaxDepth

func WithMaxDepth(depth int) CompileOption

WithMaxDepth sets the maximum parsing depth.

func WithRecovery

func WithRecovery(enable bool) CompileOption

WithRecovery enables error recovery mode.

type CompileOptions

type CompileOptions struct {
	// EnableRecovery enables error recovery mode for parsing invalid syntax.
	EnableRecovery bool
	// MaxDepth limits recursion depth to prevent stack overflow.
	MaxDepth int
}

CompileOptions holds parser configuration.

type Lexer

type Lexer struct {
	// contains filtered or unexported fields
}

Lexer converts a JSONata expression into a sequence of tokens. The implementation is based on Rob Pike's "Lexical Scanning in Go" technique.

func NewLexer

func NewLexer(input string) *Lexer

NewLexer creates a new lexer from the provided input string. The input is tokenized by successive calls to the Next method.

func (*Lexer) Error

func (l *Lexer) Error() error

Error returns the first error encountered during lexing, if any.

func (*Lexer) Next

func (l *Lexer) Next(allowRegex bool) Token

Next returns the next token from the input. When the end of the input is reached, Next returns TokenEOF for all subsequent calls.

The allowRegex parameter determines how forward slashes are interpreted. Forward slashes in JSONata can be either:

• The start of a regular expression (when allowRegex is true)
• The division operator (when allowRegex is false)

The parser must track context to determine which interpretation is correct.

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser implements a recursive descent parser for JSONata expressions. It uses Pratt's "Top Down Operator Precedence" algorithm to handle operator precedence correctly.

func NewParser

func NewParser(input string, opts ...CompileOption) *Parser

NewParser creates a new parser for the given input string.

func (*Parser) Parse

func (p *Parser) Parse() (*types.Expression, error)

Parse parses the entire expression and returns the root AST node.

type Token

type Token struct {
	Type     TokenType // Type of the token
	Value    string    // Literal value of the token
	Position int       // Starting position in the input string
}

Token represents a lexical token in a JSONata expression.

type TokenType

type TokenType uint8

TokenType represents the type of a lexical token.

const (
	// Special tokens
	TokenEOF TokenType = iota
	TokenError

	// Literals
	TokenString   // "hello" or 'hello'
	TokenNumber   // 123, 3.14, 1e-10
	TokenBoolean  // true, false
	TokenNull     // null
	TokenName     // fieldName
	TokenNameEsc  // `field name with spaces`
	TokenVariable // $var, $$
	TokenRegex    // /pattern/flags

	// Grouping symbols
	TokenBracketOpen  // [
	TokenBracketClose // ]
	TokenBraceOpen    // {
	TokenBraceClose   // }
	TokenParenOpen    // (
	TokenParenClose   // )

	// Basic symbols
	TokenDot       // .
	TokenComma     // ,
	TokenColon     // :
	TokenSemicolon // ;
	TokenCondition // ?

	// Arithmetic operators
	TokenPlus  // +
	TokenMinus // -
	TokenMult  // *
	TokenDiv   // /
	TokenMod   // %

	// Other operators
	TokenPipe   // |
	TokenSort   // ^
	TokenConcat // &

	// Comparison operators
	TokenEqual        // =
	TokenNotEqual     // !=
	TokenLess         // <
	TokenLessEqual    // <=
	TokenGreater      // >
	TokenGreaterEqual // >=

	// Special operators
	TokenRange      // ..
	TokenApply      // ~>
	TokenAssign     // :=
	TokenDescendent // **
	TokenCoalesce   // ??
	TokenDefault    // ?:
	TokenAt         // @  (context variable binding)
	TokenHash       // #  (positional variable binding)

	// Keyword operators
	TokenAnd // and
	TokenOr  // or
	TokenIn  // in
)

func (TokenType) String

func (tt TokenType) String() string

String returns a string representation of the token type.