`std/encoding`

Encoding and decoding: what other languages need reflection for (serialization, config mapping, database rows, schemas, --help texts).

const json = Json()
const text = json.encode user
const back = json.decode<User>(text)?

A value is its constructor call. The compiler knows every type's constructor and offers it in three forms: written (Encode), read (Decode) and described without a value (Describe). A format (Json, a database driver, a command line parser) implements Encoder, Decoder or Describer and never sees a type. There is no tree in between: a value is written while the type describes itself, and nothing is lost on the way.

All three forms are generated for a type whose constructor is usable from outside, over exactly the constructor's parameters: a private field with a default is not one of them, so a cache stays out without an annotation. What the compiler generates is ordinary code over the vocabulary, and could be written by hand:

extend User with Encode {
  fn encode<Target: Encoder>(var target: Target) {
    target.record "app/User"
    target.field "name"
    name.encode target
    target.field "tags"
    tags.encode target
    target.finish()
  }
}

The three traits take their target as a bound, not as a trait type: a format hands its own encoder over as a var path and reads the result out of it afterwards, and the derived code is a direct call chain with no table. EncodedValue is what a program holds where it has left the type behind, and Structure is a type's description as a value. docs/design/ENCODING.md is the design.

Modules

std/encoding/derivedThe steps a generated encode, decode and describe are made of.
std/encoding/libEncoding and decoding: what other languages need reflection for (serialization, config mapping, database rows, schemas, --help texts).
std/encoding/naming[Naming]: how a format spells the field names a type declares.
std/encoding/structureA type's structure as a value: [Structure], the [Structures] describer that builds one, and the [FieldDescription] every field of a description carries.
std/encoding/valuesA value without its type: [EncodedValue], the [Values] encoder that builds one, and the [ValueDecoder] that reads a typed value back out of one.

Everything

extend ArrayList<Item> with DecodeAn ArrayList reads back as the list it is written as - a sequence, item by item - so a field of one does not keep the type around it from having a derived decode (Chunk of the bytecode, whose code is one).
extend ArrayList<Item> with DescribeAn ArrayList describes as the sequence of List.
extend Bool with Encode, Decode, DescribeBool is the vocabulary's own bool, in all three forms.
extend Char with Encode, Decode, DescribeA Char travels as a text of one character: the formats of the language have no character of their own.
extend Decimal with Encode, Decode, DescribeDecimal is the vocabulary's own decimal: an exact number stays exact in a format that can say so.
trait DecodeA value reads itself back.
type DecodeErrorWhat went wrong reading a value, with the whole chain of fields and positions it went wrong in: items[2].price.currency: a value is needed.
fn decodeFieldValueThe value of the field [decodeHasField] positioned on, read with its own decode.
fn decodeFinishCloses the record, the variant or the tuple that was read.
fn decodeHasFieldPositions on a field that has a default, and answers whether the input has it.
fn decodeHasPrivateField[decodeHasField] for a field that is no parameter of the constructor from outside: false, and so its default, unless the source reads every field ([Decoder.readsPrivateFields]) and the input has it.
fn decodeItemOne position of a tuple.
fn decodeLiteralA literal type is read as its base and then checked against the values it allows.
trait DecoderThe reading half of a format.
fn decodeRecordOpens the record the constructor is read from.
fn decodeRequiredA field the input has to have, read with its own decode.
fn decodeSequenceOpens the sequence a tuple is read from.
fn decodeThroughA capsule read through its conversion pair: the source's own decode, then the total way in.
fn decodeThroughCheckedA capsule read through a fallible way in: the check the factory exists to force runs for a value out of a document too, and its failure is the DecodeError.
fn decodeVariantOpens a type with cases and answers the name of the case that is there.
trait DescribeA type describes its structure without a value: what schema-driven formats need (a DDL statement, a .proto file, a JSON Schema, a --help text).
fn describeCaseOne case of the open variant.
fn describeConstantFieldOne field whose default is a constant, written into the description as data.
fn describeDefaultedFieldOne field whose default is not data a description can hold: a call, or a value that is not a constant.
fn describeFieldOne field that has to be there: its name, its doc comment, and its value's own description.
fn describeFinishCloses what the last of the steps above opened.
trait DescriberThe describing half: the same method names as [Encoder], without values.
fn describeRecordOpens the description of a record.
fn describeThroughA type that is described as another one: a capsule as its source, a literal type as its base.
fn describeVariantOpens the description of a type with cases, as [describeRecord] does.
trait EncodeA value writes itself into any format.
type EncodedFieldOne named field of an [EncodedValue.Record] or [EncodedValue.Variant].
type EncodedValueAny Encode value, held without its type.
extend EncodedValue with EncodeAn EncodedValue writes itself into any encoder, which is what makes it useful: a captured value can be bound as a SQL parameter, and a document nobody has a type for can be written out again.
fn encodeFieldOne field of a record or a case: its name, then its value's own encode.
fn encodeFinishCloses what the last of the steps above opened.
fn encodeItemOne position of a tuple: its value's own encode.
fn encodePrivateFieldA field that is no parameter of the constructor from outside - private, with a default - written like any other field, but only for a target that asks for every field ([Encoder.writesPrivateFields]).
trait EncoderThe writing half of a format.
fn encodeRecordOpens the record a value of typeName is written as.
fn encodeSequenceOpens the sequence a tuple is written as.
fn encodeThroughA capsule is written as the source of its conversion pair: Wire.from(value), then that value's own encode.
fn encodeVariantOpens the case name of a type with cases.
type FieldDefaultWhether a field may be missing from the input, and what it is then.
type FieldDescriptionWhat the compiler knows about one constructor parameter, and what a schema or a help text needs of it.
extend Float32 with Encode, DescribeA Float32 travels as a Float64.
extend Float64 with Encode, Decode, DescribeFloat64 is the vocabulary's own float, in all three forms.
trait FormatWhat a whole format is, once: bytes in both directions, and the two Stages that make it work on a stream.
extend Int16 with Encode, Decode, DescribeA narrow integer travels as an Int64 and is checked on the way back: a value that does not fit is an error.
extend Int32 with Encode, Decode, DescribeA narrow integer travels as an Int64 and is checked on the way back: a value that does not fit is an error.
extend Int64 with Encode, Decode, DescribeInt64 is the vocabulary's own int, in all three forms.
extend Int8 with Encode, Decode, DescribeA narrow integer travels as an Int64 and is checked on the way back: a value that does not fit is an error.
extend List<Item> with EncodeA list is a sequence: its length in front, then every item with its own encode.
extend List<Item> with DecodeA sequence, item by item, each through the item's own decode.
extend List<Item> with DescribeA list describes as a sequence around its item's structure: the shape is one item, repeated.
extend Map<Key, Value> with EncodeA map is a map: its length in front, then every entry as its key and its value.
extend Map<Key, Value> with DecodeA map, entry by entry: a key, then its value.
extend Map<Key, Value> with DescribeA map describes as a map around its key's and its value's structure.
type NamingHow a format writes a field name.
extend Option<Value> with EncodeSome is its value, and None is nothing() - which a field may leave out, so its default applies.
extend Option<Value> with DecodeA "nothing" is None, and anything else is the value's own decode.
extend Option<Value> with DescribeAn optional value describes as optional() around the value's own structure.
fn renderedAny Encode value as readable text, for messages and debugging: User(name: "Ada", tags: ["math"]).
extend Set<Item> with EncodeA set is a sequence of its items.
extend Set<Item> with DecodeA sequence read into a set: an item that is there twice is there once.
extend Set<Item> with DescribeA set describes as a sequence of its item.
extend String with Encode, Decode, DescribeString is the vocabulary's own string, in all three forms.
type StructureWhat a [Describe] walk builds when a format wants a value instead of a visitor.
type StructureCaseOne case of a [Structure.Variant]: its name and the structure of its own fields.
type StructureFieldOne field of a [Structure.Record]: its description and the structure of the value it holds.
fn structureOfThe structure of a type, as a value.
type StructuresA Describer that builds a [Structure].
extend UInt16 with Encode, Decode, DescribeA narrow unsigned integer travels as an Int64, which holds every one of its values, and is checked on the way back.
extend UInt32 with Encode, Decode, DescribeA narrow unsigned integer travels as an Int64, which holds every one of its values, and is checked on the way back.
extend UInt64 with Encode, Decode, DescribeUInt64 is the vocabulary's own unsigned: its upper half does not fit into an Int64.
extend UInt8 with Encode, Decode, DescribeA narrow unsigned integer travels as an Int64, which holds every one of its values, and is checked on the way back.
fn unknownCaseWhat a case name the type does not have is: `Lost` is not a case of `Status`.
type ValueDecoderA Decoder over an [EncodedValue].
type ValuesAn Encoder that builds an [EncodedValue].