Chapter 3

Values: The Action Dialect

The component value holds the operations on the values of action expressions: actions, predicates and the values of bindings. They read and write no state of the parse. A value is a datum of the host, opaque to the rest of the abstract machine; these operations look inside it. Each acts on one kind of value and has none of the policy of an operator of the grammar: the compositions binary, unary, equal, index, logic, member, push, pushItems, items, itemAt, filterKeep, length, text, convert, cover, made and hull (see Compositions) decide which operation applies, which operands are valid and which failure an action expression reports. The tables of this chapter are shared by every target: a target numbers the operators, kinds and failures as they are numbered here, and prints the messages of the failures as they are written here, so that they read the same on all targets.

Value Kinds

The kind of a value, as val.kind returns it, is a code.

Code Kind Values
0 nil nil
1 int an int
2 string a string
3 bool a bool
4 other every other value: a node, a list, a tuple, a struct, and a box that holds a value, which val.unbox opens

Operators

A call of the composition binary, unary or logic passes the code of its operator: its index in the table of its group. The codes of the three groups are separate, so the first operator of each has the code 0.

Group Operators, by code from 0
Binary + add, - sub, * mul, / quo, % rem, == eq, != ne, < lt, <= le, > gt, >= ge, [] index
Unary - neg, ! not
Logical && and, || or

The last binary operator, the index of a list or a tuple, is not a scalar operator and takes the composition index. The names after the operators are the names by which targets name the codes.

Member Kinds

A member name of an action expression is the name of a field, a range or value member of a node (Start, End, Value), or a capture ($ and the name of the capture). The composition member takes the kind of a member read as a code. A range or value member reads the node itself only if the value is a node; of a struct or a list it is the field of that name. A field read returns the value that the field holds, and a list, a tuple or a struct keeps the range it had where it was made.

Code Kind Spelling Reads
0 field every other name A field
1 start Start The start of the range of a node
2 end End The end of the range of a node
3 value Value The value of a node
4 capture a name that begins with $ A capture

Every target classifies a name by this table: the whole name for the members of a node, the prefix for a capture.

Failures of an Action Expression

A failure of an action expression is reported to the code that evaluates the action expression, which decides what it does. In a Value Action it ends the parse with an error whose message is the text of the failure; in a Predicate Action it makes the predicate fail, and in a binding it makes the binding fail, and backtracking goes on as for any other failure. val.fail takes its code. In a text, {a} and {b} are the type names of the first and second value; {name} is the second value as a string, a member name or the name of a built-in function; {op} is the name of the operator that the operator code indexes, in the binary operators for invalid operands, invalid comparison and not a list, in the unary operators for invalid unary operand and in the logical operators for invalid logical operand; {i} is the first value as an int; and {n} is a count. A hint, where a failure has one, ends its message.

Code Failure Text Hint Meaning
0 division by zero division by zero A division or remainder by zero
1 invalid operands invalid operands {a} and {b} for {op} A binary operator applied to operands it does not accept
2 invalid comparison invalid operands {a} and {b} for {op} : nodes and other structured values cannot be compared; use text(x), or .Start and .End == or != with a value that is not nil, an int, a string or a bool
3 invalid unary operand invalid operand {a} for unary {op} A unary operator applied to an operand it does not accept
4 invalid logical operand invalid operand {a} for {op} A logical operator applied to an operand that is not a bool
5 not a list {op}: expected a list, got {a} A value that is not a list or a tuple used as one
6 index not an int index must be int, got {a} An index that is not an int
7 index out of range index {i} out of range for {n} elements An index out of range: {i} is the index, {n} the length
8 no members cannot access .{name} of {a} A member read of a value that has no members
9 no capture {a} has no capture {name} The read of a capture of a struct, which has none
10 no field {a} has no field {name} The read of a field that a struct type does not declare
11 not an element {name}: elements must be values, got {a} An element of a list or a tuple that is not a value, such as a function
12 argument not a list {name}: expected a list, got {a} An argument of a built-in function that takes a list and is not one
13 invalid len argument len: invalid argument {a} An argument of len that has no length
14 invalid text argument text: invalid argument {a} An argument of text that has no text
15 not convertible cannot convert {a} to {name} The conversion to a named node type of a value that is not a string, tuple or list node
16 filter result not a bool filter: predicate must produce a bool, got {a} A result of the function of filter that is not a bool

Cast Types

The type that a cast v.(T) checks a value against is a tree of kinds, each with a code, the code of its letter. The composition conforms decides whether a value is of a type; the shape of a node, as node.shape returns it, tells which kind of value a node is.

Letter Kind Takes
i int an int
s string a string
b bool a bool
z nil nil
_ top every value
o optional nil and the values of its element type
u join the values of one of its alternatives
n node a node whose value is a string, a tuple or a list
S string node a node whose value is a string
E error an error value
M missing the error value of a missing token, where the target has one
N named a struct or a node of the type of its name
l list a list value whose elements are of its element type
t tuple a tuple value with as many elements as it has element types, each of its type
v node of a type a node whose value is of its element type

The shapes are 0 string, 1 tuple, 2 list, 3 error, 4 box, 5 tuple value, 6 list value and 7 struct. A box stands for the value it holds. Each element of a list or a tuple that the check examines charges one step (seq.step); the list type whose element type is top charges none, and a tuple of another length is refused before any.

Operations on Values

Declaration State Cost Contract
op val.kind(x Datum) int none 0 Returns the kind of x: the kind nil for nil, int for an int, string for a string, bool for a bool and other for every other value, a box that holds one of these included. Law (equal results): equal arguments give equal results.
op val.unbox(x Datum) Datum none 0 Returns the value that x stands for: the value a box holds, and x for any other value. Law (equal results): equal arguments give equal results.
op val.fromBool(b bool) Datum none 0 Returns the bool value b.
op val.fromInt(i int) Datum none 0 Returns the int value i.
op val.toBool(x Datum) bool none 0 Returns the bool that x is. Requires: x is a bool: val.kind(x) is the kind bool.
host op val.fail(code int, a Datum, b Datum, op int, n int) Fail noreturn none 0 + 2*error_parts Returns the failure with the code code: {a} and {b} read as the names of the types of a and b, {op} as the name of the operator that op indexes (a binary operator for invalid operands and invalid comparison, a unary operator for invalid unary operand and a logical operator for invalid logical operand), {i} as a, an int, and {n} as n. A failure is a Fail, not a value of an action expression: the caller returns it and the action expression evaluation reports it, each target in its own form of failure. A target that bounds the work assembles the text piece by piece, charging for each piece. Requires: code indexes ActionErrors, and the arguments are those its message names.
op int.add(l Datum, r Datum) Datum none 0 Returns l + r with 64-bit wraparound. Requires: l and r are ints. Law (equal results): equal arguments give equal results.
op int.sub(l Datum, r Datum) Datum none 0 Returns l - r with 64-bit wraparound. Requires: l and r are ints. Law (equal results): equal arguments give equal results.
op int.mul(l Datum, r Datum) Datum none 0 Returns l * r with 64-bit wraparound. Requires: l and r are ints. Law (equal results): equal arguments give equal results.
op int.quo(l Datum, r Datum) Datum none 0 Returns l / r truncated toward zero; the least int divided by -1 is the least int. Requires: l and r are ints, and r is not zero. Law (equal results): equal arguments give equal results.
op int.rem(l Datum, r Datum) Datum none 0 Returns the remainder of l / r, with the sign of l; the remainder of the least int by -1 is zero. Requires: l and r are ints, and r is not zero. Law (equal results): equal arguments give equal results.
op int.neg(x Datum) Datum none 0 Returns -x with 64-bit wraparound: the negation of the least int is itself. Requires: x is an int. Law (equal results): equal arguments give equal results.
op int.zero(x Datum) bool none 0 Reports whether x is zero. Requires: x is an int.
op int.cmp(l Datum, r Datum) int none 0 Returns -1 if l is less than r, 0 if they are equal and 1 if l is greater. Requires: l and r are ints. Law (equal results): equal arguments give equal results.
op int.index(x Datum, n int) (int, bool) none 0 Returns x as an int and true if 0 <= x < n, and 0 and false otherwise. Requires: x is an int. Law (equal results): equal arguments give equal results.
host op str.add(l Datum, r Datum) Datum noreturn none 1 + 4*value_bytes Returns the concatenation of l and r. A target that bounds the work charges for the bytes it reads and copies. Requires: l and r are strings.
host op str.cmp(l Datum, r Datum) int noreturn none 1 + 4*value_bytes Returns -1 if l is less than r, 0 if they are equal and 1 if l is greater, comparing by code point: the order of the bytes of UTF-8 and not of the code units of UTF-16. A target that bounds the work charges for the bytes it compares. Requires: l and r are strings.
host op str.eq(l Datum, r Datum) bool noreturn none 1 + 4*value_bytes Reports whether l and r are the same string. A target that bounds the work charges for the bytes it compares. Requires: l and r are strings.
op seq.items(x Datum) (Seq, bool) none 0 Returns the elements of x and true if x is nil (no elements), a list or a tuple, and false otherwise. Law (equal results): equal arguments give equal results.
op node.of(x Datum) (Obj, bool) none 0 Returns x and true if x is a value that has members (a node, a list, a tuple or a struct), and false for every other value: nil, an int, a string and a bool. Law (equal results): equal arguments give equal results.
op node.isNode(n Obj) bool none 0 Reports whether n is a node, which has a range and a value: a value of a node type, a string node or an error, and not a struct, a list value or a tuple value.
op node.start(n Obj) Datum none 0 Returns the start of the range of n as an int. Requires: node.isNode(n).
op node.end(n Obj) Datum none 0 Returns the end of the range of n as an int. Requires: node.isNode(n).
op node.value(n Obj) Datum none 0 Returns the value of n: its text, or the value its node type holds. Requires: node.isNode(n).
op node.isStruct(n Obj) bool none 0 Reports whether n is a value of a struct type.
host op node.field(n Obj, name Name) (Datum, bool) noreturn none 0 + 2*fields_read + 4*value_bytes Returns the field name of n and true if n holds it, and nil and false otherwise. A struct of a target that represents it with every field holds them all. A target that bounds the work charges for the fields it scans and the bytes of the names it compares.
host op node.zero(c Act, n Obj, name Name) (Datum, bool) noreturn none 0 + 2*zero_parts Returns the zero value of the declared type of the field name of the struct n, made in c, and true, or nil and false if the type of n declares no such field or the target holds every field of a struct (node.field then holds it). A target that bounds the work charges for the values it makes. Requires: node.isStruct(n).
op node.span(n Obj) (int, int) none 0 Returns the start and the end of the range of n, a node, a struct, a list value or a tuple value, as ints.
host op val.seq(c Act, tuple bool, kids Seq) Obj noreturn none 1 Returns a new tuple value if tuple and a new list value otherwise, made in c, whose elements are kids, which it takes over, and whose range is empty. A target that bounds the work charges for the value it makes.
op seq.span(c Act, items Seq, i int) (int, int, bool) none 0 Returns the start and the end of the range that element i of a list value or a tuple value being made in c adds to the range of the value, as ints, and true if it adds one, and false (and no meaningful range) if it adds none. An element that is a node, a list, a tuple or a struct adds its own range. An int, a string or a bool adds the range of the rule c evaluates the action expression of, which a target whose elements are nodes has given its box; nil adds none. Requires: items came from seq.items or is the element list of a value being made in c, and 0 <= i < seq.len(items).
op act.span(c Act) (int, int) none 0 Returns the start and the end of the range of the rule that c evaluates the action expression of, as ints.
op node.typeName(t NodeType) Name none 0 Returns the name of the named node type t, as the {name} of a failure reads it.
op node.hasBase(n Obj) bool none 0 Reports whether n is a string node, a tuple node or a list node, of a named node type or not, which a conversion converts: not an error, a box, a list value, a tuple value or a struct.
op node.convert(n Obj, t NodeType) Datum none 0 Returns n as a node of the named node type t: n itself if it has the type, and otherwise a new node with the range, the value and the captures of n, the type t and no rule name, which keeps what n holds now. Requires: node.hasBase(n).
op val.name(name Name) Datum none 0 Returns name as a string value, as the {name} of a failure reads it.
op node.elem(n Obj) Elem none 0 Returns n as an element of a list or a tuple: n itself. Law (equal results): equal arguments give equal results.
host op val.box(c Act, x Datum) Elem noreturn none 1 Returns x as an element of a list or a tuple: in a target whose elements are nodes, a box that holds x with the range of the input of c, made in c, and x itself in a target whose elements are any values. A target that bounds the work charges for the box it makes. Requires: x is an int, a string or a bool.
op node.hasText(n Obj) bool none 0 Reports whether n is a string node or an error, whose text is the input of its range.
op node.width(n Obj) Datum none 0 Returns the length of the range of n, in the position unit, as an int.
op node.count(n Obj) Datum none 0 Returns the number of elements or children of n as an int.
op node.heldText(n Obj) (Str, bool) none 0 Returns the text that n holds and true if n is a string node or an error, and false otherwise; the text is then not meaningful.
host op node.rangeText(n Obj) Str noreturn none 1 + 1*value_bytes Returns the input of the range of n. A target that bounds the work may charge for the read of the input, and for the bytes it copies out of a stream.
host op str.len(x Datum) Datum noreturn none 0 + 1*value_bytes Returns the length of the string x in the position unit as an int. A target that bounds the work and counts characters charges for the bytes it reads. Requires: x is a string.
op str.of(x Datum) Str none 0 Returns the string x. Requires: x is a string.
op str.empty() Str none 0 Returns the empty string.
op ftype.kind(t FType) int none 0 Returns the kind of the type t: the code of the letter of the type kinds. Law (equal results): equal arguments give equal results.
op ftype.elem(t FType) FType none 0 Returns the element type of the list type, the optional type or the node type t whose value has a type. Requires: t is of kind list, optional or node of a type. Law (equal results): equal arguments give equal results.
op ftype.count(t FType) int none 0 Returns the number of the alternatives of the join type or the element types of the tuple type t. Requires: t is of kind join or tuple. Law (equal results): equal arguments give equal results.
op ftype.alt(t FType, i int) FType none 0 Returns alternative i of the join type or element type i of the tuple type t. Requires: t is of kind join or tuple, and 0 <= i < ftype.count(t). Law (equal results): equal arguments give equal results.
op node.shape(n Obj) int none 0 Returns the shape of n: string, tuple, list, error, box, tuple value, list value or struct, which a value of a node type has by its base. Law (equal results): equal arguments give equal results.
op node.isType(n Obj, t FType) bool none 0 Reports whether the type name of n is the name of the type t: a struct type or a named node type. Requires: t is of kind named.
op node.isMissing(n Obj) bool none 0 Reports whether n is the error value of a missing token. A target that has no missing tokens reports false.
op node.children(n Obj) Seq none 0 Returns the elements of the list value or the tuple value n, and the children of any other node. Law (equal results): equal arguments give equal results.
host op seq.step() noreturn none 1 Charges the step of one element of a list or a tuple: an element that is examined against its type, walked by a built-in function or made by a constructor. A target that bounds the work charges one unit; a target that does not charges nothing.
host op units.add(n int) noreturn none 0 Counts n logical compute units of values that the plain evaluation builds and the lowering does not.
host op units.items(v Datum, k int) noreturn none 0 Counts k logical compute units for each element of the list or the tuple v.
host op units.since(mark int) noreturn none 0 Counts a logical compute unit for each element gathered since mark (action.kids).
op seq.len(items Seq) int none 0 Returns the number of elements. Requires: items came from seq.items.
op seq.at(items Seq, i int) Datum none 0 Returns element i as a value: the value a box holds, and nil for a missing element. Requires: items came from seq.items, and 0 <= i < seq.len(items).

Operations That Write Host State

The component host holds these operations, which write the host and so are not operations of the component value.

Declaration State Cost Contract
op node.setSpan(n Obj, start int, end int) noreturn writes host 0 Sets the range of n to start and end. It is for a value that an action expression is making, which no one has read.

Elements Gathered

The operations of the component gathered: a stack of the elements of the lists and tuples that action expressions are making. A list or a tuple takes its elements off the stack in one piece when it is made, which charges for copying each element and for taking it off in one reservation, and an action expression that the parser abandons leaves its elements, which the predicate and the binding drop. The stack is the parser's: grammar code that collects the elements of a repetition may use it too, above the elements it finds and taking off what it pushes, so that a action expression finds the stack as it left it.

Declaration State Cost Contract
op act.push(c Act, e Elem) noreturn writes gathered 0 Pushes e on the elements gathered, as the next element of the innermost list or tuple that c is making.
op act.pushAll(c Act, items Seq) noreturn writes gathered 0 + 1*seq_len Pushes the elements of items in order, as act.push pushes each. A target that bounds the work charges one unit for each element it copies. Requires: items came from seq.items.
op action.kids() int reads gathered 0 Returns the number of the elements gathered, which action.dropKids takes as a mark.
op action.dropKids(mark int) noreturn writes gathered 0 + 1*dropped Drops the elements gathered after the mark, and charges one unit for each. Requires: mark came from action.kids and is at most the number of the elements gathered.
op action.elemsAbove(mark int) Seq noreturn reads gathered; writes gathered 0 + 2*dropped Takes the elements gathered after the mark off the elements gathered and returns them in order, for a list or a tuple to take over. It charges two units for each: one for copying it and one for taking it off, as action.dropKids charges for dropping it, in one reservation before it moves any. Requires: mark came from action.kids and is at most the number of the elements gathered.
op action.keep(items Seq, i int) noreturn writes gathered 0 Pushes element i of items as it is (a box stays a box), as act.push pushes an element, as the next element of the list that filter makes. Requires: items came from seq.items, and i is at least 0 and less than the number of its elements.

Values Made

The operations of the component made: a list of the structs that action expressions and actions made. The context of an action expression or an action holds the length of the list when it is made (action.ctx). When an action returns a struct that it recorded, the struct takes the range of the rule; when an action expression or an action ends, what it recorded is forgotten, which the predicate and the binding do with action.dropCreated.

Declaration State Cost Contract
op act.made(c Act, n Obj) noreturn writes made 0 Records n after the values made, as a value that c made. Requires: n is a struct that c made, and no act.made recorded it.
op action.created() int reads made 0 Returns the number of the values made, which action.dropCreated takes as a mark.
op action.dropCreated(mark int) noreturn writes made 0 + 1*dropped Forgets the values made after the mark, without changing them, and charges one unit for each. Requires: mark came from action.created and is at most the number of the values made.