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: kis rules registers it when a run has document input. rules.svc serves no documents.

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
act	proposed writes to records	every execution
agenda	agenda.Repeat(): keeps the firing rule on the agenda for another cycle	every execution
num strings time math map array	helper libraries	every execution
name	splits a person’s name: name.First(v), name.Last(v), name.Parse(v)	every execution
date	finds dates inside text: date.First(v), date.Last(v), date.Nth(v, n)	every execution
address	splits a postal address: address.City(v), address.Zip(v), address.Parse(v)	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()	kis rules executions that supply 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. Under kis rules, an input field called map, strings, time, math, num, array or util replaces that helper for the whole execution, so a field named time breaks every rule that calls time.Now(), and a field named out, in, findings or audit is replaced by the collector. rules.svc refuses a fact with any name the engine binds itself (400 rules-facts-invalid). See The rules service.

Rules that govern every call

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

Constraint	Consequence
Every call on a binding is checked when the rule set loads	A method that does not exist, or the wrong number of arguments, is an error naming the rule and line: rules.svc and kis rules check refuse the set, kis rules --validate lists it. Argument types are not checked; see Validating a rule set
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) loads, then panics when it runs; write math.Min(10.0, 20.0)
Methods returning (value, error) are rejected by the dispatcher	out.JSON(), audit.JSON() and findings.JSON() load 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	rules.svc returns what was written before it under meta.partial; kis rules reports the error and no result

Chain a collection straight into the call that consumes it, or stage it with out.Set and read it back:

// WRONG - `parts` is a local variable holding a list
parts = strings.Split(in.Str("codes", ""), ",");
out.Set("first", parts[0]);

// CORRECT - index the call directly
out.Set("first", strings.Split(in.Str("codes", ""), ",")[0]);

// CORRECT - stage a list of records with out.Set, read it back, then drop it from the result
out.Set("rows", in.Rows("lines"));
out.Set("row", array.FindRowBy(out.Value("rows").Rows(), "description", "homeowner"));
out.Delete("rows");

Unqualified built-ins

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

Signature	Behaviour
Retract(ruleName)	Takes the named rule off the agenda for the rest of this execution. Reset on the next execution. A rule already leaves the agenda when it fires, so a rule never needs to retract itself
Complete()	Hard stop. The engine exits the cycle loop immediately; lower-salience rules never run
Forget(snippet) / Changed(variableName)	Clear the engine’s cache of evaluated expressions. Not needed: a write to out is already seen by later rules. Kept so existing rules load
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
act	Proposed writes to records	act: proposed writes
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
ExtractRegex("pattern", "default")	Keeps the pattern’s capture groups, joined, or the whole match when it has none; the default when it does not match

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