@type arithmetic_op() :: :add | :subtract | :multiply | :divide | :modulo

Arithmetic operators in the AST.

@type ast() ::
  {:literal, value(), position()}
  | {:string_literal, binary(), :double | :single, position()}
  | {:identifier, binary(), position()}
  | {:comparison, comparison_op(), ast(), ast(), position()}
  | {:arithmetic, arithmetic_op(), ast(), ast(), position()}
  | {:unary, unary_op(), ast(), position()}
  | {:membership, membership_op(), ast(), ast(), position()}
  | {:logical_and, ast(), ast(), position()}
  | {:logical_or, ast(), ast(), position()}
  | {:logical_not, ast(), position()}
  | {:list, [ast()], position()}
  | {:object, [object_entry()], position()}
  | {:function_call, binary(), [ast()], position()}
  | {:bracket_access, ast(), ast(), position()}
  | {:property_access, ast(), binary(), position()}
  | {:duration, [{integer(), binary()}], position()}
  | {:relative_date, ast(), relative_direction(), position()}

Abstract Syntax Tree node types.

Every node carries a trailing source position - the {line, column} of the token that defines it, or nil for a node built by a caller rather than parsed.

• {:literal, value, pos} - A literal value (number, boolean, list, date, datetime, duration)
• {:string_literal, value, quote_type, pos} - A string literal with quote type information
• {:identifier, name, pos} - A variable reference
• {:comparison, operator, left, right, pos} - A comparison expression (including equality)
• {:arithmetic, operator, left, right, pos} - An arithmetic expression (+, -, *, /, %)
• {:unary, operator, operand, pos} - A unary expression (-, !)
• {:logical_and, left, right, pos} - A logical AND expression
• {:logical_or, left, right, pos} - A logical OR expression
• {:logical_not, operand, pos} - A logical NOT expression
• {:list, elements, pos} - A list literal
• {:object, entries, pos} - An object literal whose keys are object_key/0
• {:membership, operator, left, right, pos} - A membership operation (in/contains)
• {:function_call, name, arguments, pos} - A function call with arguments
• {:bracket_access, object, key, pos} - A bracket access expression (obj[key])
• {:property_access, object, property, pos} - A property access expression (obj.prop)
• {:duration, units, pos} - A duration literal (e.g., 3d8h)
• {:relative_date, duration, direction, pos} - A relative date expression (e.g., 3d ago, next 2w)

@type bare_ast() ::
  {:literal, value()}
  | {:string_literal, binary(), :double | :single}
  | {:identifier, binary()}
  | {:comparison, comparison_op(), bare_ast(), bare_ast()}
  | {:arithmetic, arithmetic_op(), bare_ast(), bare_ast()}
  | {:unary, unary_op(), bare_ast()}
  | {:membership, membership_op(), bare_ast(), bare_ast()}
  | {:logical_and, bare_ast(), bare_ast()}
  | {:logical_or, bare_ast(), bare_ast()}
  | {:logical_not, bare_ast()}
  | {:list, [bare_ast()]}
  | {:object, [{bare_object_key(), bare_ast()}]}
  | {:function_call, binary(), [bare_ast()]}
  | {:bracket_access, bare_ast(), bare_ast()}
  | {:property_access, bare_ast(), binary()}
  | {:duration, [{integer(), binary()}]}
  | {:relative_date, bare_ast(), relative_direction()}

The position-free AST shape Predicator 3.6 produced, as returned by strip_positions/1. The visitors still consume this shape; they move to ast/0 when they learn to carry positions.

@type bare_object_key() :: {:identifier, binary()} | {:string_literal, binary()}

A position-free object key, as returned by strip_positions/1.

@type comparison_op() ::
  :gt | :lt | :gte | :lte | :eq | :equal_equal | :ne | :strict_eq | :strict_ne

Comparison operators in the AST.

@type membership_op() :: :in | :contains

Membership operators in the AST.

@type object_entry() :: {object_key(), ast()}

An object entry (key-value pair) in an object literal.

The key can be either an identifier or a string literal.

@type object_key() :: {:object_key, binary(), object_key_style(), position()}

A key in an object literal.

Object keys have their own tag rather than reusing the expression node tags, so no consumer has to tell a key from an expression by tuple arity. style records how the key was written - bare, or quoted with which character - so Predicator.Visitors.StringVisitor can render it back as the author wrote it.

@type object_key_style() :: :identifier | :double | :single

How an object key was written: bare ({name: 1}), double-quoted ({"name": 1}), or single-quoted ({'name': 1}).

@type parser_state() :: %{
  tokens: [Predicator.Lexer.token()],
  position: non_neg_integer()
}

Internal parser state for tracking position and tokens.

@type position() :: Predicator.Types.position() | nil

A node's source position, or nil when the node was not produced by the parser.

@type relative_direction() :: :ago | :future | :next | :last

Relative date directions in the AST.

@type result() :: {:ok, ast()} | {:error, binary(), pos_integer(), pos_integer()}

Parser result - either success with AST or error with details.

@type unary_op() :: :minus | :bang

Unary operators in the AST.

@type value() ::
  boolean()
  | integer()
  | binary()
  | [value()]
  | Date.t()
  | DateTime.t()
  | Predicator.Types.duration()

A value that can appear in literals.