Built-in functions

This is the complete call surface of a rule. Everything a when or then can invoke is either an unqualified built-in, a method on a value, or a method on one of the bindings below. Nothing else is reachable. There is no import, no user-defined function, and no way to add one from a rule file.

Bindings

Five plugins are registered on every engine, util, log, findings, delivery and vocab, so the bindings they contribute are always there. bbox is registered on request.

Binding	Holds	Bound
in	fact reader, with defaults and dotted paths	every execution
out	the result collector returned to the caller	every execution
findings	severity-graded validation issues	every execution
audit	timestamped decision trail	every execution
to	conversion between the types a rule handles	every execution
num strings time math map array	helper libraries	every execution
util	namespace holder; carries no helper functions	every execution
log	structured logger	every execution
vocab	named phrase lists and lookup tables	every execution
delivery	output shaping	every execution
bbox	documents, and bbox.Doc()	every execution that supplies documents

bbox fails hard rather than degrading: naming it when no document was supplied aborts the whole execution with got non existent key bbox. Guard a document-dependent ruleset at the top rather than per rule.

Caution

Caller facts are bound after the helper libraries and overwrite them by name, a payload field called map, strings, time, math, num, array or util replaces that helper for the whole execution. The deployed service turns the entire request body into facts, so a request field named time breaks every rule that calls time.Now(). See The rule language.

Rules that govern every call

These four constraints decide whether a signature in the tables below is usable, and they are the reason some functions are marked not callable.

Constraint	Consequence
Integer literals are int64, float literals are float64, with no coercion	A parameter typed plain int, float32 or a named integer type cannot be satisfied. math.Min(10, 20) panics; write math.Min(10.0, 20.0)
Methods returning (value, error) are rejected by the dispatcher	out.JSON(), audit.JSON() and six document loaders parse but fail at evaluation
There is no array, map or struct literal in the grammar	A collection argument must be the direct result of another call, never a local variable
Any evaluation error aborts the whole execution	One bad call discards every value already collected

Chain a collection straight into the call that consumes it, or stage it through in.MemSet:

// WRONG - `rows` is a local variable holding a slice
rows = bbox.ExtractColumnAlignedSection("loan", "Origination Charges", "", "At Closing");
out.Set("row", array.FindRowBy(rows, "description", "homeowner"));

// CORRECT - stage through scratch memory
in.MemSet("rows", bbox.ExtractColumnAlignedSection("loan", "Origination Charges", "", "At Closing"));
out.Set("row", array.FindRowBy(in.MemGetRows("rows"), "description", "homeowner"));

Unqualified built-ins

Called with no binding prefix. These come from the rule engine itself.

Signature	Behaviour
Retract(ruleName)	Marks the named rule retracted for the rest of this execution. Reset on the next execution
Complete()	Hard stop. The engine exits the cycle loop immediately; lower-salience rules never run
Forget(snippet)	Clears the working-memory cache for an expression so it is re-evaluated next cycle
Changed(variableName)	Alias of Forget, kept for compatibility
Now()	Current time
MakeTime(year, month, day, hour, minute, second)	Builds a time value in the local zone
GetTimeYear(t)	Year component. Also GetTimeMonth, GetTimeDay, GetTimeHour, GetTimeMinute, GetTimeSecond
IsTimeBefore(t, before)	Ordering test. Also IsTimeAfter(t, after)
TimeFormat(t, layout)	Formats with a layout string
StringContains(str, substr)	Substring test
ContainsStr(list, v)	Membership test over a list produced by another call
IsZero(v)	Zero-value test for time, pointer, string and numeric kinds. A bool always reports false
IsNil(v)	Nil test. Panics on a non-nilable value such as a string
Log(text)	Writes to the engine’s own logger. Unrelated to the log binding
LogFormat(format, v)	Formatted engine log line
Max(vals ...)	Variadic maximum. Float literals only. Also Min
Round(x)	Rounds to a whole number. One argument: not the two-argument math.Round

The standard maths library is also wrapped unqualified: Abs, Acos, Acosh, Asin, Asinh, Atan, Atan2, Atanh, Cbrt, Ceil, Copysign, Cos, Cosh, Dim, Erf, Erfc, Erfcinv, Erfinv, Exp, Exp2, Expm1, Float64bits, Float64frombits, Floor, Gamma, Hypot, Ilogb, IsInf, IsNaN, J0, J1, Jn, Ldexp, MathLog, Log10, Log1p, Log2, Logb, Mod, NaN, Pow, Pow10, Remainder, RoundToEven, Signbit, Sin, Sinh, Sqrt, Tan, Tanh, Trunc. They take and return float64, except that Ilogb returns int, IsInf/IsNaN/Signbit return bool, Float64bits returns uint64, and IsInf, Jn, Ldexp and Pow10 take an int64 where the Go original takes int. Float64frombits is not callable, its parameter is uint64 and a rule literal is int64. MathLog is the natural logarithm, the name Log is taken by the engine logger.

Caution

IsNil is not a safe guard. It panics with reflect.Value.IsNil on string Value when handed a value that cannot be nil. Guard with in.Has(...) or out.Has(...) and &&, which short-circuits.

Methods on values

Any string-typed expression carries these directly, without a binding prefix.

Receiver	Methods
string	In(...), Compare(s), Contains(s), Count(s), HasPrefix(s), HasSuffix(s), Index(s), LastIndex(s), Repeat(n), Replace(old, new), Split(sep), ToLower(), ToUpper(), Trim(), Len(), MatchString(pattern)
array or slice	Len(), Append(v): appends in place, returns nothing
map	Len()
number or bool	none: calling any method on a numeric or boolean value is an error

"gold".In("gold", "platinum") is the idiomatic membership test and needs no helper.

The namespaces

Each is documented in full in the API reference: every method with its parameters and a worked rule. This page covers what is true across them; the reference covers each one.

Binding	Holds	Reference
in	Guard-free reads of the input facts	in: reading facts
out	The result collector	out: writing results
findings	Severity-graded validation results	Findings
audit	The decision trail	Findings
bbox	Documents, and bbox.Doc()	bbox: documents
to	Conversion between types	to: conversion
strings	Text, regex, phrase counting	strings: text
map, array	Collections	map and array
num, math, time	Arithmetic and dates	num, math, time
vocab	Named phrase lists and tables	vocab
log	Debug, Info, Warn, Error	Included plugins
delivery	Output shaping	Included plugins

Transform operations

The operation vocabulary bbox.PostprocessRows takes.

Operation	Effect
trim	Trims leading and trailing whitespace
upper	Upper case
lower	Lower case
normalize_spaces	Collapses every run of whitespace to a single space, then trims
trim_currency	Trims, removes every $ and ,, trims again

Chain by calling PostprocessRows again. Each call reads the rows the previous one returned.

Check the operation name against the table above before relying on it: a name outside this set leaves the value untouched rather than reporting itself, so the symptom is output that did not change.

Continue with

• The rule language: grammar, execution cycle, salience, facts
• Writing rules: file layout, loading, rule-set naming
• Rule patterns: branching, chaining, defaults
• Rules over documents: how bbox gets bound
• Troubleshooting: runtime error messages and what causes them