# `nupp.serde.debug` Debug rendering turns any bound value into readable text for logs, assertions, and error messages. See [nupp.derive](../../../../modules/nupp/derive/index.html#debug) for the `Debug` derive and its field annotations. ```nupp 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 = }') ``` The text is for people, not for reading back: it has no decoder and its format may change. [`binding`](#nupp.serde.debug.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. ## Types ### `Renderer` _interface_ ```nupp 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 | Name | Kind | Description | | --- | --- | --- | | [`render`](#nupp.serde.debug.Renderer.render) | method | Renders a value. | | [`write`](#nupp.serde.debug.Renderer.write) | method | Appends a rendered value. | | [`clear`](#nupp.serde.debug.Renderer.clear) | method | Forgets every binding's selections. | | [`cachedBindings`](#nupp.serde.debug.Renderer.cachedBindings) | method | Returns how many bindings have selections retained. | #### `render` _method_ ```nupp render: function(self, selectedBinding: core.Binding, borrows value: T): string ``` Renders a value. See [`render`](#nupp.serde.debug.render). ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `selectedBinding` | `core.Binding\` | | | `borrows value` | `T` | | ##### Returns | Type | Description | | --- | --- | | `string` | | #### `write` _method_ ```nupp write: function(self, selectedBinding: core.Binding, borrows value: T, exclusive buffer: text.Buffer): nil ``` Appends a rendered value. See [`write`](#nupp.serde.debug.write). ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `selectedBinding` | `core.Binding\` | | | `borrows value` | `T` | | | `exclusive buffer` | `text.Buffer` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `clear` _method_ ```nupp clear: function(self): nil ``` Forgets every binding's selections. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `cachedBindings` _method_ ```nupp cachedBindings: function(self): integer ``` Returns how many bindings have selections retained. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | ## Functions ### `binding` _function_ ```nupp function binding(target: Type): core.Binding ``` 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 | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `target` | `Type\` | the record or struct declaration | #### Returns | Type | Description | | --- | --- | | `core.Binding\` | the binding, cached on the declaration | ### `derived` _function_ ```nupp function derived(target: Type, borrows value: unknown): string ``` Renders a value through its declaration's Debug binding. The `Debug` derive forwards to this; call [`render`](#nupp.serde.debug.render) instead. #### Arguments | Name | Type | Description | | --- | --- | --- | | `target` | `Type\` | the declaration | | `borrows value` | `unknown` | the value | #### Returns | Type | Description | | --- | --- | | `string` | the text | ### `render` _function_ ```nupp function render(selectedBinding: core.Binding, borrows value: T): string ``` Renders a value as text. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `selectedBinding` | `core.Binding\` | the value's binding | | `borrows value` | `T` | the value | #### Returns | Type | Description | | --- | --- | | `string` | the text | ### `renderer` _function_ ```nupp function renderer(capacity: integer?): Renderer ``` Makes a [`Renderer`](#nupp.serde.debug.Renderer). #### Arguments | Name | Type | Description | | --- | --- | --- | | `capacity` | `integer?` | the most bindings to retain selections for; nil is 256 | #### Returns | Type | Description | | --- | --- | | `Renderer` | the renderer | #### Raises | Type | Condition | | --- | --- | | `string` | when capacity is not positive | ### `write` _function_ ```nupp function write(selectedBinding: core.Binding, borrows value: T, exclusive buffer: text.Buffer): nil ``` Appends a value's text to a Buffer. ```nupp 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 | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `selectedBinding` | `core.Binding\` | the value's binding | | `borrows value` | `T` | the value | | `exclusive buffer` | `text.Buffer` | the buffer to append to | #### Returns | Type | Description | | --- | --- | | `nil` | |