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. |