`std/encoding/derived`

std/encoding/src/derived.trb

The steps a generated encode, decode and describe are made of. The compiler writes a derived implementation as a straight line of calls to these functions, one per field, so what a derived form does is ordinary TorbScript that can be read here - and written by hand the same way.

// What the compiler generates for `type Price { amount: Decimal, currency: String = "EUR" }`, in words:
//   encode:   target.record "app/Price", encodeField(amount, "amount", target), ..., target.finish()
//   decode:   decodeRecord, decodeRequired<Decimal> "amount", decodeHasField "currency" (the default if not),
//             decodeFinish, and the constructor
//   describe: target.record "app/Price", describeField<Decimal> "amount", ..., target.finish()

Every function reads or writes the field chain the design asks for: an error that comes out of a field names it (DecodeError.inside).

fn encodeRecord

fn encodeRecord<Target: Encoder>(typeName: String, var target: Target)

Opens the record a value of typeName is written as.

fn encodeVariant

fn encodeVariant<Target: Encoder>(typeName: String, name: String, var target: Target)

Opens the case name of a type with cases.

fn encodeSequence

fn encodeSequence<Target: Encoder>(length: Int, var target: Target)

Opens the sequence a tuple is written as.

fn encodeFinish

fn encodeFinish<Target: Encoder>(var target: Target)

Closes what the last of the steps above opened.

fn encodeField

fn encodeField<Value: Encode, Target: Encoder>(value: Value, name: String, var target: Target)

One field of a record or a case: its name, then its value's own encode.

fn encodePrivateField

fn encodePrivateField<Value: Encode, Target: Encoder>(value: Value, name: String, var target: Target)

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

fn encodeItem

fn encodeItem<Value: Encode, Target: Encoder>(value: Value, var target: Target)

One position of a tuple: its value's own encode.

fn encodeThrough

fn encodeThrough<Value, Wire: From<Value> & Encode, Target: Encoder>(value: Value, var target: Target)

A capsule is written as the source of its conversion pair: Wire.from(value), then that value's own encode. There is no record around it, so a Path in a document is its text.

fn decodeRecord

fn decodeRecord<Source: Decoder>(typeName: String, var source: Source): Result<Void, DecodeError>

Opens the record the constructor is read from.

fn decodeRequired

fn decodeRequired<Value: Decode, Source: Decoder>(name: String, var source: Source): Result<Value, DecodeError>

A field the input has to have, read with its own decode. The error names the field.

fn decodeHasField

fn decodeHasField<Source: Decoder>(name: String, var source: Source): Result<Bool, DecodeError>

Positions on a field that has a default, and answers whether the input has it. Where it does not, the generated code evaluates the default - and only then, so a value that is there never pays for one.

fn decodeHasPrivateField

fn decodeHasPrivateField<Source: Decoder>(name: String, var source: Source): Result<Bool, DecodeError>

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 decodeFieldValue

fn decodeFieldValue<Value: Decode, Source: Decoder>(name: String, var source: Source): Result<Value, DecodeError>

The value of the field decodeHasField positioned on, read with its own decode. The error names the field.

fn decodeFinish

fn decodeFinish<Source: Decoder>(var source: Source): Result<Void, DecodeError>

Closes the record, the variant or the tuple that was read.

fn decodeVariant

fn decodeVariant<Source: Decoder>(typeName: String, var source: Source): Result<String, DecodeError>

Opens a type with cases and answers the name of the case that is there.

fn unknownCase

fn unknownCase(name: String, typeName: String): DecodeError

What a case name the type does not have is: `Lost` is not a case of `Status`.

fn decodeSequence

fn decodeSequence<Source: Decoder>(var source: Source): Result<Void, DecodeError>

Opens the sequence a tuple is read from.

fn decodeItem

fn decodeItem<Value: Decode, Source: Decoder>(position: Int, var source: Source): Result<Value, DecodeError>

One position of a tuple. The error names the position.

fn decodeThrough

fn decodeThrough<Value: From<Wire>, Wire: Decode, Source: Decoder>(var source: Source): Result<Value, DecodeError>

A capsule read through its conversion pair: the source's own decode, then the total way in.

fn decodeThroughChecked

fn decodeThroughChecked<Value: TryFrom<Wire, Failure>, Wire: Decode, Failure: Show, Source: Decoder>(var source: Source): Result<Value, DecodeError>

A 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 decodeLiteral

fn decodeLiteral<Value: TryFrom<String, LiteralParseError>, Base: Decode & Show, Source: Decoder>(var source: Source): Result<Value, DecodeError>

A literal type is read as its base and then checked against the values it allows.

fn describeRecord

fn describeRecord<Target: Describer>(typeName: String, var target: Target): Bool

Opens the description of a record. false where the target knows the type already and wants no body.

fn describeVariant

fn describeVariant<Target: Describer>(typeName: String, var target: Target): Bool

Opens the description of a type with cases, as describeRecord does.

fn describeCase

fn describeCase<Target: Describer>(name: String, var target: Target)

One case of the open variant. Its fields follow.

fn describeFinish

fn describeFinish<Target: Describer>(var target: Target)

Closes what the last of the steps above opened.

fn describeThrough

fn describeThrough<Wire: Describe, Target: Describer>(var target: Target)

A type that is described as another one: a capsule as its source, a literal type as its base.

fn describeField

fn describeField<Value: Describe, Target: Describer>(name: String, documentation: String, var target: Target)

One field that has to be there: its name, its doc comment, and its value's own description.

fn describeDefaultedField

fn describeDefaultedField<Value: Describe, Target: Describer>(name: String, documentation: String, var target: Target)

One field whose default is not data a description can hold: a call, or a value that is not a constant.

fn describeConstantField

fn describeConstantField<Value: Describe & Encode, Target: Describer>(name: String, documentation: String, default: Value, var target: Target)

One field whose default is a constant, written into the description as data.