Values

A Value is what a document read hands back — from a directional read, a cell, a line or a title. It is not yet a string or a number: you say which by coercing it.

out.Set("amount", bbox.Doc().Right("Loan Amount").Currency());

A Value that matched nothing is not an error. It stays a Value, coerces to a zero value, and knows why it is empty.

Coercions

Each returns a Value except Str() and Num(), which end the chain in a plain type.

Call	Produces
Str()	string — the matched text
Text()	Value — the text, still chainable
Num()	number
Number()	Value — numeric, still chainable
Currency()	Value — money, with symbols and separators handled
Date()	Value — a date
Percent()	Value — a percentage
YesNo()	Value — a boolean drawn from yes/no text
TitleCase()	Value — title-cased

Str() and Num() are the ones to finish on when the value is going into out.Set or a comparison. The Value-returning forms exist so you can keep chaining — .Currency().Str() gives you the normalised money text.

Inspecting a read

Call	Returns	Asks
Found()	bool	Did anything match?
Missing()	bool	The inverse
Or(fallback)	Value	This value, or the fallback when missing
Confidence()	number	How confident the match was
Match(pattern)	Value	The part of the match a pattern selects
Why()	string	Why the read produced nothing
Reason()	string	The same, as a plain reason string

Why() is the debugging entry point. A read built from an anchor chain knows which link broke, so a failing chain tells you the anchor rather than handing back an empty string:

when bbox.Doc().Right("Date Issued", "Closing Date").Missing()
then audit.Log("DateMissing", bbox.Doc().Right("Date Issued", "Closing Date").Why());

Guard with Found() or supply Or(...) when a missing value would otherwise write an empty key:

out.Set("borrower", bbox.Doc().Right("Borrower Name").Or("UNKNOWN").Str());

See also

• Document — the reads that produce a Value
• Tables and forms — cells and fields, which also return Value
• The Document API guide — the reasoning behind the surface