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

kis rules and rules.svc bind the same names, with one exception: bbox, the document surface, is loaded only by kis rules.

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 and dotted paths	`in`: reading facts
`out`	The output collector. What it holds is the result, and later rules read it	`out`: writing results
`findings`	Severity-graded validation results, returned beside `out`	Findings
`audit`	Append-only decision trail	Findings
`act`	Proposed writes to a data source, returned as actions	`act`
`agenda`	`agenda.Repeat()`: the rule that calls it may fire again	Writing rules
`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`	Ranges, numbers in text, arithmetic and dates	`num`, `math`, `time`
`name`, `date`, `address`	Splitting a person’s name, finding dates in text, splitting a postal address	Functions
`vocab`	Named phrase lists and lookup tables	`vocab`
`log`	Log lines: `Debug`, `Info`, `Warn`, `Error`	Included plugins
`delivery`	Output shaping: `ExplodeColumn`	Included plugins
`bbox`	The document surface, on a `kis rules` run that carries a document	`bbox`: documents

Two verbs are bound with no namespace:

Call	Effect
`Retract("RuleName")`	Removes another rule from the pool for the rest of this execution. A rule that fires is retracted automatically, so each fires at most once per run; retracting the rule itself is unnecessary
`Complete()`	Ends the execution immediately, keeping everything written so far. No other rule fires

The document surface

On a kis rules run, a document arrives as bbox, and everything a rule does with it starts at bbox.Doc(). rules.svc does not load documents.

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 what the call is good for:

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	Count it with `.Len()`, pass it to a `map`, `array` or `to` call, or pass a map or rows straight to `out.Set`. GRL cannot index or iterate one, and a local variable cannot hold one
Two values	Nothing. The call loads, then aborts the execution with `calling function <Fn> which returns multiple values`

What the load-time check catches

Every call a rule makes is checked when the rule set loads (kis rules check, kis rules --validate, rules.svc’s load): a method that does not exist, or the wrong number of arguments, is an error naming the rule and line, with a suggestion when one is close (strings has no method Trim (did you mean Join?)). A deprecated call loads with a warning naming its replacement.

What it does not catch, each of which aborts the execution when the rule is evaluated:

Mistake	Run-time failure	Write instead
An integer literal where a float is taken	`reflect: Call using int64 as type float64`	`0.0`, `10.0`
A bare fact name the caller did not send, in any rule’s `when`	`non existent key <name>`	`in.Str("name", "")` and the other `in` reads
Dot access on a map fact, `order.Total`	`this node identified as "order" is not referencing to an object`	`in.Double("order.Total", 0.0)`
A call that returns two values	`calling function <Fn> which returns multiple values`	Nothing: the call is not usable

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