README

#ast

Abstract Syntax Tree definitions and streaming interpreter for jq expressions.

#Overview

This package provides:

AST Types: Enum definitions for jq expressions, literals, and operators
Interpreter: A streaming evaluator that processes expressions against JSON input
Error Types: Structured errors for runtime evaluation failures

The interpreter uses lazy evaluation via Iter[Json] to enable efficient streaming of results without loading everything into memory.

#Public Functions

#eval

pub fn eval(expr : Expr, input : Json) -> Iter[Json] raise

Evaluate a jq expression against JSON input, returning an iterator of results.

Parameters:

expr: The parsed jq expression (from @parser.parse)
input: The JSON value to query

Returns:

An Iter[Json] that lazily produces results

Raises:

InterpreterError on evaluation failures (type mismatches, missing keys, etc.)

Example:

let expr = @parser.parse(".users[] | .name")
let input = @json.parse("{\"users\": [{\"name\": \"Alice\"}, {\"name\": \"Bob\"}]}")
for name in @ast.eval(expr, input) {
  println(name)  // "Alice", then "Bob"
}

#Types

#Expr

pub(all) enum Expr

The expression AST representing all jq constructs. Key variants include:

#Core Expressions

Variant	jq Syntax	Description
Identity	.	Returns input unchanged
Literal(Literal)	null, true, 123, "str"	Literal values
Pipe(Expr, Expr)	expr \\| expr	Pipeline composition
Comma(Expr, Expr)	expr, expr	Multiple outputs

#Access Expressions

Variant	jq Syntax	Description
Key(String)	.foo	Object field access
Index(Array[Int])	.[0], .[]	Array indexing/iteration
Slice(Int?, Int?)	.[2:4]	Array slicing
Optional(Expr)	expr?	Suppress errors
Recurse	..	Recursive descent

#Constructors

Variant	jq Syntax	Description
ArrayConstruct(Expr?)	[expr], []	Build arrays
ObjectConstruct(Array[(Expr, Expr?)])	{key: value}	Build objects

#Binary Operations

Variant	jq Syntax	Description
Operation(Expr, BinaryOp, Expr)	a + b, a == b	Binary operations
Alternative(Expr, Expr)	a // b	Alternative (default)

#Built-in Functions

Variant	jq Syntax	Description
Length	length	String/array/object length
Keys	keys	Object keys or array indices
Values	values	Object values
Type	type	Type name as string
Empty	empty	Produce no output
Not	not	Boolean negation

#Array Functions

Variant	jq Syntax	Description
Map(Expr)	map(expr)	Transform each element
Select(Expr)	select(expr)	Filter elements
Sort	sort	Sort array
SortBy(Expr)	sort_by(expr)	Sort by key
Reverse	reverse	Reverse array
Flatten(Int?)	flatten, flatten(n)	Flatten nested arrays
Unique	unique	Remove duplicates
UniqueBy(Expr)	unique_by(expr)	Unique by key
GroupBy(Expr)	group_by(expr)	Group by key
Combinations	combinations	Cartesian product
Transpose	transpose	Matrix transpose

#Numeric Functions

Variant	jq Syntax	Description
Add	add	Sum array elements
Min / Max	min, max	Array min/max
MinBy(Expr) / MaxBy(Expr)	min_by(expr), max_by(expr)	Min/max by key
Floor / Round / Ceil	floor, round, ceil	Rounding
Abs	abs	Absolute value
Sqrt	sqrt	Square root
Pow(Expr)	pow(exp)	Exponentiation
Log / Exp	log, exp	Natural log/exponential
Sin / Cos / Tan	sin, cos, tan	Trigonometry
Asin / Acos / Atan	asin, acos, atan	Inverse trig

#String Functions

Variant	jq Syntax	Description
Split(String)	split(sep)	Split string
Join(String)	join(sep)	Join array
StartsWith(String)	startswith(str)	Prefix check
EndsWith(String)	endswith(str)	Suffix check
Contains(Expr)	contains(val)	Containment check
LTrimStr(String)	ltrimstr(str)	Remove prefix
RTrimStr(String)	rtrimstr(str)	Remove suffix
AsciiUpcase / AsciiDowncase	ascii_upcase, ascii_downcase	Case conversion
Explode	explode	String to codepoints
Implode	implode	Codepoints to string

#Object Functions

Variant	jq Syntax	Description
Has(String)	has(key)	Key existence check
In(Expr)	in(obj)	Check if input is key in obj
ToEntries	to_entries	Object to key-value pairs
FromEntries	from_entries	Key-value pairs to object
WithEntries(Expr)	with_entries(expr)	Transform entries
MapValues(Expr)	map_values(expr)	Transform values

#Control Flow

Variant	jq Syntax	Description
IfThenElse(Expr, Expr, Expr)	if c then a else b end	Conditional
TryCatch(Expr, Expr?)	try expr catch handler	Error handling
Limit(Int, Expr)	limit(n; expr)	Limit output count
Until(Expr, Expr)	until(cond; update)	Loop until condition
While(Expr, Expr)	while(cond; update)	Loop while condition

#Variables and Iteration

Variant	jq Syntax	Description
Variable(String)	$var	Variable reference
As(Expr, String, Expr)	expr as $v \\| body	Variable binding
Reduce(Expr, String, Expr, Expr)	reduce expr as $v (init; update)	Fold/reduce
Foreach(...)	foreach expr as $v (init; update; extract)	Stateful iteration

#Path Functions

Variant	jq Syntax	Description
Path(Expr)	path(expr)	Get path to value
Paths	paths	All paths in input
PathsWithFilter(Expr)	paths(filter)	Filtered paths
LeafPaths	leaf_paths	Paths to leaf values
GetPath(Expr)	getpath(path)	Get value at path
SetPath(Expr, Expr)	setpath(path; value)	Set value at path
DelPaths(Expr)	delpaths(paths)	Delete paths

#Assignment

Variant	jq Syntax	Description
Update(Expr, Expr)	path \\|= expr	Update in place
Assign(Expr, Expr)	path = expr	Assign value
AddAssign(Expr, Expr)	path += expr	Add and assign
SubAssign(Expr, Expr)	path -= expr	Subtract and assign
MulAssign(Expr, Expr)	path *= expr	Multiply and assign
DivAssign(Expr, Expr)	path /= expr	Divide and assign
ModAssign(Expr, Expr)	path %= expr	Modulo and assign
AltAssign(Expr, Expr)	path //= expr	Alternative assign

#Format Strings

Variant	jq Syntax	Description
Format(String)	@base64, @uri, @csv, @html	Format encodings
StringInterpolation(...)	"text \(expr) more"	String interpolation

#User-defined Functions

Variant	jq Syntax	Description
FunctionDef(String, Array[String], Expr)	def name(params): body;	Define function
FunctionCall(String, Array[Expr])	name(args)	Call function

#Regex (Simple Implementation)

Variant	jq Syntax	Description
Test(String)	test(regex)	Test if matches
Match(String)	match(regex)	Get match info
Capture(String)	capture(regex)	Capture groups
Scan(String)	scan(regex)	Extract all matches
Splits(String)	splits(regex)	Split by regex
Sub(String, String)	sub(regex; repl)	Replace first
GSub(String, String)	gsub(regex; repl)	Replace all

#Literal

///|
pub(all) enum Literal {
  Null
  Bool(Bool)
  Number(Double)
  String(String)
}

Literal values that can appear in jq expressions.

#BinaryOp

///|
pub(all) enum BinaryOp {
  Add // +
  Subtract // -
  Multiply // *
  Divide // /
  Modulo // %
  Equal // ==
  NotEqual // !=
  LessThan // <
  LessEq // <=
  GreaterThan // >
  GreaterEq // >=
  And // and
  Or // or
}

Binary operators for arithmetic, comparison, and logical operations.

#InterpreterError

///|
pub(all) suberror InterpreterError {
  TypeMismatch(String, String) // (expected, got)
  KeyNotFound(String)
  IndexOutOfBounds(Int)
  InvalidOperation(String)
  DivisionByZero
  TypeError(String)
  EvalError(String)
}

Runtime errors during expression evaluation:

Variant	Description
TypeMismatch(expected, got)	Operation received wrong type
KeyNotFound(key)	Object key does not exist
IndexOutOfBounds(idx)	Array index out of range
InvalidOperation(msg)	Operation not supported for types
DivisionByZero	Division or modulo by zero
TypeError(msg)	General type error
EvalError(msg)	General evaluation error

#Streaming Semantics

The interpreter uses Iter[Json] for lazy evaluation:

// Results are computed on-demand
let results = @ast.eval(expr, input)

// Only computes what's needed
for r in results.take(5) {
  println(r)
}

// Collect all results when needed
let all_results = results.collect()

This enables efficient processing of queries that produce many results without loading everything into memory.

#Internal Structure

The package is organized into multiple files:

expression.mbt - Expr enum definition
literal.mbt - Literal enum and conversion
operator.mbt - BinaryOp enum
interpreter.mbt - Main eval function and dispatch
interpreter_*.mbt - Specialized evaluators for different expression types
interpreter_error.mbt - Error type definitions

#
InterpreterError

source

pub(all) suberror InterpreterError {
  TypeMismatch(String, String)
  KeyNotFound(String)
  IndexOutOfBounds(Int)
  InvalidOperation(String)
  DivisionByZero
  TypeError(String)
  EvalError(String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Interpreter error types

impl Show for InterpreterError

#
InterpreterError::equal

source

fn InterpreterError::equal(InterpreterError, InterpreterError) -> Bool

Preserve method-style access to derived equality operations.

#
InterpreterError::not_equal

source

fn InterpreterError::not_equal(x : InterpreterError, y : InterpreterError) -> Bool

Preserve method-style access to derived equality operations.

#
InterpreterError::output

source

fn InterpreterError::output(self : InterpreterError, logger : &Logger) -> Unit

Preserve method-style access to display operations.

#
InterpreterError::to_repr

source

fn InterpreterError::to_repr(InterpreterError) -> @moonbitlang/core/debug.Repr
Repr

Preserve method-style access to derived debug representation.

#
InterpreterError::to_string

source

fn InterpreterError::to_string(self : InterpreterError) -> String

Preserve method-style access to display operations.

#
BinaryOp

source

pub(all) enum BinaryOp {
  Add
  Subtract
  Multiply
  Divide
  Modulo
  Equal
  NotEqual
  LessThan
  LessEq
  GreaterThan
  GreaterEq
  And
  Or
} derive(Eq, ToJson, @moonbitlang/core/debug.Debug
Debug)

Binary operators in jq

impl Show for BinaryOp

#
BinaryOp::equal

source

fn BinaryOp::equal(BinaryOp, BinaryOp) -> Bool

Preserve method-style access to derived equality operations.

#
BinaryOp::not_equal

source

fn BinaryOp::not_equal(x : BinaryOp, y : BinaryOp) -> Bool

Preserve method-style access to derived equality operations.

#
BinaryOp::output

source

fn BinaryOp::output(self : BinaryOp, logger : &Logger) -> Unit

Preserve method-style access to display operations.

#
BinaryOp::to_json

source

fn BinaryOp::to_json(BinaryOp) -> Json

Preserve method-style access to derived JSON conversion.

#
BinaryOp::to_repr

source

fn BinaryOp::to_repr(BinaryOp) -> @moonbitlang/core/debug.Repr
Repr

Preserve method-style access to derived debug representation.

#
BinaryOp::to_string

source

fn BinaryOp::to_string(self : BinaryOp) -> String

Preserve method-style access to display operations.

#
Expr

source

pub(all) enum Expr {
  Identity
  Literal(Literal)
  Pipe(Expr, Expr)
  Comma(Expr, Expr)
  Key(String)
  Index(Array[Int])
  Slice(Int?, Int?)
  Optional(Expr)
  ArrayConstruct(Expr?)
  ObjectConstruct(Array[(Expr, Expr?)])
  Operation(Expr, BinaryOp, Expr)
  Length
  Keys
  Values
  Type
  Empty
  Not
  Map(Expr)
  Select(Expr)
  Sort
  SortBy(Expr)
  Reverse
  Flatten(Int?)
  Unique
  UniqueBy(Expr)
  GroupBy(Expr)
  Combinations
  Transpose
  Add
  Floor
  Sqrt
  Min
  MinBy(Expr)
  Max
  MaxBy(Expr)
  Round
  Ceil
  Abs
  Split(String)
  Join(String)
  StartsWith(String)
  EndsWith(String)
  Contains(Expr)
  Inside(Expr)
  Has(String)
  In(Expr)
  ToEntries
  FromEntries
  WithEntries(Expr)
  MapValues(Expr)
  Range(Int)
  RangeFromTo(Expr, Expr)
  RangeWithStep(Expr, Expr, Expr)
  First
  FirstGen(Expr)
  Last
  LastGen(Expr)
  Repeat(Expr)
  IndicesOf(Expr)
  IndexOf(Expr)
  Any
  AnyGen(Expr, Expr)
  All
  AllGen(Expr, Expr)
  IfThenElse(Expr, Expr, Expr)
  TryCatch(Expr, Expr?)
  Variable(String)
  As(Expr, String, Expr)
  Reduce(Expr, String, Expr, Expr)
  Foreach(Expr, String, Expr, Expr, Expr?)
  Recurse
  RecurseWith(Expr, Expr)
  Walk(Expr)
  Path(Expr)
  Update(Expr, Expr)
  Assign(Expr, Expr)
  Alternative(Expr, Expr)
  AddAssign(Expr, Expr)
  SubAssign(Expr, Expr)
  MulAssign(Expr, Expr)
  DivAssign(Expr, Expr)
  ModAssign(Expr, Expr)
  AltAssign(Expr, Expr)
  Format(String)
  StringInterpolation(Array[(String, Expr?)])
  FunctionDef(String, Array[String], Expr)
  FunctionCall(String, Array[Expr])
  LTrimStr(String)
  RTrimStr(String)
  AsciiUpcase
  AsciiDowncase
  Explode
  Implode
  ToJsonString
  FromJsonString
  Nth(Int)
  RIndex(Expr)
  Paths
  PathsWithFilter(Expr)
  LeafPaths
  GetPath(Expr)
  SetPath(Expr, Expr)
  DelPaths(Expr)
  Limit(Int, Expr)
  Until(Expr, Expr)
  While(Expr, Expr)
  Pow(Expr)
  Log
  Exp
  Sin
  Cos
  Tan
  Asin
  Acos
  Atan
  Test(String)
  Match(String)
  Capture(String)
  Scan(String)
  Splits(String)
  Sub(String, String)
  GSub(String, String)
} derive(Eq, ToJson, @moonbitlang/core/debug.Debug
Debug)

jq expression AST

impl Show for Expr

#
Expr::equal

source

fn Expr::equal(Expr, Expr) -> Bool

Preserve method-style access to derived equality operations.

#
Expr::not_equal

source

fn Expr::not_equal(x : Expr, y : Expr) -> Bool

Preserve method-style access to derived equality operations.

#
Expr::output

source

fn Expr::output(self : Expr, logger : &Logger) -> Unit

Preserve method-style access to display operations.

#
Expr::to_json

source

fn Expr::to_json(Expr) -> Json

Preserve method-style access to derived JSON conversion.

#
Expr::to_repr

source

fn Expr::to_repr(Expr) -> @moonbitlang/core/debug.Repr
Repr

Preserve method-style access to derived debug representation.

#
Expr::to_string

source

fn Expr::to_string(self : Expr) -> String

Preserve method-style access to display operations.

#
Literal

source

pub(all) enum Literal {
  Null
  Bool(Bool)
  Number(Double)
  String(String)
} derive(Eq, ToJson, @moonbitlang/core/debug.Debug
Debug)

Literal values in jq expressions

impl Show for Literal

#
Literal::equal

source

fn Literal::equal(Literal, Literal) -> Bool

Preserve method-style access to derived equality operations.

#
Literal::not_equal

source

fn Literal::not_equal(x : Literal, y : Literal) -> Bool

Preserve method-style access to derived equality operations.

#
Literal::output

source

fn Literal::output(self : Literal, logger : &Logger) -> Unit

Preserve method-style access to display operations.

#
Literal::to_json

source

fn Literal::to_json(Literal) -> Json

Preserve method-style access to derived JSON conversion.

#
Literal::to_repr

source

fn Literal::to_repr(Literal) -> @moonbitlang/core/debug.Repr
Repr

Preserve method-style access to derived debug representation.

#
Literal::to_string

source

fn Literal::to_string(self : Literal) -> String

Preserve method-style access to display operations.

#
eval

source

fn eval(expr : Expr, input : Json) -> Iter[Json] raise

Evaluate an expression with input JSON, returns iterator of results

Source Files

Site source Report issue Packages Build queue Skills Statistics

#ast

#Overview

#Public Functions

#eval

#Types

#Expr

#Core Expressions

#Access Expressions

#Constructors

#Binary Operations

#Built-in Functions

#Array Functions

#Numeric Functions

#String Functions

#Object Functions

#Control Flow

#Variables and Iteration

#Path Functions

#Assignment

#Format Strings

#User-defined Functions

#Regex (Simple Implementation)

#Literal

#BinaryOp

#InterpreterError

#Streaming Semantics

#Internal Structure

#InterpreterError

#InterpreterError::equal

#InterpreterError::not_equal

#InterpreterError::output

#InterpreterError::to_repr

#InterpreterError::to_string

#BinaryOp

#BinaryOp::equal

#BinaryOp::not_equal

#BinaryOp::output

#BinaryOp::to_json

#BinaryOp::to_repr

#BinaryOp::to_string

#Expr

#Expr::equal

#Expr::not_equal

#Expr::output

#Expr::to_json

#Expr::to_repr

#Expr::to_string

#Literal

#Literal::equal

#Literal::not_equal

#Literal::output

#Literal::to_json

#Literal::to_repr

#Literal::to_string

#eval

Source Files

#
InterpreterError

#
InterpreterError::equal

#
InterpreterError::not_equal

#
InterpreterError::output

#
InterpreterError::to_repr

#
InterpreterError::to_string

#
BinaryOp

#
BinaryOp::equal

#
BinaryOp::not_equal

#
BinaryOp::output

#
BinaryOp::to_json

#
BinaryOp::to_repr

#
BinaryOp::to_string

#
Expr

#
Expr::equal

#
Expr::not_equal

#
Expr::output

#
Expr::to_json

#
Expr::to_repr

#
Expr::to_string

#
Literal

#
Literal::equal

#
Literal::not_equal

#
Literal::output

#
Literal::to_json

#
Literal::to_repr

#
Literal::to_string

#
eval