Heap-proportional structural previews for human and model observations.
Unlike PtcRunner.Lisp.Format, this module is deliberately bounded. Its
default pass samples collections and preserves sibling shape while enforcing
depth, node, string, character, and UTF-8 byte ceilings. When the shape pass
reports truncation from implicit ceilings, one bounded greedy pass may lift
node and string ceilings to the output budget and item and depth ceilings to
larger internal traversal bounds. It replaces the preview with an exact
rendering only if every part fits those bounds. Otherwise the original
shape-preserving preview wins.
In the shape pass, map keys are exempt from the per-entry character share: a key renders against the whole key ceiling at every nesting depth, and only the remainder is charged to its value. That ceiling is 67 rendered characters, which holds 64 plain ones plus the delimiters and an elision mark, and fewer where escaping expands them. A truncated value stays identifiable from what survives while a truncated key does not, so a map that cannot fit shows fewer entries with intact names rather than every name abbreviated, and a key too long for the ceiling keeps an elided prefix rather than an opaque marker. The exact pass has no key ceiling, because it renders only when the complete value fits the output budget.
Neither pass recursively sanitizes a complete value or materializes a complete collection before applying the traversal ceilings.
Preview results are presentation metadata only. Callers must never turn a preview failure into an evaluation failure or use a preview as the retained continuation value.
Summary
Functions
Renders a preview with a bounded visible truncation notice.
Types
@type option() :: {:max_chars, pos_integer()} | {:max_bytes, pos_integer()} | {:max_items, pos_integer()} | {:max_depth, non_neg_integer()} | {:max_nodes, pos_integer()} | {:max_string_chars, pos_integer()}
Functions
@spec render(term(), [option()]) :: PtcRunner.Lisp.ValuePreview.Result.t()
@spec render_with_notice(term(), [option()]) :: PtcRunner.Lisp.ValuePreview.Result.t()
Renders a preview with a bounded visible truncation notice.