ion7-grammar / ion7-grammar

class

Grammar

local Grammar = require "ion7.grammar"

-- From a Lua type annotation
local g = Grammar.from_type({ name = "string", age = "integer" })
local gbnf = g:to_gbnf()

-- From a JSON Schema
local g2 = Grammar.from_json_schema({ type = "object",
    properties = { status = { enum = { "ok", "error" } } },
    required = { "status" },
})

-- From an ABNF rulelist
local g3 = Grammar.from_abnf([[
    date = year "-" month "-" day
    year = 4DIGIT
    month = 2DIGIT
    day = 2DIGIT
]])

-- Compose grammars
local union   = g:union(g2)
local wrapped = g:then_(Grammar.from_regex("\\d+"))

Functions

Grammar.builder

Create a new Builder (returns Builder, not Grammar_obj).

Grammar.builder(opts)
optstable?{ root = "root" }
→ Builder

Grammar.from_builder

Wrap a Builder in a Grammar_obj.

Grammar.from_builder(b)
bBuilder
→ Grammar_obj

Grammar.from_json_schema

Build from JSON Schema (draft-07 subset, pure Lua).

Grammar.from_json_schema(schema, root)
schematable
rootstring?
→ Grammar_obj

Grammar.from_type

Build from Lua type annotation (shortest path to a grammar).

Grammar.from_type(typ, root)
typstring|table
rootstring?
→ Grammar_obj

Grammar.from_regex

Build from regex pattern (ERE subset).

Grammar.from_regex(pattern, root)
patternstring
rootstring?
→ Grammar_obj

Grammar.from_abnf

Build from ABNF rulelist (RFC 5234 §4 syntax). See `ion7.grammar.from.abnf` for the supported subset and the documented differences from strict RFC 5234 (case sensitivity, incremental alternatives, prose values).

Grammar.from_abnf(source, root)
sourcestringABNF source.
rootstring?Root rule name (default: first defined rule).
→ Grammar_obj

Grammar.from_ebnf

Build from EBNF rulelist (W3C-style — XML, JSON, SVG specs). See `ion7.grammar.from.ebnf` for the supported subset.

Grammar.from_ebnf(source, root)
sourcestringEBNF source.
rootstring?Root rule name (default: first defined rule).
→ Grammar_obj

Grammar.from_auto

Detect the source format and dispatch to the right `from_*` constructor. Heuristics: - Trimmed source starts with `{` → JSON Schema. - Contains `::=` → W3C-style EBNF. - Has a `name = body` line (no `::=` anywhere) → RFC 5234 ABNF. - Otherwise → regex. The heuristic is best-effort; if you know the format ahead of time, prefer the explicit constructor.

Grammar.from_auto(source, root)
sourcestringGrammar source in one of the supported formats.
rootstring?Root rule name override.
→ Grammar_obj

Grammar.from_enum

Build from value whitelist (longest-first, deduped).

Grammar.from_enum(rule_name, values)
rule_namestring
valuestable
→ Grammar_obj

Grammar.from_json_enum

Build from JSON-quoted value whitelist.

Grammar.from_json_enum(rule_name, values)
rule_namestring
valuestable
→ Grammar_obj

Grammar.from_tools

Build tool-call grammar from registry.

Grammar.from_tools(tools)
toolstableArray of { name, schema }.
→ Grammar_obj

Grammar.from_json_schema_native

Build from JSON Schema via the C++ libcommon backend. Routes the schema through libllama's `json_schema_to_grammar` for canonical handling of `$ref`, `allOf`, `anyOf`, `oneOf`, and the format validators. Returns a raw GBNF grammar.

Grammar.from_json_schema_native(schema, root)
schemastring|tableJSON Schema as string or Lua table.
rootstring?Root rule name (default: "root").
→ Grammar_obj

Grammar.tool_pipeline

Build tool-call grammar AND return a bound JSON parser.

Grammar.tool_pipeline(tools)
toolstable
→ Grammar_obj
→ functionparser(raw_output) → calls, err

Grammar.raw

Passthrough for hand-written GBNF strings.

Grammar.raw(gbnf)
gbnfstring
→ Grammar_obj

Grammar.context

Create a stateful GrammarContext.

Grammar.context(opts)
optstable?
→ GrammarContext

Grammar.backtrack

Create a Backtrack session (IterGen/CRANE style, KV cache rollback).

Grammar.backtrack(ctx, vocab, sampler, opts)
ctxany
vocabany
samplerany
optstable?
→ Backtrack

Grammar.dccd

Draft-Conditioned Constrained Decoding (arXiv:2603.03305).

Grammar.dccd(ctx, vocab, opts)
ctxany
vocabany
optstable
→ DCCD