nupp.serde.debug

Debug rendering turns any bound value into readable text for logs, assertions, and error messages. See nupp.derive for the Debug derive and its field annotations.

local serde = require("nupp.serde")
local debug = require("nupp.serde.debug")
local record Login
    user: string
    @debug(redact = true)
    password: string
end
assert(debug.render(debug.binding(Login), new Login(user = "ada", password = "x"))
    == 'Login { user = "ada", password = <redacted> }')

The text is for people, not for reading back: it has no decoder and its format may change. binding honours the Debug derive's field annotations and a declaration's own Debug method; any other binding renders through its adapter as written, so a model library's values render without a derive.

Module contents

Types

TypeKindDescription
RendererinterfaceRenders values, keeping what it selected for each binding.

Functions

FunctionKindDescription
bindingfunctionBuilds the binding Debug renders a declaration through.
derivedfunctionRenders a value through its declaration's Debug binding.
renderfunctionRenders a value as text.
rendererfunctionMakes a Renderer.
writefunctionAppends a value's text to a Buffer.

Types#

Rendererinterface#

interface Renderer ...

Renders values, keeping what it selected for each binding.

The module-level functions share one; hold a renderer of your own to bound or clear what it retains.

Members

NameKindDescription
rendermethodRenders a value.
writemethodAppends a rendered value.
clearmethodForgets every binding's selections.
cachedBindingsmethodReturns how many bindings have selections retained.

rendermethod#

render: function<T>(self, selectedBinding: core.Binding<T>, borrows value: T): string

Renders a value. See render.

Arguments
NameTypeDescription
?self
selectedBindingcore.Binding<T>
borrows valueT
Returns
TypeDescription
string

writemethod#

write: function<T>(self, selectedBinding: core.Binding<T>, borrows value: T, exclusive buffer: text.Buffer): nil

Appends a rendered value. See write.

Arguments
NameTypeDescription
?self
selectedBindingcore.Binding<T>
borrows valueT
exclusive buffertext.Buffer
Returns
TypeDescription
nil

clearmethod#

clear: function(self): nil

Forgets every binding's selections.

Arguments
NameTypeDescription
?self
Returns
TypeDescription
nil

cachedBindingsmethod#

cachedBindings: function(self): integer

Returns how many bindings have selections retained.

Arguments
NameTypeDescription
?self
Returns
TypeDescription
integer

Functions#

bindingfunction#

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

Builds the binding Debug renders a declaration through.

Like nupp.serde.binding, with Debug's own selection: skipped and redacted fields are never read, so a field that has no other representation can still be rendered around.

Type parameters

NameDescription
T

Arguments

NameTypeDescription
targetType<T>

the record or struct declaration

Returns

TypeDescription
core.Binding<T>

the binding, cached on the declaration

derivedfunction#

function derived(target: Type<unknown>, borrows value: unknown): string

Renders a value through its declaration's Debug binding. The Debug derive forwards to this; call render instead.

Arguments

NameTypeDescription
targetType<unknown>

the declaration

borrows valueunknown

the value

Returns

TypeDescription
string

the text

renderfunction#

function render<T>(selectedBinding: core.Binding<T>, borrows value: T): string

Renders a value as text.

Type parameters

NameDescription
T

Arguments

NameTypeDescription
selectedBindingcore.Binding<T>

the value's binding

borrows valueT

the value

Returns

TypeDescription
string

the text

rendererfunction#

function renderer(capacity: integer?): Renderer

Makes a Renderer.

Arguments

NameTypeDescription
capacityinteger?

the most bindings to retain selections for; nil is 256

Returns

TypeDescription
Renderer

the renderer

Raises

TypeCondition
string

when capacity is not positive

writefunction#

function write<T>(selectedBinding: core.Binding<T>, borrows value: T, exclusive buffer: text.Buffer): nil

Appends a value's text to a Buffer.

local serde = require("nupp.serde")
local debug = require("nupp.serde.debug")
local struct Vec2
    x: float
    y: float
end
local output = nupp.text.newBuffer()
debug.write(serde.binding(Vec2), new Vec2(1.25, 2.5), output)
assert(output:tostring() == "Vec2 { x = 1.25, y = 2.5 }")

Type parameters

NameDescription
T

Arguments

NameTypeDescription
selectedBindingcore.Binding<T>

the value's binding

borrows valueT

the value

exclusive buffertext.Buffer

the buffer to append to

Returns

TypeDescription
nil