Reference

std/encoding/structure

std/encoding/src/structure.trb

A type's structure as a value: Structure, the Structures describer that builds one, and the FieldDescription every field of a description carries.

Walking a visitor is harder than walking a tree, and every schema format wants a tree - a DDL statement, a .proto file, a JSON Schema, a --help text - so the conversion is written once here instead of once per format. A format that streams a schema implements Describer directly instead.

type FieldDescription

type FieldDescription

What the compiler knows about one constructor parameter, and what a schema or a help text needs of it.

field name

name: String

The field's name, as the type declares it.

field documentation

documentation: String = ""

The field's doc comment, as written: what an @description annotation is for in other languages.

field default

default: FieldDefault = FieldDefault.Required

Whether the field may be missing, and what it is then.

type FieldDefault

type FieldDefault

Whether a field may be missing from the input, and what it is then.

case Required

case Required

No default: the field has to be there.

case Computed

case Computed

A default the description cannot write as data: a call, or a value that is not a constant.

case Constant

case Constant(value: EncodedValue)

A default that is static data, and this is it.

type Structure

type Structure with Show

What a Describe walk builds when a format wants a value instead of a visitor.

Recursion is a Reference: the second time a type is opened the walk hands back its name and stops.

Examples

type Point {
  x: Int
  y: Int
}

print structureOf<Point>()

case Boolean

case Boolean

Bool.

case Integer

case Integer

A signed whole number.

case Natural

case Natural

A whole number that may not fit into an Int64.

case Floating

case Floating

A floating point number.

case Exact

case Exact

A Decimal.

case Text

case Text

A text.

case Binary

case Binary

Raw bytes.

case Optional

case Optional(of: Self)

A value that may be absent.

case Sequence

case Sequence(of: Self)

Many values of one structure, in order.

case Mapping

case Mapping(key: Self, value: Self)

A map from one structure to another.

case Record

case Record(typeName: String, fields: List<StructureField>)

A record, with its fields in declaration order.

case Wrapper

case Wrapper(typeName: String, of: Self)

A type that is its one value. It keeps its name, so a format can map it.

case Variant

case Variant(typeName: String, cases: List<StructureCase>)

A type with cases.

case Reference

case Reference(typeName: String)

A type that is already being described further up: the schema refers to it by name.

fn recordFields

fn recordFields(): List<StructureField>

The fields of a record, or nothing for everything else: what a tabular or a row-shaped format starts from.

fn declaredName

fn declaredName(): String

The qualified name of the declaration, or an empty text for a structure that has none.

fn show

fn show(): String

Record("app/Point", [x: Integer, y: Integer]).

type StructureField

type StructureField

One field of a Structure.Record: its description and the structure of the value it holds.

field description

description: FieldDescription

The field's name, doc comment and default.

field of

of: Structure

The structure of the value the field holds.

fn name

fn name(): String

The field's name.

fn isRequired

fn isRequired(): Bool

Whether the input has to have the field: it has no default and may not be absent.

type StructureCase

type StructureCase

One case of a Structure.Variant: its name and the structure of its own fields.

field name

name: String

The case's name.

field fields

fields: List<StructureField>

The fields of the case, in declaration order.

fn structureOf

fn structureOf<Value: Describe>(): Structure

The structure of a type, as a value.

Examples

print structureOf<List<Int>>()

type Structures

type Structures with Describer

A Describer that builds a Structure. The mirror image of Values, and the same state machine.

fn result

fn result(): Structure

What was described. Text when nothing was.

fn bool

var fn bool()

Completes the current description as Structure.Boolean.

fn int

var fn int()

Completes the current description as Structure.Integer.

fn unsigned

var fn unsigned()

Completes the current description as Structure.Natural.

fn float

var fn float()

Completes the current description as Structure.Floating.

fn decimal

var fn decimal()

Completes the current description as Structure.Exact.

fn string

var fn string()

Completes the current description as Structure.Text.

fn bytes

var fn bytes()

Completes the current description as Structure.Binary.

fn optional

var fn optional()

Opens an optional description; Structures.finish wraps the description in between in Structure.Optional.

fn sequence

var fn sequence()

Opens a sequence description; Structures.finish builds a Structure.Sequence from the item in between.

fn map

var fn map()

Opens a map description; Structures.finish builds a Structure.Mapping from the key and the value.

fn record

var fn record(typeName: String): Bool

Opens a record description and answers true. A name that was opened before completes as a Structure.Reference instead and answers false, so the caller leaves the body out.

fn variant

var fn variant(typeName: String): Bool

Opens a variant description as Structures.record opens a record: a known name completes as a Structure.Reference and answers false.

fn variantCase

var fn variantCase(name: String)

Opens the case name of the open variant; Structures.finish adds it as a StructureCase with its fields.

fn field

var fn field(description: FieldDescription)

Keeps description for the field whose structure completes next. It does nothing when no description is open.

fn finish

var fn finish()

Closes the innermost open description and completes it as the Structure its kind builds from what was described inside. It does nothing when none is open.