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: Structure)

A value that may be absent.

case Sequence

case Sequence(of: Structure)

Many values of one structure, in order.

case Mapping

case Mapping(key: Structure, value: Structure)

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: Structure)

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()

Not documented.

fn int

var fn int()

Not documented.

fn unsigned

var fn unsigned()

Not documented.

fn float

var fn float()

Not documented.

fn decimal

var fn decimal()

Not documented.

fn string

var fn string()

Not documented.

fn bytes

var fn bytes()

Not documented.

fn optional

var fn optional()

Not documented.

fn sequence

var fn sequence()

Not documented.

fn map

var fn map()

Not documented.

fn record

var fn record(typeName: String): Bool

Not documented.

fn variant

var fn variant(typeName: String): Bool

Not documented.

fn variantCase

var fn variantCase(name: String)

Not documented.

fn field

var fn field(description: FieldDescription)

Not documented.

fn finish

var fn finish()

Not documented.