Debug interfacev0.1.0

pub interface Debug {
    func WriteDebug(
        writer: &var TextWriter,
        spec: FormatSpec
    ) -> ! FormatError;
}

Debug output is diagnostic, not a serialization format: it may quote, escape, name fields, and show an invalid value by its numeric form where Display would replace it. Nothing promises it can be parsed back.

Requirements

WriteDebug

func WriteDebug(
    writer: &var TextWriter,
    spec: FormatSpec
) -> ! FormatError

Writes this value's inspection text under spec. The same failures WriteDisplay may report, for the same reasons.

Returns: success when the value's complete text was accepted

Source

Implementations

Related

WriteDebugValue

pub func WriteDebugValue(
    writer: &var TextWriter,
    value: Debug,
    spec: FormatSpec
) -> ! FormatError

Writes value under spec through its Debug implementation.

Source

Parameters

Returns: whatever the value's implementation reported

WriteEscaped

pub func WriteEscaped(
    writer: &var TextWriter,
    text: char8[..]
) -> ! FormatError

Writes text with the characters that would be ambiguous or invisible replaced by escapes. The quote and the backslash are escaped because they collide with the quoting around a debug rendering. The C0 and C1 control ranges are escaped because they act on a terminal rather than being read, and a value containing one should say so rather than doing it. \n, \r, \t and \0 get their short forms; every other control becomes \u{XX}. Everything else, including all ordinary non-ASCII text, is written unchanged. Runs of ordinary bytes are written in one call rather than byte by byte, so escaping costs a pass and not a write per character. Reports whatever the writer reported, stopping at the first refusal.

Source

Parameters

Returns: success when the escaped text was accepted

WriteOptionalDebug<T>

pub func WriteOptionalDebug<T: Debug>(
    writer: &var TextWriter,
    value: &T?,
    spec: FormatSpec
) -> ! FormatError

Writes a borrowed optional as Some(value) or none. The optional is borrowed and its payload with it, so this can be called on an optional holding a value that cannot be copied, as many times as wanted, and the optional still holds it afterwards. spec is handed to the payload's own WriteDebug and describes it rather than the wrapper. Reports whatever the writer or the payload's implementation reported, stopping at the first refusal, so a destination that has already refused something is not written to again.

Source

Type parameters

Parameters

Returns: success when the whole rendering was accepted

WriteFallibleDebug<T, E>

pub func WriteFallibleDebug<T: Debug, E: Debug>(
    writer: &var TextWriter,
    value: &(T ! E),
    spec: FormatSpec
) -> ! FormatError

Writes a borrowed fallible as Success(value) or Failure(reason). Both payloads are borrowed, so neither channel is consumed by being shown. The names are the native channel names, so what is written names the case a reader would branch on. spec is handed to whichever payload is present and describes it rather than the wrapper. Reports whatever the writer or the payload's implementation reported, stopping at the first refusal.

Source

Type parameters

Parameters

Returns: success when the whole rendering was accepted

WriteSliceDebug<T>

pub func WriteSliceDebug<T: Debug>(
    writer: &var TextWriter,
    items: T[..],
    spec: FormatSpec
) -> ! FormatError

Writes a borrowed run of elements as [first, second, third]. An empty run is [], which is visible where writing nothing would not be. Elements are separated by a comma and a space, and every element is shown, since a diagnostic that elided part of what it was given would be worse than a long one. The run is borrowed and each element is shown through a borrow of it, so a slice of a move-only element type is shown without disturbing a single one of them. spec is handed to each element unchanged and means whatever that element type makes of it. The brackets and commas are punctuation and are never padded. Reports whatever the writer or an element's implementation reported, stopping at the first refusal rather than continuing through the rest of the run.

Source

Type parameters

Parameters

Returns: success when the whole rendering was accepted