⌂ Modules nupp nupp.serde nupp.serde.adapters nupp.serde.adaptersThese builders give a model library that owns its schema adapters over its own nupp.serde.MemberSerialization bindings for how model bindings fit beside declaration bindings.
A declaration binding from nupp.serde.binding
local serde = require ( "nupp.serde" )
local adapters = require ( "nupp.serde.adapters" )
local json = require ( "nupp.serde.json" )
local plain = json . codec ( json . memberNamePolicy )
local record Member is serde . Member
@ readonly name : string
@ readonly index : integer ?
end
local record Book
title : string
tags : { string }
end
local record Draft is nupp . Closeable title : string ?
tags : { string } ?
function close ( takes self ) : nil
end
end
local record Construction is adapters . Construction < Book , Draft >
function begin ( self ) : Draft
return new Draft ( )
end
function finish ( self , takes draft : Draft ) : Book
local owned : Draft = draft
local book = new Book ( title = assert ( owned . title , "title is required" ) , tags = owned . tags or { } )
owned : close ( )
return book
end
end
local title = new Member ( name = "title" )
local tags = new Member ( name = "tags" )
local book = adapters . structure ( new Member ( name = "Book" ) , {
adapters . field < Book , Draft , string , Member > (
title ,
function ( borrows value : Book ) : string borrows ( value )
return value . title
end ,
function ( exclusive draft : Draft , value : string ) : nil
draft . title = value end ,
adapters . text ( title ) ,
true ,
false
) ,
adapters . field < Book , Draft , { string } , Member > (
tags ,
function ( borrows value : Book ) : { string } borrows ( value )
return value . tags
end ,
function ( exclusive draft : Draft , value : { string } ) : nil
draft . tags = value end ,
adapters . list ( tags , new Member ( name = "tag" ) , adapters . text ( new Member ( name = "tag" ) ) ) ,
false ,
true
)
} , new Construction ( ) )
local books : serde . Binding < Book > = new serde . Bound < Book , Member > ( adapter = book )
local bytes = plain : encode ( books , new Book ( title = "Dune" , tags = { "sf" } ) )
assert ( bytes == '{"title":"Dune","tags":["sf"]}' )
assert ( plain : decode ( books , '{"title":"Emma"}' ) . title == "Emma" ) Every builder takes the member the value sits at, so the same scalar adapter type serves a top-level value, a structure field, and a list element. Wrap the finished adapter in nupp.serde.Bound
Module contents Types Type Kind Description BorrowGettype Reads a field by borrowing it from the value. Constructioninterface How a structure opens and finishes the draft its fields are read into. Conversioninterface The projection convert applies: project on write, restore on read. CopyGettype Reads a field by copying it out of the value. Fieldinterface A field built by field, with the operations a codec needs to plan it. FieldConsumerinterface Visits one field of a structure with its value type recovered. Gettype A field reader, borrowed or copied. Hastype Decides whether a field is written for a value. IndexedValuerecord One record of a Layout, read and written through its slots. Layoutinterface A record whose fields are defined at runtime, for a model that loads its schema rather than generating Nupp types... Settype Stores a decoded field value into a structure's draft. Slotrecord A typed field of a Layout. StructureConsumerinterface Visits a structure adapter's fields and construction.
Functions Function Kind Description atomfunction A model-defined nupp.serde.Atom, passed through uninterpreted. bigIntegerfunction An integer of unbounded size, carried as its decimal text. booleanfunction A boolean. borrowedGetfunction Wraps a borrowing field reader. bytesfunction Binary data. convertfunction Converts between an application value and one an adapter already handles. copiedGetfunction Wraps a copying field reader, for a field computed rather than stored. decimalfunction An exact decimal, as a nupp.serde.Decimal. documentfunction A document-valued member: a value with no schema of its own, read and written through a document adapter such as... fieldfunction One field of a structure. floatfunction A floating-point number written at a fixed width. inspectfunction Opens a structure adapter to a consumer, for a codec that plans its own field layout, such as one that assigns... integerfunction An integer of a fixed width and signedness, as a nupp.serde.Integer. layoutfunction Starts an empty Layout. listfunction A list of values that share one element adapter. structurefunction A structure: named fields written in order, read in any order, and constructed through an exclusive draft. textfunction A UTF-8 string. timestampfunction An instant, as a nupp.serde.Timestamp.
Types
BorrowGettype Reads a field by borrowing it from the value.
Type parameters
Constructioninterface How a structure
The draft is exclusive and Closeable, so a failed read drops it rather than leaking a half-built value.
Type parameters
Members Name Kind Description beginmethod Opens an empty draft for one read. finishmethod Builds the value from a draft the fields have been read into.
beginmethod Opens an empty draft for one read.
Arguments
Returns Type Description S the draft the fields' setters write into
finishmethod Builds the value from a draft the fields have been read into.
The structure adapter does not check required or hasDefault itself, so finish is where a field that never arrived is reported or given its default. The draft is transferred to finish, which drops it.
Arguments Name Type Description ?self takes stateS the draft, after every field present in the input was set
Returns Type Description T the value
Conversioninterface The projection convertproject on write, restore on read.
Type parameters
Members Name Kind Description projectmethod Returns the value the base adapter writes in place of an application value. restoremethod Builds the application value from one the base adapter read.
projectmethod Returns the value the base adapter writes in place of an application value.
Arguments Name Type Description ?self borrows valueT the application value being written
Returns Type Description V the projected value
restoremethod restore : function ( self , value : V ) : T Builds the application value from one the base adapter read.
Arguments Name Type Description ?self valueV the value the base adapter read
Returns Type Description T the application value
CopyGettype Reads a field by copying it out of the value.
Type parameters
Fieldinterface A field built by field
Type parameters
Members Name Kind Description writemethod Writes the field of a value, or nothing when the value leaves it out. readmethod Reads the field's value and stores it into the draft. acceptmethod Hands the field's parts to a consumer with the field's value type recovered.
writemethod write : function ( self , borrows source : T , exclusive writer : core . Writer < M > ) : nil Writes the field of a value, or nothing when the value leaves it out.
The structure adapter asks writer:include first and calls this only for a member the writer includes.
Arguments Name Type Description ?self borrows sourceT the value the field is read from
exclusive writercore . Writer < M > the writer the field is written to
Returns
readmethod read : function ( self , exclusive state : S , exclusive reader : core . Reader < M > ) : nil Reads the field's value and stores it into the draft.
Arguments Name Type Description ?self exclusive stateS the draft being constructed
exclusive readercore . Reader < M > the reader positioned at the field's value
Returns
acceptmethod accept : function < R > ( self , consumer : FieldConsumer < T , S , M , R > ) : R Hands the field's parts to a consumer with the field's value type recovered.
Arguments Name Type Description ?self consumerFieldConsumer < T , S , M , R > what to apply to the field
Returns Type Description R the consumer's result
FieldConsumerinterface Visits one field of a structure with its value type recovered.
Type parameters
Members Name Kind Description applymethod Receives one field's parts with its value type V in scope.
applymethod Receives one field's parts with its value type V in scope.
Arguments Name Type Description ?self memberM the member the field sits at
hasHas < T > decides whether a value writes the field; always true when the field was built without present
getGet < T , V > reads the field from a value
setSet < S , V > stores a decoded value into the draft
adaptercore . Adapter < V , M > the field value's adapter
fallback( function ( ) : V ) ? supplies the field's default, or nil when the field carries none of its own
Returns Type Description R the consumer's result
Gettype A field reader, borrowed or copied.
Type parameters
Hastype Decides whether a field is written for a value.
Type parameters
IndexedValuerecord One record of a Layout
Members Name Kind Description ownerfield valuesfield presentfield hasmethod Returns whether a slot holds a value, explicit null included. getmethod Returns the value a slot holds. setmethod Stores a value under a slot and marks it present. removemethod Clears a slot, making it absent.
ownerfield @private @readonly
valuesfield @private @readonly
presentfield @private @readonly
hasmethod Returns whether a slot holds a value, explicit null included.
A slot whose adapter reads null holds nil and still counts as present, so has tells an explicit null from an absent field where get does not.
Arguments Name Type Description selfany slotSlot < V > the slot to test
Returns Type Description boolean whether the slot is present
Raises Type Condition string when the slot belongs to another layout
getmethod Returns the value a slot holds.
A default is not applied here. Decoding stores it when the field is absent, but a value made by the layout's value holds nothing until it is set.
Arguments Name Type Description selfany slotSlot < V > the slot to read
Returns Type Description V ? the value, or nil when the slot is absent or explicitly null
Raises Type Condition string when the slot belongs to another layout
setmethod Stores a value under a slot and marks it present.
Arguments Name Type Description selfany slotSlot < V > the slot to write
valueV the value, which is nil for an explicit null
Returns
Raises Type Condition string when the slot belongs to another layout
removemethod Clears a slot, making it absent.
Arguments Name Type Description selfany slotSlot < V > the slot to clear
Returns
Raises Type Condition string when the slot belongs to another layout
Layoutinterface interface Layout < M is core . Member > ... A record whose fields are defined at runtime, for a model that loads its schema rather than generating Nupp types from it.
Each field is a typed Slot
local serde = require ( "nupp.serde" )
local adapters = require ( "nupp.serde.adapters" )
local json = require ( "nupp.serde.json" )
local plain = json . codec ( json . memberNamePolicy )
local record Member is serde . Member
@ readonly name : string
@ readonly index : integer ?
end
local title = new Member ( name = "title" )
local pages = new Member ( name = "pages" )
local layout = adapters . layout ( new Member ( name = "Book" ) )
local titleSlot = layout : add ( title , adapters . text ( title ) , true )
local pagesSlot = layout : addDefault ( pages , adapters . float ( pages , 64 ) , function ( ) : number return 0 end )
local books = layout : binding ( )
local book = plain : decode ( books , '{"title":"Dune"}' )
assert ( book : get ( titleSlot ) == "Dune" and book : get ( pagesSlot ) == 0 )
book : set ( pagesSlot , 412 )
assert ( plain : encode ( books , book ) == '{"title":"Dune","pages":412}' ) Type parameters
Members Name Kind Description addmethod Adds a field with no default. addDefaultmethod Adds a field that falls back to a default when absent. valuemethod Makes an empty value of this layout, with every field absent. bindingmethod Returns the binding that reads and writes this layout's values.
addmethod Adds a field with no default.
A required field that is absent fails both directions: decoding raises once the input is read, and encoding raises at the field. An optional field that is absent is left out of the output and stays absent on decode.
Arguments Name Type Description ?self memberM the member the field sits at
adaptercore . Adapter < V , M > the field value's adapter, which must describe member
requiredboolean whether the field must be present
Returns Type Description Slot < V > the field's slot
Raises Type Condition string when the layout is sealed, the adapter describes another member, or the member is already a field
addDefaultmethod Adds a field that falls back to a default when absent.
Decoding stores the default in a value that lacks the field, so it reads as present. Encoding writes the default for an absent field without storing it.
Arguments Name Type Description ?self memberM the member the field sits at
adaptercore . Adapter < V , M > the field value's adapter, which must describe member
defaultfunction ( ) : V makes the field's default, called each time one is needed
Returns Type Description Slot < V > the field's slot
Raises Type Condition string when the layout is sealed, the adapter describes another member, or the member is already a field
valuemethod value : function ( self ) : Value Makes an empty value of this layout, with every field absent.
Arguments
Returns Type Description Value the value
bindingmethod binding : function ( self ) : core . Binding < Value > Returns the binding that reads and writes this layout's values.
The first call seals the layout, so no field can be added after it, and every call returns the same binding. Fields are written in the order they were added.
Arguments
Returns Type Description core . Binding < Value > the binding
Settype Stores a decoded field value into a structure's draft.
Type parameters
Slotrecord A typed field of a Layout
Type parameters
ownerfield @private @readonly
positionfield @private @readonly
valueTypefield valueType : ( function ( value : V ) : V ) ? @private @readonly
StructureConsumerinterface interface StructureConsumer < T , M is core . Member , R > ... Visits a structure adapter's fields and construction. See inspect
Type parameters
Members Name Kind Description applymethod Receives a structure adapter's parts with its draft type S in scope.
applymethod Receives a structure adapter's parts with its draft type S in scope.
Arguments Name Type Description ?self memberM the member the structure sits at
fieldsconst { Field < T , S , M > } the fields, in write order
constructionConstruction < T , S > how the structure opens and finishes its draft
unknowncore . UnknownConsumer < S > what the structure does with undeclared wire fields; the rejecting consumer when the adapter was built without one
additionalcore . Members < M , T > ? the extra members written after the fields, or nil
Returns Type Description R the consumer's result
Functions
atomfunction A model-defined nupp.serde.Atom
Type parameters
Arguments Name Type Description memberM
Returns
bigIntegerfunction An integer of unbounded size, carried as its decimal text.
Type parameters
Arguments Name Type Description memberM
Returns Type Description core . Adapter < string , M >
booleanfunction A boolean.
Type parameters
Arguments Name Type Description memberM
Returns
borrowedGetfunction Wraps a borrowing field reader.
Type parameters
Arguments
Returns
bytesfunction Binary data. JSON writes it as base64.
Type parameters
Arguments Name Type Description memberM
Returns Type Description core . Adapter < string , M >
convertfunction Converts between an application value and one an adapter already handles.
local serde = require ( "nupp.serde" )
local adapters = require ( "nupp.serde.adapters" )
local json = require ( "nupp.serde.json" )
local plain = json . codec ( json . memberNamePolicy )
local record Member is serde . Member
@ readonly name : string
@ readonly index : integer ?
end
local record Celsius
degrees : number
end
local record Degrees is adapters . Conversion < Celsius , number >
function project ( self , borrows value : Celsius ) : number
return value . degrees
end
function restore ( self , value : number ) : Celsius
return new Celsius ( degrees = value )
end
end
local member = new Member ( name = "temperature" )
local temperature : serde . Binding < Celsius > = new serde . Bound < Celsius , Member > (
adapter = adapters . convert ( adapters . float ( member , 64 ) , new Degrees ( ) )
)
assert ( plain : encode ( temperature , new Celsius ( degrees = 21.5 ) ) == "21.5" ) Type parameters
Arguments
Returns
copiedGetfunction Wraps a copying field reader, for a field computed rather than stored.
Type parameters
Arguments Name Type Description readCopyGet < T , V >
Returns
decimalfunction An exact decimal, as a nupp.serde.Decimal
Type parameters
Arguments Name Type Description memberM
Returns
documentfunction A document-valued member: a value with no schema of its own, read and written through a document adapter such as nupp.serde.document.adapter
Type parameters
Arguments
Returns
fieldfunction function field < T , S is nupp . Closeable , V is nupp . Copyable , M is core . Member > ( member : M , get : BorrowGet < T , V > , set : Set < S , V > , adapter : core . Adapter < V , M > , required : boolean , hasDefault : boolean , present : Has < T > ? ) : Field < T , S , M > One field of a structure
get borrows the field from the value on write and set stores a decoded one into the draft on read. A required field must be present when reading; hasDefault tells codecs the construction supplies one, so the field may be absent. present, when given, decides per value whether the field is written at all.
Type parameters
Arguments
Returns Type Description Field < T , S , M >
floatfunction function float < M is core . Member > ( member : M , width : 32 | 64 ) : core . Adapter < number , M > A floating-point number written at a fixed width.
A 32-bit float is rounded on write, so a codec that keeps widths, such as nupp.serde.nativefloat32.
Type parameters
Arguments Name Type Description memberM width32 | 64
Returns Type Description core . Adapter < number , M >
inspectfunction function inspect < T , M is core . Member , R > ( selected : core . Adapter < T , M > , consumer : Consumer < T , M , R > ) : R ? Opens a structure
Type parameters
Arguments
Returns
integerfunction An integer of a fixed width and signedness, as a nupp.serde.Integer
The codec checks the range on both sides, so a 64-bit value round-trips exactly on every target. Use convertinteger.
Type parameters
Arguments Name Type Description memberM width8 | 16 | 32 | 64 signedboolean
Returns
layoutfunction Starts an empty Layout
Type parameters
Arguments Name Type Description memberM
Returns
listfunction A list of values that share one element adapter.
Type parameters
Arguments Name Type Description memberM elementM adaptercore . Adapter < V , M >
Returns Type Description core . Adapter < { V } , M >
structurefunction function structure < T , S is nupp . Closeable , M is core . Member > ( member : M , fields : const { Field < T , S , M > } , construction : Construction < T , S > , unknown : core . UnknownConsumer < S > ? , additional : core . Members < M , T > ? , deferredConstruction : boolean ? ) : core . Adapter < T , M > A structure: named fields written in order, read in any order, and constructed through an exclusive draft.
Reading calls construction:begin(), applies each field's setter to the draft as the codec meets it, then hands the draft to construction:finish(). A wire field the model does not declare is passed to unknown, which rejects it when nil. additional emits extra members after the declared ones, such as preserved unknown fields.
Type parameters
Arguments
Returns
textfunction A UTF-8 string.
Type parameters
Arguments Name Type Description memberM
Returns Type Description core . Adapter < string , M >
timestampfunction An instant, as a nupp.serde.Timestamp
Type parameters
Arguments Name Type Description memberM
Returns
← Previous nupp.serde Next → nupp.serde.codec