`bbox`, documents

bbox is the document surface. Almost every rule uses exactly one function on it, bbox.Doc(), and the rest of this page is the surface around it.

If you are writing a rule that reads a document, you want Document, not this page.

bbox is bound only on a run that carries a document. A rule that names it on a run without one aborts the execution with non existent key bbox.

Reaching a document

`bbox.Doc(name?)` → Doc

Returns the document as the curated rule-facing facade.

Parameter	Type	Meaning
`name`	string, optional	Which loaded document. Omit for the usual single-document case

With no name, bbox.Doc() returns the only loaded document, or the one named page when several are loaded. The name earns its place only when a rule genuinely works across more than one loaded document.

rule ClassifyByHeader "identify the form from its header band" salience 100 {
    when
        bbox.Doc().Top(10).Has("Closing Disclosure")
    then
        out.Set("docType", "closing_disclosure");
}

Everything a rule does with a document starts here and chains: a scope, a verb, a coercion. See Document for the methods on the returned Doc.

`bbox.Get(name)` → Document: deprecated

Returns a loaded document as the raw document object. Deprecated: use bbox.Doc(name). It still loads, with a warning naming bbox.Doc as the replacement.

Parameter	Type	Meaning
`name`	string	The document name

bbox.Get hands a rule the internal document object and everything it exports. That was never a designed surface, and it changes as the implementation does. bbox.Doc() is the surface that is designed, documented and stable.

Loading a document

kis rules loads documents before the rules run, so a rule does not load one itself. To compare against a second document, a prior version or a schedule referenced by the main form, pass it on the command line under its own name (--bbox prior=prior.bbox) and reach it with bbox.Doc("prior").

The bbox object also carries the loaders a program embedding the engine uses. From rule text:

Call	From a rule
`bbox.LoadFromFile(name, path)` · `bbox.LoadFromMap(name, data)` · `bbox.LoadFromEnv(name, envVar)` · `bbox.GetOrLoad(name, path)`	Not callable. Each returns a document and an error, and the call aborts the execution with `calling function … which returns multiple values`
`bbox.LoadFromBytes(name, data)` · `bbox.LoadFromReader(name, r)`	Not callable. They take bytes and a stream, which no rule value is
`bbox.MustLoadFromFile(name, path)`	Loads a document file from the machine running the rules, or aborts the execution when it cannot. Prefer `--bbox`

Managing what is loaded

`bbox.Has(name)` → bool

Whether a document with this name is loaded.

Parameter	Type	Meaning
`name`	string	The document name

rule ComparePriorVersion "only compare when a prior version was supplied" {
    when
        bbox.Has("prior") && bbox.Doc("prior").Has("Loan Amount")
    then
        out.Set("priorAmount", bbox.Doc("prior").Right("Loan Amount").Currency());
}

`bbox.Names()` → list of string

Every loaded document name. Diagnostic: log it when a named lookup returns nothing.

`bbox.Remove(name)`

Removes one document.

Parameter	Type	Meaning
`name`	string	The document to remove

`bbox.Clear()`

Removes every loaded document.

Both are host-lifecycle operations. A rule that removes the document other rules are about to read is a rule whose ordering now matters in a way nothing else expresses.

Geometry constructors

These build the coordinate and direction values that methods of the raw document object take, reached only through the deprecated bbox.Get. Rules written against bbox.Doc() need none of them: Top(10), Right("Label") and Region(...) take plain numbers and strings.

`bbox.Box(x0, y0, x1, y1)` → BoundingBox

Parameter	Type	Meaning
`x0`, `y0`, `x1`, `y1`	float64	The rectangle’s corners

`bbox.Pt(x, y)` → Point

Parameter	Type	Meaning
`x`, `y`	float64	The coordinates

`bbox.Dir(name)` → Direction

Parameter	Type	Meaning
`name`	string	`"right"`, `"left"`, `"above"` or `"below"`

`bbox.RelDir(name)` → RelativeDir

Same vocabulary, for the methods that take a relative direction.

Parameter	Type	Meaning
`name`	string	`"right"`, `"left"`, `"above"` or `"below"`

`bbox.GeoBox(x0, y0, x1, y1)` → Box · `bbox.GeoDir(name)` → Direction

The geometry-package forms, for the fuzzy-search methods.

Parameter	Type	Meaning
`name`	string	`"right"`, `"left"`, `"up"` or `"down"`: note up/down, not above/below

The vocabulary difference between Dir and GeoDir is a genuine trap: bbox.GeoDir("above") is not a direction this constructor knows.

Column-aligned sections

`bbox.ExtractColumnAlignedSection(docName, sectionStart, sectionEnd, columnHeaders)` → list of map

Extracts rows from a columnar form section: auto-detects column positions from the page header labels, finds the section boundaries by fuzzy match, and returns the rows between them.

Parameter	Type	Meaning
`docName`	string	The document name. `--with-bbox` loads documents as `page`
`sectionStart`	string	The heading the section starts at
`sectionEnd`	string	The heading it ends at, or `""` for the page bottom
`columnHeaders`	string	Comma-separated column labels

Each row is a map with description, row_number, and one key per column header. An unknown document name returns nothing.

For anything new, prefer bbox.Doc().Rows(start, end): it is the same capability on the curated facade, with per-column naming and typing, and it does not need the document name.

rule ExtractPaymentSchedule "pull the payment schedule rows" {
    when
        bbox.Doc().Has("Payment Schedule")
    then
        out.Set("schedule",
            bbox.ExtractColumnAlignedSection("page", "Payment Schedule", "Total",
                "Date,Principal,Interest,Balance"));
}

The headers are comma-separated, so a vocab.List, which joins with |, does not fit this parameter.

`bbox.PostprocessRows(rows, key, fn)` → list of map

Applies a named operation to the text value at key in every row, in place, and returns the rows. A row whose key is missing or not text is left alone, and an unknown fn changes nothing.

Parameter	Type	Meaning
`rows`	list of map	The rows to clean
`key`	string	The column to operate on
`fn`	string	The operation

`fn`	Effect
`trim`	Strip leading and trailing whitespace
`upper`	Upper-case
`lower`	Lower-case
`normalize_spaces`	Collapse runs of whitespace to one space
`trim_currency`	Remove `$` and `,`, then trim
`ExtractRegex("pattern", "default")`	Keep the first match (its capture groups joined, when it has any), or `default` when nothing matches

Call it repeatedly to chain operations on the same column.

rule CleanScheduleAmounts "normalise the amount column before storing" {
    when
        out.Has("schedule")
    then
        out.Set("schedule",
            bbox.PostprocessRows(
                bbox.PostprocessRows(to.Rows(out.Get("schedule")), "amount", "trim"),
                "amount", "trim_currency"));
}

The nesting is the chaining. Each call returns the rows for the next to take. Beyond two or three steps, a Rows read with typed columns is clearer.

`bbox`, documents

Reaching a document

bbox.Doc(name?) → Doc

bbox.Get(name) → Document: deprecated

Loading a document

Managing what is loaded

bbox.Has(name) → bool

bbox.Names() → list of string

bbox.Remove(name)

bbox.Clear()

Geometry constructors

bbox.Box(x0, y0, x1, y1) → BoundingBox

bbox.Pt(x, y) → Point

bbox.Dir(name) → Direction

bbox.RelDir(name) → RelativeDir

bbox.GeoBox(x0, y0, x1, y1) → Box · bbox.GeoDir(name) → Direction