# `nupp.serde.document`
A document is a value without a schema, which any codec reads and writes. This
module holds the [`Document`](#nupp.serde.document.Document) tree, conversion between bound values and
documents, typed views, and saved `nupp.util.Store` snapshots; see
[Serialization bindings](../../../../learn/runtime/data/serde/index.html#documents) for the guide.
```nupp
local document = require("nupp.serde.document")
local json = require("nupp.serde.json")
local value = json.decodeDocument(document.adapter(), '{"id":18446744073709551615,"tags":["a","b"]}')
assert(value.kind == "structure")
assert(assert(value:get("id")):numberToken() == "18446744073709551615")
assert(assert(value:get("tags")):at(2):string() == "b")
assert(json.encodeDocument(document.adapter(), value) == '{"id":18446744073709551615,"tags":["a","b"]}')
```
A document keeps what the codec read without rounding it: integers beyond 2^53
stay exact, decimals keep their digits, floats keep their width, and absent,
null, and present members stay distinct. It also keeps the
`nupp.serde.Context` it was read under, so a protocol can tell where it came
from.
A document-valued member, one a schema declares without describing, is a
document *boundary*: [`boundary`](#nupp.serde.document.boundary) wraps its contents so a protocol can treat
the member separately from the value inside it.
[`from`](#nupp.serde.document.from) and [`into`](#nupp.serde.document.into) cross between a bound value and its document, which is
how a value moves between codecs or is inspected without knowing its type:
```nupp
local serde = require("nupp.serde")
local document = require("nupp.serde.document")
local record Point
x: integer
y: integer
end
local points = serde.binding(Point)
local tree = document.from(points, new Point(x = 1, y = 2))
assert(assert(tree:get("y")):numberToken() == "2")
assert(document.into(points, tree).x == 1)
```
## Types
### `Decoder` _interface_
```nupp
interface Decoder ...
```
Constructs values of one binding from documents, without looking the
binding up each time.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`read`](#nupp.serde.document.Decoder.read) | method | Constructs a value from a document. |
#### `read` _method_
```nupp
read: function(self, value: documents.Document): T
```
Constructs a value from a document.
The binding's construction runs exactly as a codec decoder's would, so
required fields and defaults are checked the same way.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `self` | |
| `value` | `documents.Document` | the document |
##### Returns
| Type | Description |
| --- | --- |
| `T` | the value |
##### Raises
| Type | Condition |
| --- | --- |
| `nupp.serde.Error` | when the document does not fit the binding |
| `string` | when the binding does not consume the document |
### `Document` _record_
```nupp
record Document ...
```
An immutable value tree.
`kind` says which accessor applies: `string()` for a string, `at(i)` and
`size()` for a list or tuple, `get(name)` and `field(i)` for a structure,
`entry(i)` for a map, `document()` for a boundary. `get` returns nil on any
other kind; a scalar accessor raises on a document of another kind.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`kind`](#nupp.serde.document.Document.kind) | field | The kind of value the document holds, which decides the accessor that applies. |
| [`text`](#nupp.serde.document.Document.text) | field | |
| [`flag`](#nupp.serde.document.Document.flag) | field | |
| [`time`](#nupp.serde.document.Document.time) | field | |
| [`integerValue`](#nupp.serde.document.Document.integerValue) | field | |
| [`decimalValue`](#nupp.serde.document.Document.decimalValue) | field | |
| [`floatValue`](#nupp.serde.document.Document.floatValue) | field | |
| [`atomValue`](#nupp.serde.document.Document.atomValue) | field | |
| [`entries`](#nupp.serde.document.Document.entries) | field | |
| [`elements`](#nupp.serde.document.Document.elements) | field | |
| [`fields`](#nupp.serde.document.Document.fields) | field | |
| [`source`](#nupp.serde.document.Document.source) | field | |
| [`size`](#nupp.serde.document.Document.size) | method | Returns how many values the document holds directly. |
| [`at`](#nupp.serde.document.Document.at) | method | Returns the element at a position in a list or tuple. |
| [`get`](#nupp.serde.document.Document.get) | method | Finds the member of a structure or union by name. |
| [`string`](#nupp.serde.document.Document.string) | method | Returns the string a string document holds. |
| [`numberToken`](#nupp.serde.document.Document.numberToken) | method | Returns the lexeme a numberToken document holds. |
| [`boolean`](#nupp.serde.document.Document.boolean) | method | Returns the value a boolean document holds. |
| [`integer`](#nupp.serde.document.Document.integer) | method | Returns the fixed-width integer an integer document holds. |
| [`decimal`](#nupp.serde.document.Document.decimal) | method | Returns the exact decimal a decimal document holds. |
| [`float`](#nupp.serde.document.Document.float) | method | Returns the float a float document holds. |
| [`bytes`](#nupp.serde.document.Document.bytes) | method | Returns the binary data a bytes document holds. |
| [`bigInteger`](#nupp.serde.document.Document.bigInteger) | method | Returns the integer a bigInteger document holds. |
| [`timestamp`](#nupp.serde.document.Document.timestamp) | method | Returns the timestamp a timestamp document holds. |
| [`atom`](#nupp.serde.document.Document.atom) | method | Returns a snapshot of the atom an atom document holds. |
| [`entry`](#nupp.serde.document.Document.entry) | method | Returns the entry at a position in a map document. |
| [`field`](#nupp.serde.document.Document.field) | method | Returns the member at a position in a structure or union document. |
| [`document`](#nupp.serde.document.Document.document) | method | Returns the contents of a document boundary. |
| [`context`](#nupp.serde.document.Document.context) | method | Returns the context the document carries. |
#### `kind` _field_
```nupp
kind: core.Kind
```
`@readonly`
The kind of value the document holds, which decides the accessor that
applies.
#### `text` _field_
```nupp
text: string?
```
`@private` `@readonly`
#### `flag` _field_
```nupp
flag: boolean?
```
`@private` `@readonly`
#### `time` _field_
```nupp
time: core.Timestamp?
```
`@private` `@readonly`
#### `integerValue` _field_
```nupp
integerValue: core.Integer?
```
`@private` `@readonly`
#### `decimalValue` _field_
```nupp
decimalValue: core.Decimal?
```
`@private` `@readonly`
#### `floatValue` _field_
```nupp
floatValue: core.Float?
```
`@private` `@readonly`
#### `atomValue` _field_
```nupp
atomValue: core.Atom?
```
`@private` `@readonly`
#### `entries` _field_
```nupp
entries: {MapEntry}?
```
`@private` `@readonly`
#### `elements` _field_
```nupp
elements: {Document}
```
`@private` `@readonly`
#### `fields` _field_
```nupp
fields: {Entry}
```
`@private` `@readonly`
#### `source` _field_
```nupp
source: core.Context?
```
`@private` `@readonly`
#### `size` _method_
```nupp
size: function size(self): integer
```
Returns how many values the document holds directly.
A structure or union counts its members, a map its entries, and a
list or tuple its elements. A boundary counts its contents as one,
and any other kind returns 0.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `integer` | the count |
#### `at` _method_
```nupp
at: function at(self, index: integer): Document
```
Returns the element at a position in a list or tuple.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `index` | `integer` | the 1-based position |
##### Returns
| Type | Description |
| --- | --- |
| `Document` | the element |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when no element is at the index |
#### `get` _method_
```nupp
get: function get(self, name: string): Document?
```
Finds the member of a structure or union by name.
Any other kind has no members, so it returns nil.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `name` | `string` | the member name |
##### Returns
| Type | Description |
| --- | --- |
| `Document?` | the member's value, or nil when no member has the name |
#### `string` _method_
```nupp
string: function string(self): string
```
Returns the string a `string` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a string |
#### `numberToken` _method_
```nupp
numberToken: function numberToken(self): string
```
Returns the lexeme a `numberToken` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | the number as it was written |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a number token |
#### `boolean` _method_
```nupp
boolean: function boolean(self): boolean
```
Returns the value a `boolean` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `boolean` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a boolean |
#### `integer` _method_
```nupp
integer: function integer(self): core.Integer
```
Returns the fixed-width integer an `integer` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `core.Integer` | the integer's decimal digits, width, and signedness |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not an integer |
#### `decimal` _method_
```nupp
decimal: function decimal(self): core.Decimal
```
Returns the exact decimal a `decimal` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `core.Decimal` | the decimal's coefficient and exponent |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a decimal |
#### `float` _method_
```nupp
float: function float(self): core.Float
```
Returns the float a `float` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `core.Float` | the float's value and width |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a float |
#### `bytes` _method_
```nupp
bytes: function bytes(self): string
```
Returns the binary data a `bytes` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | the data as a string |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not bytes |
#### `bigInteger` _method_
```nupp
bigInteger: function bigInteger(self): string
```
Returns the integer a `bigInteger` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `string` | the integer's decimal text |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a big integer |
#### `timestamp` _method_
```nupp
timestamp: function timestamp(self): core.Timestamp
```
Returns the timestamp a `timestamp` document holds.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `core.Timestamp` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a timestamp |
#### `atom` _method_
```nupp
atom: function atom(self): core.Atom
```
Returns a snapshot of the atom an `atom` document holds.
Each call returns a new snapshot, so the document keeps its own.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `core.Atom` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not an atom |
#### `entry` _method_
```nupp
entry: function entry(self, index: integer): MapEntry
```
Returns the entry at a position in a `map` document.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `index` | `integer` | the 1-based position |
##### Returns
| Type | Description |
| --- | --- |
| `MapEntry` | the entry |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a map |
| `string` | when no entry is at the index |
#### `field` _method_
```nupp
field: function field(self, index: integer): Entry
```
Returns the member at a position in a `structure` or `union` document.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
| `index` | `integer` | the 1-based position |
##### Returns
| Type | Description |
| --- | --- |
| `Entry` | the member |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is neither a structure nor a union |
| `string` | when no member is at the index |
#### `document` _method_
```nupp
document: function document(self): Document
```
Returns the contents of a `document` boundary.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `Document` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the document is not a boundary |
#### `context` _method_
```nupp
context: function context(self): core.Context?
```
Returns the context the document carries.
A decoded document carries the context it was read under, and
[`nupp.serde.document.withContext`](#nupp.serde.document.withContext) attaches one to any document.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `core.Context?` | the context, or nil when the document has none |
### `Entry` _record_
```nupp
record Entry ...
```
A named structure member, as [`object`](#nupp.serde.document.object) takes and `Document:field` returns.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`name`](#nupp.serde.document.Entry.name) | field | The member's name. |
| [`value`](#nupp.serde.document.Entry.value) | field | The member's value. |
#### `name` _field_
```nupp
name: string
```
`@readonly`
The member's name.
#### `value` _field_
```nupp
value: Document
```
`@readonly`
The member's value.
### `MapEntry` _record_
```nupp
record MapEntry ...
```
A map entry, whose key is itself a document.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`key`](#nupp.serde.document.MapEntry.key) | field | The entry's key. |
| [`value`](#nupp.serde.document.MapEntry.value) | field | The entry's value. |
#### `key` _field_
```nupp
key: Document
```
`@readonly`
The entry's key.
#### `value` _field_
```nupp
value: Document
```
`@readonly`
The entry's value.
### `Migration` _interface_
```nupp
interface Migration ...
```
Upgrades a saved entry from an older version to the current one.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`apply`](#nupp.serde.document.Migration.apply) | method | Upgrades a saved entry's document to the registered version. |
#### `apply` _method_
```nupp
apply: function(self, previousVersion: integer, value: documents.Document): documents.Document
```
Upgrades a saved entry's document to the registered version.
Loading calls it once per older entry, and its result is constructed
through the registered binding, so it must return the current
version's document directly.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `self` | |
| `previousVersion` | `integer` | the version the entry was saved at |
| `value` | `documents.Document` | the saved document |
##### Returns
| Type | Description |
| --- | --- |
| `documents.Document` | the document at the registered version |
### `StoreEntry` _record_
```nupp
record StoreEntry ...
```
One saved store entry: its name, version, and document.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`name`](#nupp.serde.document.StoreEntry.name) | field | The name the entry's key is registered under. |
| [`version`](#nupp.serde.document.StoreEntry.version) | field | The version the entry was saved at. |
| [`value`](#nupp.serde.document.StoreEntry.value) | field | The entry's value, as a document. |
#### `name` _field_
```nupp
name: string
```
`@readonly`
The name the entry's key is registered under.
#### `version` _field_
```nupp
version: integer
```
`@readonly`
The version the entry was saved at.
#### `value` _field_
```nupp
value: documents.Document
```
`@readonly`
The entry's value, as a document.
### `StoreRegistry` _interface_
```nupp
interface StoreRegistry ...
```
Saves and restores the entries of a `nupp.util.Store` by name and
version.
Each registered key names its entry, its binding, its current version, and
the migration that upgrades an older one. Saving produces a
[`StoreSnapshot`](#nupp.serde.document.StoreSnapshot) any codec can carry through [`storeBinding`](#nupp.serde.document.storeBinding).
```nupp
local serde = require("nupp.serde")
local document = require("nupp.serde.document")
local json = require("nupp.serde.json")
local record Settings
volume: integer
end
local settings: nupp.util.Key = nupp.util.newKey()
local registry = document.storeRegistry()
registry:register("settings", settings, serde.binding(Settings), 1, nil)
local store = nupp.util.newStore()
store:set(settings, new Settings(volume = 7))
local bytes = json.encode(document.storeBinding(), registry:save(store))
local restored = registry:load(json.decode(document.storeBinding(), bytes), "reject")
assert(assert(restored:get(settings)).volume == 7)
```
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`register`](#nupp.serde.document.StoreRegistry.register) | method | Registers a store key for saving under a persistent name. |
| [`save`](#nupp.serde.document.StoreRegistry.save) | method | Saves the registered keys that hold a value in a store. |
| [`load`](#nupp.serde.document.StoreRegistry.load) | method | Restores a snapshot's entries into a new store. |
#### `register` _method_
```nupp
register: function(
self,
name: string,
key: util.Key,
binding: core.Binding,
version: integer,
migration: Migration?
): nil
```
Registers a store key for saving under a persistent name.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `self` | |
| `name` | `string` | the name the key's entry is saved under |
| `key` | `util.Key\` | the store key |
| `binding` | `core.Binding\` | the binding the key's value is saved and restored through |
| `version` | `integer` | the current version, a positive integer |
| `migration` | `Migration?` | the migration that upgrades an older entry, or nil when only the current version loads |
##### Returns
| Type | Description |
| --- | --- |
| `nil` | |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the name is empty or already registered |
| `string` | when the key is already registered |
| `string` | when the version is not a positive integer |
#### `save` _method_
```nupp
save: function(self, borrows store: util.Store): Snapshot
```
Saves the registered keys that hold a value in a store.
Entries are in registration order, each at its key's current version.
A registered key the store holds no value under is left out.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `self` | |
| `borrows store` | `util.Store` | the store to read, which is borrowed |
##### Returns
| Type | Description |
| --- | --- |
| `Snapshot` | the snapshot |
#### `load` _method_
```nupp
load: function(self, snapshot: Snapshot, unknown: "reject" | "skip"): util.Store
```
Restores a snapshot's entries into a new store.
An entry at its key's registered version is constructed through the
binding as it is. An older entry passes through the key's migration
first. A newer entry, or an older one with no migration, raises.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `?` | `self` | |
| `snapshot` | `Snapshot` | the saved entries |
| `unknown` | `"reject" | "skip"` | "reject" to raise on an entry whose name is not registered, or "skip" to leave it out |
##### Returns
| Type | Description |
| --- | --- |
| `util.Store` | the store holding every restored entry |
##### Raises
| Type | Condition |
| --- | --- |
| `string` | when the snapshot's format is not 1 |
| `string` | when two entries share a name |
| `string` | when an entry's name is not registered and `unknown` is "reject" |
| `string` | when an entry's version is not a positive integer, is newer than the registered version, or is older with no migration |
| `nupp.serde.Error` | when an entry's document does not fit its binding |
| `string` | when an entry's document constructs a nil value |
### `StoreSnapshot` _record_
```nupp
record StoreSnapshot ...
```
The saved entries of a store.
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`format`](#nupp.serde.document.StoreSnapshot.format) | field | The snapshot layout version, which loading requires to be 1. |
| [`entries`](#nupp.serde.document.StoreSnapshot.entries) | field | The saved entries. |
#### `format` _field_
```nupp
format: integer
```
`@readonly`
The snapshot layout version, which loading requires to be 1.
#### `entries` _field_
```nupp
entries: {Entry}
```
`@readonly`
The saved entries.
### `View` _record_
```nupp
record View ...
```
A bound value presented as a document, without building the tree.
A codec reads the current value through the binding each time, so a view
follows changes to its owner. `snapshot()` reconstructs a detached copy,
and `document()` materializes the tree when one is wanted.
```nupp
local serde = require("nupp.serde")
local document = require("nupp.serde.document")
local json = require("nupp.serde.json")
local record Counter
count: integer
end
local counters = serde.binding(Counter)
local owner = new Counter(count = 1)
local live = document.view(counters, owner)
local frozen = live:snapshot()
owner.count = 2
local views = document.viewAdapter(counters)
assert(json.encodeDocument(views, live) == '{"count":2}')
assert(json.encodeDocument(views, frozen) == '{"count":1}')
```
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Members
| Name | Kind | Description |
| --- | --- | --- |
| [`binding`](#nupp.serde.document.View.binding) | field | The binding the view reads its value through. |
| [`value`](#nupp.serde.document.View.value) | field | |
| [`source`](#nupp.serde.document.View.source) | field | |
| [`context`](#nupp.serde.document.View.context) | method | Returns the context the view carries. |
| [`document`](#nupp.serde.document.View.document) | method | Builds the document tree of the value's current state. |
| [`snapshot`](#nupp.serde.document.View.snapshot) | method | Returns a view of an independent copy of the value. |
#### `binding` _field_
```nupp
binding: core.Binding
```
`@readonly`
The binding the view reads its value through.
#### `value` _field_
```nupp
value: T
```
`@private` `@readonly`
#### `source` _field_
```nupp
source: core.Context?
```
`@private` `@readonly`
#### `context` _method_
```nupp
context: function context(self): core.Context?
```
Returns the context the view carries.
A view made by [`nupp.serde.document.view`](#nupp.serde.document.view) carries the context it was
given, and a decoded view the context it was read under.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `core.Context?` | the context, or nil when the view has none |
#### `document` _method_
```nupp
document: function document(self): documents.Document
```
Builds the document tree of the value's current state.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `documents.Document` | the document, carrying the view's context |
#### `snapshot` _method_
```nupp
snapshot: function snapshot(self): View
```
Returns a view of an independent copy of the value.
The copy is reconstructed from the value's document through the
binding, so later changes to the original do not reach it.
##### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `self` | `any` | |
##### Returns
| Type | Description |
| --- | --- |
| `View\` | the detached view, with the same binding and context |
##### Raises
| Type | Condition |
| --- | --- |
| `nupp.serde.Error` | when the binding cannot construct a value from the document it wrote |
## Functions
### `adapter` _function_
```nupp
function adapter(): core.DocumentAdapter
```
Returns the adapter that reads and writes a [`Document`](#nupp.serde.document.Document) as its contents.
Pass it to a codec's `encodeDocument` and `decodeDocument`, or to
`nupp.serde.adapters.document` for a document-valued member.
#### Returns
| Type | Description |
| --- | --- |
| `core.DocumentAdapter\` | |
### `atom` _function_
```nupp
function atom(borrows value: core.Atom): Document
```
A model-defined atom, snapshotted so the document owns it.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `borrows value` | `core.Atom` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `bigInteger` _function_
```nupp
function bigInteger(value: string): Document
```
An integer of unbounded size, from its decimal text.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `boolean` _function_
```nupp
function boolean(value: boolean): Document
```
A boolean.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `boolean` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `boundary` _function_
```nupp
function boundary(value: Document): Document
```
A document boundary around contents, for a document-valued member.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `Document` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `bytes` _function_
```nupp
function bytes(value: string): Document
```
Binary data.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `cachedBindings` _function_
```nupp
function cachedBindings(): integer
```
Returns how many bindings the [`decoder`](#nupp.serde.document.decoder) cache holds.
#### Returns
| Type | Description |
| --- | --- |
| `integer` | |
### `clear` _function_
```nupp
function clear(): nil
```
Empties the [`decoder`](#nupp.serde.document.decoder) cache. Decoders already handed out keep working.
#### Returns
| Type | Description |
| --- | --- |
| `nil` | |
### `decimal` _function_
```nupp
function decimal(value: core.Decimal): Document
```
An exact decimal.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `core.Decimal` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `decoder` _function_
```nupp
function decoder(binding: core.Binding): Decoder
```
Returns a binding's [`Decoder`](#nupp.serde.document.Decoder), cached by binding identity.
The cache keeps at most 256 bindings and evicts the least recently used.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `binding` | `core.Binding\` | |
#### Returns
| Type | Description |
| --- | --- |
| `Decoder\` | |
### `float` _function_
```nupp
function float(value: core.Float): Document
```
A float with its width.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `core.Float` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `from` _function_
```nupp
function from(binding: core.Binding, borrows value: T, context: core.Context?): documents.Document
```
Converts a bound value to its document.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `binding` | `core.Binding\` | |
| `borrows value` | `T` | |
| `context` | `core.Context?` | |
#### Returns
| Type | Description |
| --- | --- |
| `documents.Document` | |
### `integer` _function_
```nupp
function integer(value: core.Integer): Document
```
A fixed-width integer.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `core.Integer` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `into` _function_
```nupp
function into(binding: core.Binding, value: documents.Document): T
```
Constructs a bound value from a document.
The binding's construction runs exactly as a decoder's would, so
required fields and defaults are checked the same way.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `binding` | `core.Binding\` | |
| `value` | `documents.Document` | |
#### Returns
| Type | Description |
| --- | --- |
| `T` | |
### `list` _function_
```nupp
function list(values: {Document}): Document
```
A list.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `values` | `{Document}` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `map` _function_
```nupp
function map(values: {MapEntry}): Document
```
A map whose keys are documents.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `values` | `{MapEntry}` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `null` _function_
```nupp
function null(): Document
```
A null.
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `numberToken` _function_
```nupp
function numberToken(value: string): Document
```
A number kept as the lexeme it was written as, such as a JSON number too
large for any integer width.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `object` _function_
```nupp
function object(values: {Entry}): Document
```
A structure, from its members in order.
```nupp
local document = require("nupp.serde.document")
local json = require("nupp.serde.json")
local value = document.object({
new document.Entry(name = "ok", value = document.boolean(true)),
new document.Entry(name = "note", value = document.null())
})
assert(json.encodeDocument(document.adapter(), value) == '{"ok":true,"note":null}')
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `values` | `{Entry}` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `reader` _function_
```nupp
function reader(value: documents.Document): Reader
```
Reads a document through the `nupp.serde.DocumentReader` contract, as a
codec's own reader would.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `documents.Document` | |
#### Returns
| Type | Description |
| --- | --- |
| `Reader` | |
### `snapshot` _function_
```nupp
function snapshot(value: documents.Document): documents.Document
```
Copies a document into one that owns all of its values.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `documents.Document` | |
#### Returns
| Type | Description |
| --- | --- |
| `documents.Document` | |
### `storeBinding` _function_
```nupp
function storeBinding(): core.Binding
```
Returns the binding a codec writes and reads a [`StoreSnapshot`](#nupp.serde.document.StoreSnapshot) through.
#### Returns
| Type | Description |
| --- | --- |
| `core.Binding\` | |
### `storeRegistry` _function_
```nupp
function storeRegistry(): Registry
```
Starts an empty [`StoreRegistry`](#nupp.serde.document.StoreRegistry).
#### Returns
| Type | Description |
| --- | --- |
| `Registry` | |
### `string` _function_
```nupp
function string(value: string): Document
```
A string.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `timestamp` _function_
```nupp
function timestamp(value: core.Timestamp): Document
```
A timestamp.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `core.Timestamp` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `tuple` _function_
```nupp
function tuple(values: {Document}): Document
```
A tuple: a list whose length is part of its shape.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `values` | `{Document}` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `union` _function_
```nupp
function union(name: string, value: Document): Document
```
A union: the one member that is set.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | |
| `value` | `Document` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |
### `view` _function_
```nupp
function view(binding: core.Binding, value: T, context: core.Context?): View
```
Presents a Copyable value as a [`View`](#nupp.serde.document.View).
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `binding` | `core.Binding\` | |
| `value` | `T` | |
| `context` | `core.Context?` | |
#### Returns
| Type | Description |
| --- | --- |
| `View\` | |
### `viewAdapter` _function_
```nupp
function viewAdapter(binding: core.Binding): core.DocumentAdapter>
```
Returns the document adapter for views of one binding.
#### Type parameters
| Name | Description |
| --- | --- |
| `T` | |
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `binding` | `core.Binding\` | |
#### Returns
| Type | Description |
| --- | --- |
| `core.DocumentAdapter\\>` | |
### `withContext` _function_
```nupp
function withContext(value: Document, context: core.Context): Document
```
The same document with a context attached.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `Document` | |
| `context` | `core.Context` | |
#### Returns
| Type | Description |
| --- | --- |
| `Document` | |