Rule API reference

This reference covers what a rule can call, and nothing else. If a name is not on these pages, rule text cannot reach it.

That boundary is the point of the section. The engine is a library, and most of its surface exists for the program that embeds it — constructing an engine, loading rule sets, reading a result object. None of that is available inside a when or a then. You write GRL; this is the GRL-visible API.

Bound into every execution

Name	What it is	Reference
your facts	Every top-level key of the input, bound under its own name	Writing rules
in	Guard-free reads of those facts, with defaults	in — reading facts
out	The output collector. What it holds is the result	out — writing results
findings	Severity-graded validation results	Findings
audit	Append-only decision trail	Built-in functions
bbox	The document surface, when the run carries a document	bbox — documents
to	Conversion between the types a rule handles	to — conversion
strings	Text: case, regex, phrase counting, line location	strings — text
map, array	Collections, since the language cannot index one	map and array
num, math, time	Arithmetic, ranges and dates	num, math, time
vocab	Named phrase lists and lookup tables	vocab
log	Log lines — Debug, Info, Warn, Error	Built-in functions
delivery	Output shaping — ExplodeColumn	Included plugins

Every one of the 337 callable methods across these is documented, with its parameters and a rule that uses it.

Two verbs are bound with no namespace:

Call	Effect
Retract("RuleName")	Removes a rule from the pool for the rest of this execution. Optional — a rule is retracted automatically after it fires
Complete()	Ends the execution immediately, keeping everything written so far

The document surface

A document arrives as bbox, and everything a rule does with it starts at bbox.Doc():

bbox.Doc().Top(20).Has("INVOICE")
bbox.Doc().Right("Loan Amount").Currency()

Type	Reached by	Reference
Doc	bbox.Doc(), and every scope call on it	Document
Value	A directional read, a cell, a coercion	Values
Table, Row	bbox.Doc().Table(), .TableWith(text)	Tables and forms
Rows	bbox.Doc().Rows(start, end)	Tables and forms
Form	bbox.Doc().Form(name)	Tables and forms

Matching through this surface is fuzzy and case-insensitive by default. You do not configure it; you opt out with Exact() or MatchCase() when a near-miss would be wrong. See the Document API guide for why.

How to read the tables

Every entry names what a rule gets back, because that is what decides whether the call is usable at all:

Returns	What a rule can do with it
bool, number, string	Use it directly, in a when or as an argument
Doc	Keep chaining scopes and verbs
Value	Coerce it, or ask whether it was found
Table / Row / Rows / Form	Keep calling that type’s methods
A list or map	Only .Len(). GRL cannot index or iterate one — pass Records() straight to out.Set
Two values	Nothing. The grammar rejects a call that returns a value and an error

That last row catches people. A method returning a value and an error is not callable at all; the failure is calling function <Fn> which … returns multiple values.

Deliberately not here

Not documented	Why	Where it is
Engine construction, rule-set loading, result objects	Not reachable from rule text	The library’s own source
Word boxes, lines, reading order, table detection	Analysis that happens before your rule runs	The document model
hOCR ingest and the .bbox format	Input preparation, not a rule call	OCR input
Fuzzy scoring internals	A property of the surface, not a knob	The Document API

See also

• The Document API — the same surface as a guide, with the reasoning
• Writing rules — rule structure, salience, chaining
• The rule language — grammar, operators, what the language lacks
• Functions — the helper namespaces in full
• Errors — every message, with cause