`nupp.serde`

A binding selects how a value is read and constructed, separately from the codec that chooses its wire representation. See Serialization bindings for the guide to bindings, codecs, and documents.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record User
    id: integer
    name: string
end
local users = serde.binding(User)
local bytes = json.encode(users, new User(id = 7, name = "Ada"))
assert(bytes == '{"id":7,"name":"Ada"}')
assert(json.decode(users, bytes).name == "Ada")

A Binding is chosen at the call site and passed to a codec, so one record can have several: the binding a save file uses can differ from the one a web service uses. binding builds one from a record or struct declaration with no derive, and Options renames, filters, or reinterprets its fields.

The package splits by audience:

nupp.serde.json, nupp.serde.native, and nupp.serde.debug are the codecs: JSON text, a LuaJIT-local persistence frame, and diagnostic text.
nupp.serde.document holds schema-free values: a document tree, typed views of bound values, and saved nupp.util.Store snapshots.
nupp.serde.adapters builds bindings for a model library that owns its own schema, such as one generated from Smithy or OpenAPI.
nupp.serde.codec holds what a new codec needs beyond the contracts here.

This module holds the contracts all of them share. A model library implements Adapter over its own Member type and wraps it in Bound; a codec implements Writer and Reader. Neither imports the other, and the erased Binding is the only thing a caller passes between them.

Failures are raised as an Error carrying the logical path to the value, the byte offset when a decoder has one, and the original cause.

Submodules

Module	Description
`nupp.serde.adapters`	These builders give a model library that owns its schema adapters over its own nupp.serde.Member type.
`nupp.serde.codec`	A new codec uses these helpers to apply the number, timestamp, error-path, and context rules the built-in codecs share.
`nupp.serde.debug`	Debug rendering turns any bound value into readable text for logs, assertions, and error messages.
`nupp.serde.document`	A document is a value without a schema, which any codec reads and writes.
`nupp.serde.json`	This codec writes and reads JSON text through any nupp.serde.Binding.
`nupp.serde.native`	The native codec saves values as a compact binary frame on a native LuaJIT host.

Module contents

Types

Type	Kind	Description
`Access`	record	A declaration's fields and constructor, as an external model sees them.
`Adapter`	interface	Reads and writes one type of value against a model's members.
`Atom`	interface	A model-defined scalar a codec passes through without interpreting, such as an enum member or an XML qualified name.
`Binding`	interface	Selects how a value of type T is written and constructed.
`Bound`	record	Erases an Adapter's member type into a Binding for a Copyable value.
`Child`	interface	One member of a described structure, union, list, or map.
`Consumer`	interface	Applies an adapter to state, recovering the member type a Binding erased.
`Context`	interface	Typed values a codec attaches to what it reads, such as the schema a document came from.
`Decimal`	record	An exact decimal: coefficient times ten to the exponent.
`Description`	interface	The shape of an adapter's value for one direction, which a codec plans against before it reads or writes anything.
`Direction`	type	Whether a description is for writing or for reading.
`Discard`	interface	Disposes a value a codec has to give up.
`DocumentAdapter`	interface	Reads and writes a document type as its logical contents.
`DocumentElement`	interface	Receives one document list element.
`DocumentEntry`	interface	Receives one document map entry.
`DocumentMember`	interface	Receives one document structure member.
`DocumentReader`	interface	Reads one document value without a schema.
`ElementConsumer`	interface	Receives one list or tuple element while reading.
`EntryConsumer`	interface	Receives one map entry while reading.
`Error`	record	A serialization failure.
`ErrorCode`	type	What kind of failure an Error is: malformed input, an exceeded limit, a value the codec cannot represent, a model's...
`FieldOptions`	record	Mapping for one field of a declaration binding.
`FieldView`	interface	Chooses an adapter in place of the one a declared type implies.
`Float`	record	A floating-point value with the width it was written at.
`Integer`	record	An integer of a declared width, carried as its decimal text so 64-bit values survive targets without an exact carrier.
`IntoConsumer`	interface	A Consumer that also writes into an exclusive output.
`Kind`	type	The broad shape of a value: a scalar kind, or a structure, union, list, tuple, map, or opaque value.
`Member`	interface	A field, list element, or other position in a model's schema.
`MemberConsumer`	interface	Receives one structure or union member while reading.
`Members`	interface	Emits a structure's members, a list's elements, or a map's entries.
`Options`	record	Field mapping for binding.
`OwnedBound`	record	Erases an Adapter for a value that owns resources.
`Presence`	type	Whether a member was absent, explicitly null, or present.
`Reader`	interface	What a codec reads a value from.
`ScalarKind`	type	The scalar kinds a Writer and Reader carry.
`Timestamp`	record	An instant as whole seconds since the Unix epoch, in decimal text, and nanoseconds within that second.
`UnknownConsumer`	interface	Receives a wire field the model does not declare.
`UnknownReader`	interface	Skips or captures an undeclared wire field's value.
`WireField`	interface	A wire field a decoder met that the model does not declare.
`Writer`	interface	What a codec emits a value into.

Functions

Function	Kind	Description
`access`	function	Returns the Access for a declaration, cached on the declaration.
`binding`	function	Builds a binding from a record or struct declaration.

Values

Value	Kind	Description
`iso8601Seconds`	variable	The representation that writes an integer field of epoch seconds as an RFC 3339 timestamp, and reads one back.

Types#

`Access`record#

record Access<T is nupp.Copyable> ...

A declaration's fields and constructor, as an external model sees them.

access returns one for a model library that maps a Nupp record onto its own schema, so it reads fields and constructs values exactly as binding does without depending on that binding.

Type parameters

Name	Description
`T`

Members

Name	Kind	Description
`info`	field	The reflection graph the declaration was read from.
`typeIndex`	field	The position of the declaration in info.types.
`fields`	field	The declaration's stored, readable fields, in declaration order.
`parameters`	field	The constructor's parameters, in call order.
`owner`	field
`target`	field
`defaults`	field
`constructor`	constructor
`constructionProblem`	field
`accessible`	field
`nestedCache`	field
`get`	method	Reads a field of a value, borrowed from it.
`begin`	method	Starts constructing a value.
`constructionError`	method	Returns why the declaration cannot be constructed through this access.
`nested`	method	Returns the access for a record or struct the declaration's storage reaches.
`finish`	method	Constructs the value from a builder and drops the builder.

`info`field#

info: nupp.reflect.Info

@readonly

The reflection graph the declaration was read from.

`typeIndex`field#

typeIndex: integer

@readonly

The position of the declaration in info.types.

`fields`field#

fields: const{Field}

@readonly

The declaration's stored, readable fields, in declaration order.

`parameters`field#

parameters: const{Parameter}

@readonly

The constructor's parameters, in call order.

The list is empty when the declaration owns resources, is generic, or needs a factory; constructionError then says why.

`owner`field#

owner: table

@private@readonly

`target`field#

target: Type<T>

@private@readonly

`defaults`field#

defaults: {[string]: unknown}

@private@readonly

`constructor`constructor#

constructor: integer?

@private@readonly

`constructionProblem`field#

constructionProblem: string?

@private@readonly

`accessible`field#

accessible: {[integer]: boolean}

@private@readonly

`nestedCache`field#

nestedCache: {[integer]: Access<unknown>}

@private@readonly

`get`method#

get: function get(self, borrows value: T, field: const Field): unknown

Reads a field of a value, borrowed from it.

Arguments

Name	Type	Description
`self`	`any`
`borrows value`	`T`	the value to read
`field`	`const Field`	one of this access's fields

Returns

Type	Description
`unknown`	the field's value

Raises

Type	Condition
`string`	when the field belongs to another access

`begin`method#

begin: function begin(self): Builder<T>

Starts constructing a value.

The builder is an owner: pass it to finish, or drop it to discard the arguments.

Arguments

Name	Type	Description
`self`	`any`

Returns

Type	Description
`Builder<T>`	the builder

Raises

Type	Condition
`string`	when the declaration cannot be constructed; the message is the one `constructionError` returns

`constructionError`method#

constructionError: function constructionError(self): string?

Returns why the declaration cannot be constructed through this access.

The reported problems are an owning or generic declaration, a constructor that needs a factory, a parameter that is not plain or whose type cannot be checked at runtime, and metadata built by a compiler that predates ownership attestation. Each needs a construction adapter of its own, except the last, which needs a rebuild.

Arguments

Name	Type	Description
`self`	`any`

Returns

Type	Description
`string?`	the problem, or nil when `begin` succeeds

`nested`method#

nested: function nested(self, index: integer): Access<unknown>

Returns the access for a record or struct the declaration's storage reaches.

The access is cached, so asking twice for an index returns the same one.

Arguments

Name	Type	Description
`self`	`any`
`index`	`integer`	the nested declaration's position in `info.types`

Returns

Type	Description
`Access<unknown>`	the nested declaration's access

Raises

Type	Condition
`string`	when the type is not reachable through readable storage, is not a record or struct, or has no runtime declaration

`finish`method#

finish: function finish(self, takes builder: Builder<T>): T

Constructs the value from a builder and drops the builder.

An unset optional parameter takes a copy of the field's default, if any, when the declaration has no constructor of its own, and nil when it does. The constructed value is checked against the declaration before it is returned.

Arguments

Name	Type	Description
`self`	`any`
`takes builder`	`Builder<T>`	the builder from `begin`, transferred

Returns

Type	Description
`T`	the value

Raises

Type	Condition
`string`	when the builder is closed or belongs to another access, a required parameter is unset, or an argument or the result does not fit its declared type

`Adapter`interface#

interface Adapter<T, M is Member> ...

Reads and writes one type of value against a model's members.

describe returns the shape a codec plans against, write emits a value through a Writer, and read constructs one from a Reader. The builders in nupp.serde.adapters cover scalars, structures, and lists.

Type parameters

Name	Description
`T`
`M`

Members

Name	Kind	Description
`describe`	method	Describes the value's shape for a direction.
`write`	method	Writes value to writer as exactly one value.
`read`	method	Constructs a value by consuming exactly one value from reader.

`describe`method#

describe: function(self, direction: Direction): Description<M>

Describes the value's shape for a direction.

Arguments

Name	Type	Description
`?`	`self`
`direction`	`Direction`

Returns

Type	Description
`Description<M>`

`write`method#

write: function(self, borrows value: T, exclusive writer: Writer<M>): nil

Writes value to writer as exactly one value.

Arguments

Name	Type	Description
`?`	`self`
`borrows value`	`T`
`exclusive writer`	`Writer<M>`

Returns

Type	Description
`nil`

`read`method#

read: function(self, exclusive reader: Reader<M>): T

Constructs a value by consuming exactly one value from reader.

Arguments

Name	Type	Description
`?`	`self`
`exclusive reader`	`Reader<M>`

Returns

Type	Description
`T`

`Atom`interface#

interface Atom ...

A model-defined scalar a codec passes through without interpreting, such as an enum member or an XML qualified name.

Members

Name	Kind	Description
`family`	field	A table identifying the model that defined the atom, which a codec compares to recognize atoms it can render.
`snapshot`	method	Copies the atom into a value a document can keep after the original is gone.

`family`field#

family: table

@readonly

A table identifying the model that defined the atom, which a codec compares to recognize atoms it can render.

`snapshot`method#

snapshot: function(borrows self: Atom): Atom

Copies the atom into a value a document can keep after the original is gone.

Arguments

Name	Type	Description
`borrows self`	`Atom`

Returns

Type	Description
`Atom`

`Binding`interface#

interface Binding<T> is Discard<T> ...

Selects how a value of type T is written and constructed.

A binding is opaque: it hides the model's Member type and is invariant in T, so a binding for one record cannot be passed where another is expected. Make one with binding, or with Bound or OwnedBound over an Adapter.

Type parameters

Name	Description
`T`

Members

Name	Kind	Description
`accept`	method	Passes the erased adapter and state to consumer, recovering the member type.
`acceptInto`	method	Passes the erased adapter, state, and output to consumer, recovering the member type.

`accept`method#

accept: function<S, R>(self, consumer: Consumer<T, S, R>, borrows state: S): R

Passes the erased adapter and state to consumer, recovering the member type.

Arguments

Name	Type	Description
`?`	`self`
`consumer`	`Consumer<T, S, R>`
`borrows state`	`S`

Returns

Type	Description
`R`

`acceptInto`method#

acceptInto: function<S, O, R>(self, consumer: IntoConsumer<T, S, O, R>, borrows state: S, exclusive output: O): R

Passes the erased adapter, state, and output to consumer, recovering the member type.

Arguments

Name	Type	Description
`?`	`self`
`consumer`	`IntoConsumer<T, S, O, R>`
`borrows state`	`S`
`exclusive output`	`O`

Returns

Type	Description
`R`

`Bound`record#

record Bound<T is nupp.Copyable, M is Member> is Binding<T> ...

Erases an Adapter's member type into a Binding for a Copyable value.

A codec still has to be told how the model's members are named: see nupp.serde.json.memberNamePolicy.

local serde = require("nupp.serde")
local adapters = require("nupp.serde.adapters")
local json = require("nupp.serde.json")
local record Member is serde.Member
    @readonly name: string
    @readonly index: integer?
end
local title: serde.Binding<string> = new serde.Bound<string, Member>(
    adapter = adapters.text(new Member(name = "title"))
)
assert(json.codec(json.memberNamePolicy):encode(title, "Dune") == '"Dune"')

Type parameters

Name	Description
`T`
`M`

Members

Name	Kind	Description
`adapter`	field	The adapter the binding erases.
`discard`	method	Discards a value.
`accept`	method	Passes adapter and state to consumer.
`acceptInto`	method	Passes adapter, state, and output to consumer.

`adapter`field#

adapter: Adapter<T, M>

@readonly

The adapter the binding erases.

`discard`method#

discard: function discard(self, takes value: T): nil

Discards a value. A Copyable value carries no cleanup obligation, so only its transfer ends here.

Arguments

Name	Type	Description
`self`	`any`
`takes value`	`T`

Returns

Type	Description
`nil`

`accept`method#

accept: function accept<S, R>(self, consumer: Consumer<T, S, R>, borrows state: S): R

Passes adapter and state to consumer.

Arguments

Name	Type	Description
`self`	`any`
`consumer`	`Consumer<T, S, R>`
`borrows state`	`S`

Returns

Type	Description
`R`

`acceptInto`method#

acceptInto: function acceptInto<S, O, R>(self, consumer: IntoConsumer<T, S, O, R>, borrows state: S, exclusive output: O): R

Passes adapter, state, and output to consumer.

Arguments

Name	Type	Description
`self`	`any`
`consumer`	`IntoConsumer<T, S, O, R>`
`borrows state`	`S`
`exclusive output`	`O`

Returns

Type	Description
`R`

`Child`interface#

interface Child<M is Member> ...

One member of a described structure, union, list, or map.

Type parameters

Name	Description
`M`

Members

Name	Kind	Description
`member`	field	The member the child's value sits at.
`required`	field	Whether reading needs the member present.
`hasDefault`	field	Whether construction supplies a value when the member is absent.
`describe`	method	Describes the child's value for a direction.

`member`field#

member: M

@readonly

The member the child's value sits at.

`required`field#

required: boolean

@readonly

Whether reading needs the member present.

`hasDefault`field#

hasDefault: boolean

@readonly

Whether construction supplies a value when the member is absent.

`describe`method#

describe: function(self, direction: Direction): Description<M>

Describes the child's value for a direction.

Arguments

Name	Type	Description
`?`	`self`
`direction`	`Direction`

Returns

Type	Description
`Description<M>`

`Consumer`interface#

interface Consumer<T, S, R> ...

Applies an adapter to state, recovering the member type a Binding erased. A codec passes one to Binding:accept.

Type parameters

Name	Description
`T`
`S`
`R`

Members

Name	Kind	Description
`apply`	method	Applies the adapter a binding erased to borrowed state.

`apply`method#

apply: function<M is Member>(self, adapter: Adapter<T, M>, borrows state: S): R

Applies the adapter a binding erased to borrowed state.

Arguments

Name	Type	Description
`?`	`self`
`adapter`	`Adapter<T, M>`
`borrows state`	`S`

Returns

Type	Description
`R`

`Context`interface#

interface Context ...

Typed values a codec attaches to what it reads, such as the schema a document came from. Keys are nupp.util.Keys; a context returns its own value for a key, then its parent's.

Members

Name	Kind	Description
`codec`	field	The identity of the codec that read the value.
`profile`	field	The codec configuration the value was read under.
`parent`	field	The context this one extends, or nil.
`get`	method	Returns the value held under a key, falling back to the parent's.

`codec`field#

codec: table

@readonly

The identity of the codec that read the value.

`profile`field#

profile: table

@readonly

The codec configuration the value was read under. A JSON writer replays a captured value only under the same profile.

`parent`field#

parent: Context?

@readonly

The context this one extends, or nil.

`get`method#

get: function<V is nupp.Copyable>(self, key: store.Key<V>): V?

Returns the value held under a key, falling back to the parent's.

Arguments

Name	Type	Description
`?`	`self`
`key`	`store.Key<V>`

Returns

Type	Description
`V?`

`Decimal`record#

record Decimal ...

An exact decimal: coefficient times ten to the exponent.

Members

Name	Kind	Description
`coefficient`	field	The digits as decimal integer text, with a leading - when negative.
`exponent`	field	The power of ten the coefficient is scaled by.

`coefficient`field#

coefficient: string

@readonly

The digits as decimal integer text, with a leading - when negative.

`exponent`field#

exponent: integer

@readonly

The power of ten the coefficient is scaled by.

`Description`interface#

interface Description<M is Member> ...

The shape of an adapter's value for one direction, which a codec plans against before it reads or writes anything.

Type parameters

Name	Description
`M`

Members

Name	Kind	Description
`kind`	field	The value's broad shape.
`member`	field	The member the value sits at.
`nullable`	field	Whether the value may be an explicit null.
`width`	field	The width in bits of an integer or float, or nil for other kinds.
`signed`	field	Whether an integer is signed, or nil for other kinds.
`canRead`	field	Whether the adapter can construct a value when reading.
`children`	field	The members of a structure or union, a list's one element, a tuple's slots in order, or a map's key and then its value.

`kind`field#

kind: Kind

@readonly

The value's broad shape.

`member`field#

member: M

@readonly

The member the value sits at.

`nullable`field#

nullable: boolean

@readonly

Whether the value may be an explicit null.

`width`field#

width: integer?

@readonly

The width in bits of an integer or float, or nil for other kinds.

`signed`field#

signed: boolean?

@readonly

Whether an integer is signed, or nil for other kinds.

`canRead`field#

canRead: boolean

@readonly

Whether the adapter can construct a value when reading. A codec refuses to plan a read of a value that cannot be constructed.

`children`field#

children: const{Child<M>}

@readonly

The members of a structure or union, a list's one element, a tuple's slots in order, or a map's key and then its value.

`Direction`type#

type Direction = "write" | "read"

Whether a description is for writing or for reading.

`Discard`interface#

interface Discard<T> ...

Disposes a value a codec has to give up.

Type parameters

Name	Description
`T`

Members

Name	Kind	Description
`discard`	method	Drops a value the codec cannot hand back, such as one an adapter built before a later check on the input failed.

`discard`method#

discard: function(self, takes value: T): nil

Drops a value the codec cannot hand back, such as one an adapter built before a later check on the input failed.

Arguments

Name	Type	Description
`?`	`self`
`takes value`	`T`

Returns

Type	Description
`nil`

`DocumentAdapter`interface#

interface DocumentAdapter<D> is Discard<D> ...

Reads and writes a document type as its logical contents. See nupp.serde.document.

Type parameters

Name	Description
`D`

Members

Name	Kind	Description
`context`	method	Returns the context a document carries, or nil when it has none.
`contents`	method	Returns the binding that writes a document's contents as an ordinary value.
`readContents`	method	Constructs a document by reading its contents from reader.

`context`method#

context: function(self, borrows document: D): Context?

Returns the context a document carries, or nil when it has none.

Arguments

Name	Type	Description
`?`	`self`
`borrows document`	`D`

Returns

Type	Description
`Context?`

`contents`method#

contents: function(self): Binding<D>

Returns the binding that writes a document's contents as an ordinary value.

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`Binding<D>`

`readContents`method#

readContents: function(self, exclusive reader: DocumentReader): D

Constructs a document by reading its contents from reader.

Arguments

Name	Type	Description
`?`	`self`
`exclusive reader`	`DocumentReader`

Returns

Type	Description
`D`

`DocumentElement`interface#

interface DocumentElement<S> ...

Receives one document list element.

Type parameters

Name	Description
`S`

Members

Name	Kind	Description
`apply`	method	Reads the element at a 1-based index into state, consuming value.

`apply`method#

apply: function(self, exclusive state: S, index: integer, exclusive value: DocumentReader): nil

Reads the element at a 1-based index into state, consuming value.

Arguments

Name	Type	Description
`?`	`self`
`exclusive state`	`S`
`index`	`integer`
`exclusive value`	`DocumentReader`

Returns

Type	Description
`nil`

`DocumentEntry`interface#

interface DocumentEntry<S> ...

Receives one document map entry.

Type parameters

Name	Description
`S`

Members

Name	Kind	Description
`apply`	method	Reads one entry into state, consuming both key and value.

`apply`method#

apply: function(self, exclusive state: S, exclusive key: DocumentReader, exclusive value: DocumentReader): nil

Reads one entry into state, consuming both key and value.

Arguments

Name	Type	Description
`?`	`self`
`exclusive state`	`S`
`exclusive key`	`DocumentReader`
`exclusive value`	`DocumentReader`

Returns

Type	Description
`nil`

`DocumentMember`interface#

interface DocumentMember<S> ...

Receives one document structure member.

Type parameters

Name	Description
`S`

Members

Name	Kind	Description
`apply`	method	Reads the member called name into state, consuming value.

`apply`method#

apply: function(self, exclusive state: S, name: string, exclusive value: DocumentReader): nil

Reads the member called name into state, consuming value.

Arguments

Name	Type	Description
`?`	`self`
`exclusive state`	`S`
`name`	`string`
`exclusive value`	`DocumentReader`

Returns

Type	Description
`nil`

`DocumentReader`interface#

interface DocumentReader ...

Reads one document value without a schema. See nupp.serde.document.

Members

Name	Kind	Description
`context`	method	Returns the context the value came with, or nil.
`kind`	method	Returns the kind of the value without consuming it.
`readNull`	method	Reads an explicit null.
`readBoolean`	method	Reads a boolean.
`readNumberToken`	method	Reads a number as its unparsed text.
`readString`	method	Reads a string.
`readBytes`	method	Reads a byte string.
`readTimestamp`	method	Reads a timestamp.
`readInteger`	method	Reads an integer with the width it was written at.
`readDecimal`	method	Reads an exact decimal.
`readFloat`	method	Reads a floating-point value with the width it was written at.
`readBigInteger`	method	Reads an integer of any size as decimal text.
`readAtom`	method	Reads a model-defined atom.
`readDocument`	method	Reads a nested document through adapter.
`readList`	method	Reads a list, passing each element to consume in order.
`readTuple`	method	Reads a tuple, passing each slot to consume in order.
`readStruct`	method	Reads a structure, passing each member to consume with its name.
`readUnion`	method	Reads a union, passing its one alternative to consume with its name.
`readMap`	method	Reads a map, passing each entry's key and value to consume.

`context`method#

context: function(self): Context?

Returns the context the value came with, or nil.

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`Context?`

`kind`method#

kind: function(self): Kind

Returns the kind of the value without consuming it.

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`Kind`

`readNull`method#

readNull: function(exclusive self: DocumentReader): nil

Reads an explicit null.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`nil`

`readBoolean`method#

readBoolean: function(exclusive self: DocumentReader): boolean

Reads a boolean.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`boolean`

`readNumberToken`method#

readNumberToken: function(exclusive self: DocumentReader): string

Reads a number as its unparsed text.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`string`

`readString`method#

readString: function(exclusive self: DocumentReader): string

Reads a string.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`string`

`readBytes`method#

readBytes: function(exclusive self: DocumentReader): string

Reads a byte string.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`string`

`readTimestamp`method#

readTimestamp: function(exclusive self: DocumentReader): Timestamp

Reads a timestamp.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`Timestamp`

`readInteger`method#

readInteger: function(exclusive self: DocumentReader): Integer

Reads an integer with the width it was written at.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`Integer`

`readDecimal`method#

readDecimal: function(exclusive self: DocumentReader): Decimal

Reads an exact decimal.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`Decimal`

`readFloat`method#

readFloat: function(exclusive self: DocumentReader): Float

Reads a floating-point value with the width it was written at.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`Float`

`readBigInteger`method#

readBigInteger: function(exclusive self: DocumentReader): string

Reads an integer of any size as decimal text.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`string`

`readAtom`method#

readAtom: function(exclusive self: DocumentReader): Atom

Reads a model-defined atom.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`

Returns

Type	Description
`Atom`

`readDocument`method#

readDocument: function<D>(exclusive self: DocumentReader, adapter: DocumentAdapter<D>): D

Reads a nested document through adapter.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`
`adapter`	`DocumentAdapter<D>`

Returns

Type	Description
`D`

`readList`method#

readList: function<S>(exclusive self: DocumentReader, exclusive state: S, consume: DocumentElement<S>): nil

Reads a list, passing each element to consume in order.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`
`exclusive state`	`S`
`consume`	`DocumentElement<S>`

Returns

Type	Description
`nil`

`readTuple`method#

readTuple: function<S>(exclusive self: DocumentReader, exclusive state: S, consume: DocumentElement<S>): nil

Reads a tuple, passing each slot to consume in order.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`
`exclusive state`	`S`
`consume`	`DocumentElement<S>`

Returns

Type	Description
`nil`

`readStruct`method#

readStruct: function<S>(exclusive self: DocumentReader, exclusive state: S, consume: DocumentMember<S>): nil

Reads a structure, passing each member to consume with its name.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`
`exclusive state`	`S`
`consume`	`DocumentMember<S>`

Returns

Type	Description
`nil`

`readUnion`method#

readUnion: function<S>(exclusive self: DocumentReader, exclusive state: S, consume: DocumentMember<S>): nil

Reads a union, passing its one alternative to consume with its name.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`
`exclusive state`	`S`
`consume`	`DocumentMember<S>`

Returns

Type	Description
`nil`

`readMap`method#

readMap: function<S>(exclusive self: DocumentReader, exclusive state: S, consume: DocumentEntry<S>): nil

Reads a map, passing each entry's key and value to consume.

Arguments

Name	Type	Description
`exclusive self`	`DocumentReader`
`exclusive state`	`S`
`consume`	`DocumentEntry<S>`

Returns

Type	Description
`nil`

`ElementConsumer`interface#

interface ElementConsumer<M is Member, S> ...

Receives one list or tuple element while reading.

Type parameters

Name	Description
`M`
`S`

Members

Name	Kind	Description
`apply`	method	Reads the element at a 1-based index into state, consuming exactly one value from reader.

`apply`method#

apply: function(self, exclusive state: S, index: integer, exclusive reader: Reader<M>): nil

Reads the element at a 1-based index into state, consuming exactly one value from reader.

Arguments

Name	Type	Description
`?`	`self`
`exclusive state`	`S`
`index`	`integer`
`exclusive reader`	`Reader<M>`

Returns

Type	Description
`nil`

`EntryConsumer`interface#

interface EntryConsumer<M is Member, S> ...

Receives one map entry while reading.

Type parameters

Name	Description
`M`
`S`

Members

Name	Kind	Description
`apply`	method	Reads one entry into state, consuming one value from each of key and value.

`apply`method#

apply: function(self, exclusive state: S, exclusive key: Reader<M>, exclusive value: Reader<M>): nil

Reads one entry into state, consuming one value from each of key and value.

Arguments

Name	Type	Description
`?`	`self`
`exclusive state`	`S`
`exclusive key`	`Reader<M>`
`exclusive value`	`Reader<M>`

Returns

Type	Description
`nil`

`Error`record#

record Error ...

A serialization failure.

path is the logical path to the value, such as $["users"][2]["name"]; byte is the input offset when a decoder knows it. cause is the original problem, and suppressed collects failures raised while cleaning up after it.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record User
    id: integer
end
local ok, problem = pcall(json.decode, serde.binding(User), '{"id":"seven"}')
assert(not ok)
local failure = problem as serde.Error
assert(failure.path == '$["id"]')

Members

Name	Kind	Description
`code`	field	The kind of failure.
`message`	field	A description of the failure.
`path`	field	The logical path to the value, such as $["users"][2]["name"].
`byte`	field	The input byte offset, when a decoder knows it.
`cause`	field	The original problem, such as the value an adapter raised.
`suppressed`	field	Failures raised while handling this one, such as a discard that failed after it.
`__tostring`	metamethod	Renders the code, the path, the byte offset when known, and the message, as in model $["id"] at byte 7: expected an...

`code`field#

code: Code

@readonly

The kind of failure.

`message`field#

message: string

@readonly

A description of the failure.

`path`field#

path: string

@readonly

The logical path to the value, such as $["users"][2]["name"].

`byte`field#

byte: integer?

@readonly

The input byte offset, when a decoder knows it.

`cause`field#

cause: unknown

@readonly

The original problem, such as the value an adapter raised.

`suppressed`field#

suppressed: const{unknown}

@readonly

Failures raised while handling this one, such as a discard that failed after it.

`__tostring`metamethod#

__tostring: function(self): string

Renders the code, the path, the byte offset when known, and the message, as in model $["id"] at byte 7: expected an integer.

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`string`

`ErrorCode`type#

type ErrorCode = "syntax" | "limit" | "unsupported" | "model" | "contract"

What kind of failure an Error is: malformed input, an exceeded limit, a value the codec cannot represent, a model's own failure, or a broken adapter contract.

`FieldOptions`record#

record FieldOptions ...

Mapping for one field of a declaration binding.

name replaces the wire name, overriding Options's naming. omitEmpty leaves an empty field out instead of writing it: nil, false, "", or an empty table. representation reinterprets the field's carrier; iso8601Seconds is the one supplied.

Members

Name	Kind	Description
`omitEmpty`	field	Whether encoding leaves the field out when it is empty.
`representation`	field	Reinterprets the field's carrier, or nil to keep it.
`name`	field	The field's wire name, overriding the options' naming, or nil to derive it.

`omitEmpty`field#

omitEmpty: boolean

@readonly

Whether encoding leaves the field out when it is empty.

Empty is nil, false, the empty string, or a table with no entries. Decoding is unchanged.

`representation`field#

representation: "iso8601Seconds"?

@readonly

Reinterprets the field's carrier, or nil to keep it.

"iso8601Seconds" writes epoch seconds as an RFC 3339 string and reads one back. The binding raises when the field's carrier is not integer or a sized integer narrower than 64 bits.

`name`field#

name: string?

@readonly

The field's wire name, overriding the options' naming, or nil to derive it.

`FieldView`interface#

interface FieldView ...

Chooses an adapter in place of the one a declared type implies.

Set as Options's view. resolve is asked once for every type at every member the binding reaches: the root, each field, list and tuple elements, map keys and values, and both an optional type and the type inside it. It returns nil to keep the default, and an adapter it returns takes precedence over a field's representation.

Members

Name	Kind	Description
`resolve`	method	Returns the adapter for a type where it sits, or nil to keep the default.

`resolve`method#

resolve: function<M is core.Member>(
    self,
    info: nupp.reflect.Info,
    index: integer,
    member: M
): core.Adapter<unknown, M>?

Returns the adapter for a type where it sits, or nil to keep the default.

The binding asks once for each type at each member it reaches, from the root declaration down through fields, list and tuple elements, and map keys and values. An optional or const type is asked about before the type it wraps. A returned adapter replaces the default adapter outright, a field's representation included.

Arguments

Name	Type	Description
`?`	`self`
`info`	`nupp.reflect.Info`	the reflection graph of the declaration being bound
`index`	`integer`	the type's position in `info.types`
`member`	`M`	the member the type sits at

Returns

Type	Description
`core.Adapter<unknown, M>?`	the adapter, or nil for the default

`Float`record#

record Float ...

A floating-point value with the width it was written at.

Members

Name	Kind	Description
`value`	field	The value as a Lua number.
`width`	field	The width in bits the value was written at.

`value`field#

value: number

@readonly

The value as a Lua number.

`width`field#

width: 32 | 64

@readonly

The width in bits the value was written at.

`Integer`record#

record Integer ...

An integer of a declared width, carried as its decimal text so 64-bit values survive targets without an exact carrier.

Members

Name	Kind	Description
`decimal`	field	The value as decimal text, with a leading - when negative.
`width`	field	The width in bits the value must fit.
`signed`	field	Whether the value is signed; an unsigned value is never negative.

`decimal`field#

decimal: string

@readonly

The value as decimal text, with a leading - when negative.

`width`field#

width: 8 | 16 | 32 | 64

@readonly

The width in bits the value must fit.

`signed`field#

signed: boolean

@readonly

Whether the value is signed; an unsigned value is never negative.

`IntoConsumer`interface#

interface IntoConsumer<T, S, O, R> ...

A Consumer that also writes into an exclusive output.

Type parameters

Name	Description
`T`
`S`
`O`
`R`

Members

Name	Kind	Description
`apply`	method	Applies the adapter a binding erased to borrowed state, writing into output.

`apply`method#

apply: function<M is Member>(self, adapter: Adapter<T, M>, borrows state: S, exclusive output: O): R

Applies the adapter a binding erased to borrowed state, writing into output.

Arguments

Name	Type	Description
`?`	`self`
`adapter`	`Adapter<T, M>`
`borrows state`	`S`
`exclusive output`	`O`

Returns

Type	Description
`R`

`Kind`type#

type Kind = ScalarKind | "dynamic" | "opaque" | "structure" | "union" | "list" | "tuple" | "map"

The broad shape of a value: a scalar kind, or a structure, union, list, tuple, map, or opaque value.

`Member`interface#

interface Member ...

A field, list element, or other position in a model's schema.

A model library implements this with whatever its schema needs, such as a shape identifier or numbered binary field, and its codec policy interprets it. Codecs see only name and, for positional formats, index.

Members

Name	Kind	Description
`name`	field	The member's logical name, which a codec's policy maps to a wire name.
`index`	field	The member's position, for a format that numbers its fields, or nil.

`name`field#

name: string

@readonly

The member's logical name, which a codec's policy maps to a wire name.

`index`field#

index: integer?

@readonly

The member's position, for a format that numbers its fields, or nil.

`MemberConsumer`interface#

interface MemberConsumer<M is Member, S> ...

Receives one structure or union member while reading.

Type parameters

Name	Description
`M`
`S`

Members

Name	Kind	Description
`apply`	method	Reads a declared member's value into state, consuming exactly one value from reader.

`apply`method#

apply: function(self, exclusive state: S, member: M, exclusive reader: Reader<M>): nil

Reads a declared member's value into state, consuming exactly one value from reader.

Arguments

Name	Type	Description
`?`	`self`
`exclusive state`	`S`
`member`	`M`
`exclusive reader`	`Reader<M>`

Returns

Type	Description
`nil`

`Members`interface#

interface Members<M is Member, S> ...

Emits a structure's members, a list's elements, or a map's entries.

Type parameters

Name	Description
`M`
`S`

Members

Name	Kind	Description
`apply`	method	Writes the members, elements, or entries of source to writer.

`apply`method#

apply: function(self, borrows source: S, exclusive writer: Writer<M>): nil

Writes the members, elements, or entries of source to writer.

Arguments

Name	Type	Description
`?`	`self`
`borrows source`	`S`
`exclusive writer`	`Writer<M>`

Returns

Type	Description
`nil`

`Options`record#

record Options ...

Field mapping for binding.

naming and unknownMembers apply to every record the binding reaches. fields maps the root declaration's fields one by one, and when it is present it is a whitelist, so a field it does not mention is neither written nor read.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record Account
    displayName: string
    passwordHash: string?
end
local public = serde.binding(Account, new serde.Options(
    naming = "snakeCase",
    fields = {displayName = new serde.FieldOptions()},
    unknownMembers = "ignore"
))
assert(json.encode(public, new Account(displayName = "Ada", passwordHash = "x")) == '{"display_name":"Ada"}')
assert(json.decode(public, '{"display_name":"Ada","admin":true}').passwordHash == nil)

A field left out of the whitelist must have a default for decoding to be selected; an encode-only binding can leave out required fields.

Members

Name	Kind	Description
`fields`	field	Options for the root declaration's fields, keyed by declared name.
`naming`	field	How declared field names become wire names, for every record and shape the binding reaches.
`unknownMembers`	field	What decoding does with a wire member no field declares, for every record and shape the binding reaches.
`view`	field	Chooses adapters in place of the defaults, or nil to keep every default.

`fields`field#

fields: const{[string]: FieldOptions}?

@readonly

Options for the root declaration's fields, keyed by declared name.

When present it is a whitelist: a field it does not name is neither written nor read. It reaches the root declaration only, so a nested record keeps every field. The binding copies it, and raises when it names a field the declaration does not have.

`naming`field#

naming: "identity" | "snakeCase" | "camelCase"

@readonly

How declared field names become wire names, for every record and shape the binding reaches.

"identity" keeps the name, "snakeCase" turns displayName into display_name, and "camelCase" turns display_name into displayName.

`unknownMembers`field#

unknownMembers: "reject" | "ignore"

@readonly

What decoding does with a wire member no field declares, for every record and shape the binding reaches.

"reject" raises at the member and "ignore" skips its value.

`view`field#

view: View?

@readonly

Chooses adapters in place of the defaults, or nil to keep every default.

`OwnedBound`record#

record OwnedBound<T, M is Member> is Binding<T> ...

Erases an Adapter for a value that owns resources.

drop takes a decoded value the codec has to discard, such as one whose adapter returned without consuming its input, and drops it, so a failed decode does not leak what it built.

Type parameters

Name	Description
`T`
`M`

Members

Name	Kind	Description
`adapter`	field	The adapter the binding erases.
`drop`	method	Drops a value the codec has to discard.
`discard`	method	Discards a value by passing it to drop.
`accept`	method	Passes adapter and state to consumer.
`acceptInto`	method	Passes adapter, state, and output to consumer.

`adapter`field#

adapter: Adapter<T, M>

@readonly

The adapter the binding erases.

`drop`method#

drop: function(takes value: T): nil

@readonly

Drops a value the codec has to discard.

Arguments

Name	Type	Description
`takes value`	`T`

Returns

Type	Description
`nil`

`discard`method#

discard: function discard(self, takes value: T): nil

Discards a value by passing it to drop.

Arguments

Name	Type	Description
`self`	`any`
`takes value`	`T`

Returns

Type	Description
`nil`

`accept`method#

accept: function accept<S, R>(self, consumer: Consumer<T, S, R>, borrows state: S): R

Passes adapter and state to consumer.

Arguments

Name	Type	Description
`self`	`any`
`consumer`	`Consumer<T, S, R>`
`borrows state`	`S`

Returns

Type	Description
`R`

`acceptInto`method#

acceptInto: function acceptInto<S, O, R>(self, consumer: IntoConsumer<T, S, O, R>, borrows state: S, exclusive output: O): R

Passes adapter, state, and output to consumer.

Arguments

Name	Type	Description
`self`	`any`
`consumer`	`IntoConsumer<T, S, O, R>`
`borrows state`	`S`
`exclusive output`	`O`

Returns

Type	Description
`R`

`Presence`type#

type Presence = "absent" | "null" | "value"

Whether a member was absent, explicitly null, or present.

`Reader`interface#

interface Reader<M is Member> ...

What a codec reads a value from. Adapters call it; codecs implement it.

Type parameters

Name	Description
`M`

Members

Name	Kind	Description
`context`	method	Returns the context the codec attached to this read, or nil.
`isNull`	method	Returns whether the next value is an explicit null, without consuming it.
`readNull`	method	Reads an explicit null at a member, raising when the member's description does not admit null.
`readBoolean`	method	Reads a boolean at a member.
`readInteger`	method	Reads an integer at a member, raising when it does not fit width and signed.
`readFloat`	method	Reads a floating-point value at a member, narrowed to width bits.
`readBigInteger`	method	Reads an integer of any size at a member, as decimal text.
`readDecimal`	method	Reads an exact decimal at a member.
`readNumberToken`	method	Reads a number at a member as its unparsed text.
`readString`	method	Reads a string at a member.
`readBytes`	method	Reads a byte string at a member.
`readTimestamp`	method	Reads a timestamp at a member.
`readAtom`	method	Reads a model-defined atom at a member.
`readDocument`	method	Reads a document at a member, through adapter.
`readStruct`	method	Reads a structure at a member.
`readUnion`	method	Reads a union at a member, raising unless it holds exactly one alternative.
`readList`	method	Reads a list at a member, passing each element to consume in order.
`readTuple`	method	Reads a tuple of size slots at a member, passing each to consume in order.
`readMap`	method	Reads a map at a member, passing each entry's key and value to consume.
`containerSize`	method	Returns the member, element, or entry count of the next value when the format knows it before reading, or nil.

`context`method#

context: function(self): Context?

Returns the context the codec attached to this read, or nil.

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`Context?`

`isNull`method#

isNull: function(self): boolean

Returns whether the next value is an explicit null, without consuming it.

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`boolean`

`readNull`method#

readNull: function(exclusive self: Reader<M>, member: M): nil

Reads an explicit null at a member, raising when the member's description does not admit null.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`nil`

`readBoolean`method#

readBoolean: function(exclusive self: Reader<M>, member: M): boolean

Reads a boolean at a member.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`boolean`

`readInteger`method#

readInteger: function(exclusive self: Reader<M>, member: M, width: 8 | 16 | 32 | 64, signed: boolean): Integer

Reads an integer at a member, raising when it does not fit width and signed.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`
`width`	`8 \| 16 \| 32 \| 64`
`signed`	`boolean`

Returns

Type	Description
`Integer`

`readFloat`method#

readFloat: function(exclusive self: Reader<M>, member: M, width: 32 | 64): number

Reads a floating-point value at a member, narrowed to width bits.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`
`width`	`32 \| 64`

Returns

Type	Description
`number`

`readBigInteger`method#

readBigInteger: function(exclusive self: Reader<M>, member: M): string

Reads an integer of any size at a member, as decimal text.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`string`

`readDecimal`method#

readDecimal: function(exclusive self: Reader<M>, member: M): Decimal

Reads an exact decimal at a member.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`Decimal`

`readNumberToken`method#

readNumberToken: function(exclusive self: Reader<M>, member: M): string

Reads a number at a member as its unparsed text.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`string`

`readString`method#

readString: function(exclusive self: Reader<M>, member: M): string

Reads a string at a member.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`string`

`readBytes`method#

readBytes: function(exclusive self: Reader<M>, member: M): string

Reads a byte string at a member.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`string`

`readTimestamp`method#

readTimestamp: function(exclusive self: Reader<M>, member: M): Timestamp

Reads a timestamp at a member.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`Timestamp`

`readAtom`method#

readAtom: function(exclusive self: Reader<M>, member: M): Atom

Reads a model-defined atom at a member. A codec that cannot represent atoms raises.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`

Returns

Type	Description
`Atom`

`readDocument`method#

readDocument: function<D>(exclusive self: Reader<M>, member: M, adapter: DocumentAdapter<D>): D

Reads a document at a member, through adapter.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`
`adapter`	`DocumentAdapter<D>`

Returns

Type	Description
`D`

`readStruct`method#

readStruct: function<S>(
    exclusive self: Reader<M>,
    member: M,
    exclusive state: S,
    consume: MemberConsumer<M, S>,
    unknown: UnknownConsumer<S>
): nil

Reads a structure at a member.

Each declared member the policy reads is passed to consume, and each wire field the model does not declare to unknown.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`
`exclusive state`	`S`
`consume`	`MemberConsumer<M, S>`
`unknown`	`UnknownConsumer<S>`

Returns

Type	Description
`nil`

`readUnion`method#

readUnion: function<S>(
    exclusive self: Reader<M>,
    member: M,
    exclusive state: S,
    consume: MemberConsumer<M, S>,
    unknown: UnknownConsumer<S>
): nil

Reads a union at a member, raising unless it holds exactly one alternative.

A declared alternative is passed to consume, and an undeclared one to unknown.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`
`exclusive state`	`S`
`consume`	`MemberConsumer<M, S>`
`unknown`	`UnknownConsumer<S>`

Returns

Type	Description
`nil`

`readList`method#

readList: function<S>(exclusive self: Reader<M>, member: M, exclusive state: S, consume: ElementConsumer<M, S>): nil

Reads a list at a member, passing each element to consume in order.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`
`exclusive state`	`S`
`consume`	`ElementConsumer<M, S>`

Returns

Type	Description
`nil`

`readTuple`method#

readTuple: function<S>(
    exclusive self: Reader<M>,
    member: M,
    size: integer,
    exclusive state: S,
    consume: ElementConsumer<M, S>
): nil

Reads a tuple of size slots at a member, passing each to consume in order. The codec raises when the input holds a different count.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`
`size`	`integer`
`exclusive state`	`S`
`consume`	`ElementConsumer<M, S>`

Returns

Type	Description
`nil`

`readMap`method#

readMap: function<S>(exclusive self: Reader<M>, member: M, exclusive state: S, consume: EntryConsumer<M, S>): nil

Reads a map at a member, passing each entry's key and value to consume.

Arguments

Name	Type	Description
`exclusive self`	`Reader<M>`
`member`	`M`
`exclusive state`	`S`
`consume`	`EntryConsumer<M, S>`

Returns

Type	Description
`nil`

`containerSize`method#

containerSize: function(self): integer?

Returns the member, element, or entry count of the next value when the format knows it before reading, or nil.

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`integer?`

`ScalarKind`type#

type ScalarKind = "null"
| "boolean"
| "integer"
| "float"
| "bigInteger"
| "decimal"
| "numberToken"
| "string"
| "bytes"
| "timestamp"
| "atom"
| "document"

The scalar kinds a Writer and Reader carry.

`Timestamp`record#

record Timestamp ...

An instant as whole seconds since the Unix epoch, in decimal text, and nanoseconds within that second.

Members

Name	Kind	Description
`seconds`	field	Whole seconds since the Unix epoch, as decimal integer text.
`nanos`	field	Nanoseconds within the second, from 0 through 999999999.

`seconds`field#

seconds: string

@readonly

Whole seconds since the Unix epoch, as decimal integer text.

`nanos`field#

nanos: integer

@readonly

Nanoseconds within the second, from 0 through 999999999.

`UnknownConsumer`interface#

interface UnknownConsumer<S> ...

Receives a wire field the model does not declare.

Type parameters

Name	Description
`S`

Members

Name	Kind	Description
`apply`	method	Receives an undeclared field, whose value it must skip or capture through value.

`apply`method#

apply: function<F is WireField>(self, exclusive state: S, field: F, exclusive value: UnknownReader): nil

Receives an undeclared field, whose value it must skip or capture through value.

Arguments

Name	Type	Description
`?`	`self`
`exclusive state`	`S`
`field`	`F`
`exclusive value`	`UnknownReader`

Returns

Type	Description
`nil`

`UnknownReader`interface#

interface UnknownReader ...

Skips or captures an undeclared wire field's value.

Members

Name	Kind	Description
`skipValue`	method	Skips the value.
`captureValue`	method	Reads the value as a document through adapter.

`skipValue`method#

skipValue: function(exclusive self: UnknownReader): nil

Skips the value.

Arguments

Name	Type	Description
`exclusive self`	`UnknownReader`

Returns

Type	Description
`nil`

`captureValue`method#

captureValue: function<D>(exclusive self: UnknownReader, adapter: DocumentAdapter<D>): D

Reads the value as a document through adapter.

Arguments

Name	Type	Description
`exclusive self`	`UnknownReader`
`adapter`	`DocumentAdapter<D>`

Returns

Type	Description
`D`

`WireField`interface#

interface WireField ...

A wire field a decoder met that the model does not declare.

Members

Name	Kind	Description
`diagnosticLabel`	method	Returns the field's name as a diagnostic shows it.

`diagnosticLabel`method#

diagnosticLabel: function(self): string

Returns the field's name as a diagnostic shows it.

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`string`

`Writer`interface#

interface Writer<M is Member> is nupp.Closeable ...

What a codec emits a value into. Adapters call it; codecs implement it.

Type parameters

Name	Description
`M`

Members

Name	Kind	Description
`include`	method	Returns whether the codec's policy writes a member at all.
`writeNull`	method	Writes an explicit null at a member.
`writeBoolean`	method	Writes a boolean at a member.
`writeInteger`	method	Writes an integer at a member, raising when it does not fit its width.
`writeFloat`	method	Writes a floating-point value at a member, narrowed to width bits.
`writeBigInteger`	method	Writes an integer of any size, given as decimal text, at a member.
`writeDecimal`	method	Writes an exact decimal at a member.
`writeNumberToken`	method	Writes a number given as unparsed number text at a member.
`writeString`	method	Writes a string at a member.
`writeBytes`	method	Writes a byte string at a member.
`writeTimestamp`	method	Writes a timestamp at a member.
`writeAtom`	method	Writes a model-defined atom at a member.
`writeDocument`	method	Writes a document at a member, through adapter.
`writeStruct`	method	Writes a structure at a member, whose members emit writes from source.
`writeUnion`	method	Writes a union at a member.
`writeList`	method	Writes a list at a member, whose elements emit writes from source.
`writeTuple`	method	Writes a tuple of size slots at a member, which emit writes from source.
`writeMap`	method	Writes a map at a member, whose entries emit writes from source through writeEntry.
`writeEntry`	method	Writes one entry of the map being written.
`writeUnknown`	method	Writes an undeclared wire field, such as one captured on an earlier read, into the structure being written.

`include`method#

include: function(exclusive self: Writer<M>, member: M): boolean

Returns whether the codec's policy writes a member at all.

An adapter skips the member on false. The codec may already have written a substitute in its place, such as a redaction.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`

Returns

Type	Description
`boolean`

`writeNull`method#

writeNull: function(exclusive self: Writer<M>, member: M): nil

Writes an explicit null at a member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`

Returns

Type	Description
`nil`

`writeBoolean`method#

writeBoolean: function(exclusive self: Writer<M>, member: M, value: boolean): nil

Writes a boolean at a member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`value`	`boolean`

Returns

Type	Description
`nil`

`writeInteger`method#

writeInteger: function(exclusive self: Writer<M>, member: M, borrows value: Integer): nil

Writes an integer at a member, raising when it does not fit its width.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`borrows value`	`Integer`

Returns

Type	Description
`nil`

`writeFloat`method#

writeFloat: function(exclusive self: Writer<M>, member: M, value: number, width: 32 | 64): nil

Writes a floating-point value at a member, narrowed to width bits.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`value`	`number`
`width`	`32 \| 64`

Returns

Type	Description
`nil`

`writeBigInteger`method#

writeBigInteger: function(exclusive self: Writer<M>, member: M, value: string): nil

Writes an integer of any size, given as decimal text, at a member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`value`	`string`

Returns

Type	Description
`nil`

`writeDecimal`method#

writeDecimal: function(exclusive self: Writer<M>, member: M, borrows value: Decimal): nil

Writes an exact decimal at a member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`borrows value`	`Decimal`

Returns

Type	Description
`nil`

`writeNumberToken`method#

writeNumberToken: function(exclusive self: Writer<M>, member: M, value: string): nil

Writes a number given as unparsed number text at a member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`value`	`string`

Returns

Type	Description
`nil`

`writeString`method#

writeString: function(exclusive self: Writer<M>, member: M, value: string): nil

Writes a string at a member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`value`	`string`

Returns

Type	Description
`nil`

`writeBytes`method#

writeBytes: function(exclusive self: Writer<M>, member: M, value: string): nil

Writes a byte string at a member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`value`	`string`

Returns

Type	Description
`nil`

`writeTimestamp`method#

writeTimestamp: function(exclusive self: Writer<M>, member: M, borrows value: Timestamp): nil

Writes a timestamp at a member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`borrows value`	`Timestamp`

Returns

Type	Description
`nil`

`writeAtom`method#

writeAtom: function<A is Atom>(exclusive self: Writer<M>, member: M, borrows value: A): nil

Writes a model-defined atom at a member. A codec that cannot represent the atom raises.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`borrows value`	`A`

Returns

Type	Description
`nil`

`writeDocument`method#

writeDocument: function<D>(exclusive self: Writer<M>, member: M, borrows value: D, adapter: DocumentAdapter<D>): nil

Writes a document at a member, through adapter.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`borrows value`	`D`
`adapter`	`DocumentAdapter<D>`

Returns

Type	Description
`nil`

`writeStruct`method#

writeStruct: function<S>(exclusive self: Writer<M>, member: M, borrows source: S, emit: Members<M, S>): nil

Writes a structure at a member, whose members emit writes from source.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`borrows source`	`S`
`emit`	`Members<M, S>`

Returns

Type	Description
`nil`

`writeUnion`method#

writeUnion: function<S>(exclusive self: Writer<M>, member: M, borrows source: S, emit: Members<M, S>): nil

Writes a union at a member. emit writes exactly one alternative from source.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`borrows source`	`S`
`emit`	`Members<M, S>`

Returns

Type	Description
`nil`

`writeList`method#

writeList: function<S>(
    exclusive self: Writer<M>,
    member: M,
    size: integer?,
    borrows source: S,
    emit: Members<M, S>
): nil

Writes a list at a member, whose elements emit writes from source.

size is the element count, or nil when it is not known in advance. The codec raises when emit writes a different count.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`size`	`integer?`
`borrows source`	`S`
`emit`	`Members<M, S>`

Returns

Type	Description
`nil`

`writeTuple`method#

writeTuple: function<S>(
    exclusive self: Writer<M>,
    member: M,
    size: integer,
    borrows source: S,
    emit: Members<M, S>
): nil

Writes a tuple of size slots at a member, which emit writes from source. The codec raises when emit writes a different count.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`size`	`integer`
`borrows source`	`S`
`emit`	`Members<M, S>`

Returns

Type	Description
`nil`

`writeMap`method#

writeMap: function<S>(
    exclusive self: Writer<M>,
    member: M,
    size: integer?,
    borrows source: S,
    emit: Members<M, S>
): nil

Writes a map at a member, whose entries emit writes from source through writeEntry.

size is the entry count, or nil when it is not known in advance. The codec raises when emit writes a different count.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`member`	`M`
`size`	`integer?`
`borrows source`	`S`
`emit`	`Members<M, S>`

Returns

Type	Description
`nil`

`writeEntry`method#

writeEntry: function<K, V>(
    exclusive self: Writer<M>,
    borrows key: K,
    keyEmit: Members<M, K>,
    borrows value: V,
    valueEmit: Members<M, V>
): nil

Writes one entry of the map being written.

keyEmit writes exactly one value from key, and valueEmit exactly one from value. The codec raises outside a writeMap.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`borrows key`	`K`
`keyEmit`	`Members<M, K>`
`borrows value`	`V`
`valueEmit`	`Members<M, V>`

Returns

Type	Description
`nil`

`writeUnknown`method#

writeUnknown: function<F is WireField, D>(
    exclusive self: Writer<M>,
    field: F,
    borrows value: D,
    adapter: DocumentAdapter<D>
): nil

Writes an undeclared wire field, such as one captured on an earlier read, into the structure being written.

adapter writes the field's document value. The codec raises outside a structure or union, or when the field collides with a declared member.

Arguments

Name	Type	Description
`exclusive self`	`Writer<M>`
`field`	`F`
`borrows value`	`D`
`adapter`	`DocumentAdapter<D>`

Returns

Type	Description
`nil`

Functions#

`access`function#

function access<T is nupp.Copyable>(target: Type<T>): Access<T>

Returns the Access for a declaration, cached on the declaration.

local serde = require("nupp.serde")
local record Point
    x: number
    y: number = 0
end
local point = serde.access(Point)
assert(#point.fields == 2 and point.fields[2].hasDefault)

Type parameters

Name	Description
`T`

Arguments

Name	Type	Description
`target`	`Type<T>`

Returns

Type	Description
`Access<T>`

`binding`function#

function binding<T is nupp.Copyable>(target: Type<T>, options: Options?): core.Binding<T>

Builds a binding from a record or struct declaration.

Fields are read through the declaration's own access rules and values are constructed through its constructor, so defaults, @private storage, and custom construction all hold. Recursive types are supported. Optional fields and homogeneous literal unions use their declared carriers; a record union needs an explicit Adapter, since a declaration names no discriminator.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record Node
    name: string
    children: {Node} = {}
end
local nodes = serde.binding(Node)
local tree = new Node(name = "root", children = {new Node(name = "leaf")})
assert(json.encode(nodes, tree) == '{"name":"root","children":[{"name":"leaf","children":[]}]}')

Type parameters

Name	Description
`T`

Arguments

Name	Type	Description
`target`	`Type<T>`
`options`	`Options?`

Returns

Type	Description
`core.Binding<T>`

Values#

`iso8601Seconds`variable#

const iso8601Seconds: "iso8601Seconds"

The representation that writes an integer field of epoch seconds as an RFC 3339 timestamp, and reads one back.

local serde = require("nupp.serde")
local json = require("nupp.serde.json")
local record Event
    at: integer
end
local events = serde.binding(Event, new serde.Options(
    fields = {at = new serde.FieldOptions(representation = serde.iso8601Seconds)}
))
assert(json.encode(events, new Event(at = 0)) == '{"at":"1970-01-01T00:00:00Z"}')
assert(json.decode(events, '{"at":"1970-01-01T00:01:00Z"}').at == 60)

nupp.serde

Submodules

Module contents

Types

Functions

Values

Types#

Accessrecord#

Type parameters

Members

infofield#

typeIndexfield#

fieldsfield#

parametersfield#

ownerfield#

targetfield#

defaultsfield#

constructorconstructor#

constructionProblemfield#

accessiblefield#

nestedCachefield#

getmethod#

Arguments

Returns

Raises

beginmethod#

Arguments

Returns

Raises

constructionErrormethod#

Arguments

Returns

nestedmethod#

Arguments

Returns

Raises

finishmethod#

Arguments

Returns

Raises

Adapterinterface#

Type parameters

Members

describemethod#

Arguments

Returns

writemethod#

Arguments

Returns

readmethod#

Arguments

Returns

Atominterface#

Members

familyfield#

snapshotmethod#

Arguments

Returns

Bindinginterface#

Type parameters

Members

acceptmethod#

Arguments

Returns

acceptIntomethod#

Arguments

Returns

Boundrecord#

Type parameters

Members

adapterfield#

discardmethod#

Arguments

Returns

acceptmethod#

Arguments

Returns

acceptIntomethod#

Arguments

Returns

`nupp.serde`

`Access`record#

`info`field#

`typeIndex`field#

`fields`field#

`parameters`field#

`owner`field#

`target`field#

`defaults`field#

`constructor`constructor#

`constructionProblem`field#

`accessible`field#

`nestedCache`field#

`get`method#

`begin`method#

`constructionError`method#

`nested`method#

`finish`method#

`Adapter`interface#

`describe`method#

`write`method#

`read`method#

`Atom`interface#

`family`field#

`snapshot`method#

`Binding`interface#

`accept`method#

`acceptInto`method#

`Bound`record#

`adapter`field#

`discard`method#

`accept`method#

`acceptInto`method#

`Child`interface#

`member`field#

`required`field#

`hasDefault`field#

`describe`method#

`Consumer`interface#

`apply`method#

`Context`interface#

`codec`field#

`profile`field#

`parent`field#

`get`method#

`Decimal`record#

`coefficient`field#

`exponent`field#

`Description`interface#

`kind`field#

`member`field#

`nullable`field#

`width`field#

`signed`field#

`canRead`field#

`children`field#

`Direction`type#

`Discard`interface#

`discard`method#

`DocumentAdapter`interface#

`context`method#

`contents`method#

`readContents`method#

`DocumentElement`interface#

`apply`method#

`DocumentEntry`interface#

`apply`method#

`DocumentMember`interface#