Chapter 1

Functions

A function at the Flow stage is a function of Code IR that is the body of one rule variant: a rule, or a part of its body that runs as a function of its own, lowered for one combination of the options below (Node, Budget and Document). The base's parts, its name, parameters, locals and body, are those of Code IR: its variables are the locals of the function, and its body is the base's structured control. The Flow dialect adds the following parts as attributes of the function.

Part Meaning
Name The function's name
Rule The rule of Core IR it is the body of
Variables Its variables, which are the locals of the function, each with a name unique in the function and a type, in the order they were made
Body Its statements. Running to the end of the body is success; an exit to the failure label is failure
Failure label The label that an exit takes to fail
Entry variables The start, the position at which the rule was entered, set before the body runs; the result, the rule's value; and the context of the rule's action. The code that holds the function declares them. A framed function has none
Binds The body may bind variables of the grammar, which the entry restores
Framed The function is framed (below)
Value The value with which a framed function succeeds; none where it cannot succeed
Cut The cut flag of the outermost scope of a framed function, a variable, which it reads from the register of the cut flag on entry
Node The function builds the values of the node runtime, and none of the typed runtime
Budget The function is lowered with budget controls, and charges the budget as Invariants requires
Document The function is lowered for a build with Documents, and reads input in place only as Invariants allows
Entered The function is lowered with budget controls and its entry is charged by the code that holds it: the function charges nothing for its entry and starts charged

Local and Framed Functions

A function is local or framed. A local function is a whole rule: it succeeds by running to its end, with the rule's value in the result variable, and fails by an exit to its failure label; its captures are variables. A framed function matches an expression whose captures the runtime keeps in a frame: the body of a left-recursion leader or of a rule that recovers, or a line of an Operators Rule. It succeeds with its value, and the runtime owns the frame, the rule's value and its finish. On both returns, success and failure, a framed function with a cut flag publishes it to the register of the cut flag again; the body holds no statement for that, and the code that holds the function writes it where the function returns.

Types

The types of the Flow stage are the types of Code IR: int and bool are its scalar types, and each of the others is a handle type of the component of the Flow dialect.

Type Values
int A position, a count or a length
bool A truth value
rune A code point
value A value of the runtime
env A variable environment
expmark A mark of the recorded expectations
expids A list of expectations
vals A list of values being gathered
ctx The context of an action
mark A mark of the whole state of a parse
frame A capture frame of the runtime
error A syntax error
run The run of a repetition that a Document parse resumes

Registers

A register is a register of the Code IR module (see The Module): a part of the state of a parse that functions read and assign directly.

Register Holds
pos The position
cut The cut flag of the scope the runtime entered last

The variable environment and the current capture frame, which hold handles, are read and assigned through the operations flow.env, flow.setEnv, flow.frame and flow.setFrame.

Variables, Labels and Places

Variables are declared for the whole function, so that any statement may exit to any enclosing label. A label names a block or a loop; a label without a name is never printed by a target, which names only the labels of blocks. A place, which an assignment assigns, is a variable, a register, or a discard, whose value is dropped.

Statements after an exit, up to the end of the block that is exited to or of the loop, are unreachable. Code IR keeps them at this stage, and a backend leaves out what is unreachable.