Language Reference

The complete Predicator expression language: data types, operators, builtin functions, decompile formatting, and error shapes. For the grammar with precedence, see Architecture.

Data Types

• Numbers: 42, -17 (integers), 3.14, -2.5 (floats)
• Strings: 'hello', 'world' (single-quoted) or "hello", "world" (double-quoted, with escape sequences)
• Booleans: true, false (or plain identifiers like active, expired)
• Dates: #2024-01-15# (ISO 8601 date format)
• DateTimes: #2024-01-15T10:30:00Z# (ISO 8601 datetime format with timezone)
• Durations: Natural units for time spans (e.g., 3d, 2h, 15m)
  • In relative expressions: 3d ago, 2w from now, next 1mo, last 1y
  • In arithmetic: #2024-01-10# + 5d, #2024-01-15T10:30:00Z# - 2h
• Lists: [1, 2, 3], ['admin', 'manager'] (homogeneous collections)
• Objects: {}, {name: "John", age: 30}, {user: {role: "admin"}} (JavaScript-style object literals)
• Identifiers: score, user_name, is_active, user.profile.name, user['key'], items[0] (variable references with dot notation and bracket notation for nested data)

Arithmetic Operators

Comparison Operators

Deprecated: = as equality. Using = for equality still works and still compiles to ["compare", "EQ"], but parsing one emits a deprecation warning. Predicator 4.0 makes expression-position = a parse error - = is being reserved for assignment in the forthcoming statement grammar. Migrate to == before upgrading. Silence the warning with config :predicator, deprecation_warnings: false. See ADR-0002 for the reasoning.

Logical Operators

Membership Operators

Builtin Functions

String Functions

iex> Predicator.evaluate("len('hello')", %{})
{:ok, 5}

iex> Predicator.evaluate("upper('world')", %{})
{:ok, "WORLD"}

iex> Predicator.evaluate("starts_with('hello world', 'hello')", %{})
{:ok, true}

iex> Predicator.evaluate("ends_with('hello world', 'world')", %{})
{:ok, true}

iex> Predicator.evaluate("substring('hello world', 6)", %{})
{:ok, "world"}

iex> Predicator.evaluate("substring('hello world', 0, 5)", %{})
{:ok, "hello"}

iex> Predicator.evaluate("index_of('hello world', 'world')", %{})
{:ok, 6}

iex> Predicator.evaluate("index_of('hello world', 'nope')", %{})
{:ok, -1}

Numeric Functions

iex> Predicator.evaluate("Math.abs(-5) == 5", %{})
{:ok, true}

iex> Predicator.evaluate("Math.max(1, 2) == 2", %{})
{:ok, true}

iex> Predicator.evaluate("Math.pow(2, 10) == 1024", %{})
{:ok, true}

Date Functions

iex> Predicator.evaluate("Date.year(created_at) == 2024", %{"created_at" => ~D[2024-03-15]})
{:ok, true}

Numeric and date functions moved under the Math. and Date. namespaces to avoid colliding with likely user variable names; the unnamespaced string functions predate that convention and were left as-is.

Decompiling and Formatting Options

Predicator.decompile/2 converts a parsed AST back to source, preserving quote style, with formatting options:

iex> {:ok, ast} = Predicator.parse("score > 85")
iex> Predicator.decompile(ast, spacing: :compact)
"score>85"

iex> {:ok, ast} = Predicator.parse("score > 85")
iex> Predicator.decompile(ast, spacing: :verbose)
"score  >  85"

iex> {:ok, ast} = Predicator.parse("score > 85")
iex> Predicator.decompile(ast, parentheses: :explicit)
"(score > 85)"

Error Shapes

Predicator returns errors as structs under Predicator.Errors, never as bare strings, and never raises at a leaf:

iex> {:error, err} = Predicator.evaluate("score >> 85", %{})
iex> {err.__struct__, err.line, err.column}
{Predicator.Errors.ParseError, 1, 8}

iex> {:error, err} = Predicator.evaluate("score AND", %{})
iex> {err.__struct__, err.column}
{Predicator.Errors.ParseError, 10}

A function that errors mid-evaluation surfaces as an EvaluationError:

iex> custom_functions = %{"divide" => {2, fn [a, b], _ctx ->
...>   if b == 0, do: {:error, "Division by zero"}, else: {:ok, a / b}
...> end}}
iex> {:error, err} = Predicator.evaluate("divide(10, 0)", %{}, functions: custom_functions)
iex> {err.__struct__, err.message}
{Predicator.Errors.EvaluationError, "Division by zero"}

See the location expressions guide for Predicator.Errors.LocationError, the third error struct.