std::debug
The Debug interface: a value as a developer reads it, what dbg,
io.inspect and an assertion’s values: row write. Every value has a
Debug form; Display (std::display) is the user-facing one.
Import with import std::debug.
Exports
Section titled “Exports”Interfaces
How built-in values render
Section titled “How built-in values render”| Type | Display | Debug |
|---|---|---|
Int, Float, Bool | numeric / variant form: 42, 3.14, True / False | identical |
Decimal | its digits at its scale: 1.50 | its literal: 1.50d |
Unit | no Display impl; rendering one is a compile error | Unit |
String | raw text, no quotes | its literal, String.to_literal: "..." with \n, \r, \t, \\, \" and \${ escaped and \u{...} for any other character that is not printable |
Infallible | uninhabited; can never be called | none |
Int, Float and Bool render the same in both, and a Decimal’s
Debug adds its literal’s d. For a String the two differ more. Display
gives the bare text, so "hello ${name}" doesn’t double-quote. Debug
gives the literal, so io.inspect("a\"b") shows the escape;
String.to_literal gives the rules for that literal.
Containers recurse through the same interface as the caller: a container’s Display uses Display on its elements, and its Debug uses Debug. Brackets, braces, parentheses and separators are byte-identical between the two; only the per-element function differs.
| Type | Display | Debug |
|---|---|---|
List<T> | [Display(v1), Display(v2), ...], [] for empty | [Debug(...), ...] |
Vector<T> | Vector[Display(v1), ...], Vector[] for empty | Vector[Debug(...), ...] |
Set<T> | Set[Display(v1), ...], Set[] for empty | Set[Debug(...), ...] |
Map<K, V> | {Display(k) => Display(v), ...}, {} for empty | {Debug(...) => Debug(...), ...} |
Maybe<T> | Some(Display(v)), None | Some(Debug(v)), None |
Result<T, E> | Ok(Display(v)), Err(Display(e)) | Ok(Debug(v)), Err(Debug(e)) |
Range<T> | Debug(start)..Debug(end), Debug(start)..=Debug(end), Debug(start).. for unbounded integer ranges | identical |
Tuple (...) | (Display(a), Display(b), ...) | (Debug(a), Debug(b), ...) |
Anon struct {f: V, ...} | {f: Display(v), ...} | {f: Debug(v), ...} |
Tuples and anonymous structs are syntactic intrinsics with no named type to attach an impl to; they get language-level rendering, as their literal syntax is privileged. Every other built-in type gets a Nomi-side impl in the standard library.
Container impls require their elements to implement the corresponding
interface: ${[some_fn]} is an error because functions have no Display
impl. Each container impl states the constraint as a bound
(impl Display for List<T> where T: Display), which its body needs to
render an element, so List<Foo> is Display exactly when Foo is; a
missing element impl is reported as the element’s
(no impl of `Display` for `Foo` ).
For Maybe and Result, the variant constructor is always rendered
(Some(...), None, Ok(...), Err(...)), never unwrapped. Display
keeps the variant: the user-facing form of Maybe.None is "None", not
the empty string.
interface Debug
Section titled “interface Debug”interface Debug fn inspect(value: self) -> String end
Protocol for a developer-facing String form of a value.
An impl writes text that looks like the value’s literal: Nomi source that builds the value again where that is possible, and a faithful rendering of its structure where it is not.
io.inspect, dbg, debug logs and Debug.inspect(value) write it.
Text for a user is Display’s: string interpolation "${value}" calls
Display, not Debug.
dbg expr is a language form, not a member of this interface. It evaluates
expr, prints the source location, source text, and Debug.inspect output,
then returns the original value. The LSP reports every dbg as a warning
because it is for development only. io.inspect(value) is the function
for printing the Debug form as part of a program’s behavior.
Debug’s function is inspect and Display’s is to_string, so a type
that implements both has two functions with two names.
For a String the two differ: Display.to_string("hello") is hello,
and Debug.inspect("hello") is "hello", in quotes as the literal is.
For Int, Float, and Bool, Debug.inspect is the same text as
Display.to_string, because the literal is the user-facing form.
Every value has a Debug form, with no derive and no impl. The
compiler writes a structural Debug for any declared type that does not
supply one, so an impl Debug is only for changing how a type renders.
Precedence, highest first: a hand-written impl Debug, then derive Debug, then the structural impl the compiler writes.
An opaque type inspects as its name only, <opaque T>, since a
structural form would show the internals opaque hides; write an impl Debug for T in its file to show more. A host type with no impl
inspects as its bare name (True as True, Unit as Unit). Values
with no declaration have placeholders: <function>, <task>,
<channel>, <arm> and <iter>.
Debug.inspect
Section titled “Debug.inspect”fn inspect(value: self) -> String
interface Debug