ShellRender
ShellRender: the combinators march --shell renders a result with.
The shell (bin/shell_cmd.ml, bin/shell_render_gen.ml) compiles each input into a fragment that returns its result as a String. It generates, from the result's static type, a renderer built from these functions: one per record, tuple and ADT the type reaches, each passing the element limit down. The rules (R5.7 of specs/plans/2026-09-28-observe-recon-shell-plan.md):
- A collection (List, Array, Map, Set, and the other stdlib containers:
HashMap, OrderedMap, SortedSet, Deque, Queue, RRB.Vec, NativeArray) shows
at most `limit` elements and then `… n more`. A string shows at most `limit` characters (codepoints),
quoted and escaped, then `… n more chars`. The limit applies at every
depth; `limit <= 0` means no limit.- Records, tuples and constructors render field by field, in derive Show's
form.- A hand-written Show impl's string is cut at 16 KiB (
show_cut).
Functions
An anonymous record: { a: 1, b: 2 }. Each field arrives rendered as a: 1. No fields renders as {}.
Examples
march> ShellRender.anon_record(["a: 1", "b: 2"])
"{ a: 1, b: 2 }"
march> ShellRender.anon_record([])
"{}"An Array: Array[1, 2, … n more], as list.
Examples
march> ShellRender.array(Array.from_list([1, 2, 3]), 2, int_to_string) == "Array[1, 2, … 1 more]"
trueA constructor with arguments: Name(a, b). The arguments arrive already rendered. An empty list still prints the parentheses (Name()); a nullary constructor is rendered by its bare name instead.
Examples
march> ShellRender.ctor("Pair", ["1", "\"a\""])
"Pair(1, \"a\")"A Deque: Deque[1, 2, … n more], as list, front to back.
Examples
march> ShellRender.deque(Deque.from_list([1, 2, 3]), 0, int_to_string)
"Deque[1, 2, 3]"A HashMap: HashMap{k => v, … n more}, as map, in the map's hash order.
Examples
march> ShellRender.hash_map(HashMap.from_list([(1, "a")]), 0, int_to_string, ShellRender.quote)
"HashMap{1 => \"a\"}"A list, each element rendered by f: [1, 2, … 98 more] at most limit elements (all when limit <= 0). f is called only on the elements shown.
Examples
march> ShellRender.list([1, 2, 3, 4], 2, int_to_string) == "[1, 2, … 2 more]"
true
march> ShellRender.list([1, 2, 3], 0, int_to_string)
"[1, 2, 3]"
march> ShellRender.list([], 2, int_to_string)
"[]"A Map: Map{k => v, … n more}, keys by fk and values by fv, at most limit entries, in the map's iteration order.
Examples
march> ShellRender.map(Map.from_list_int([(1, "a"), (2, "b")]), 1, int_to_string, ShellRender.quote) == "Map{1 => \"a\", … 1 more}"
trueA NativeArray, given as the list of its elements (its family's to_list_*): NativeArray[1, 2, … n more], as list.
Examples
march> ShellRender.native_array([1, 2, 3], 2, int_to_string) == "NativeArray[1, 2, … 1 more]"
trueAn OrderedMap: OrderedMap{k => v, … n more}, as map, in key order.
Examples
march> ShellRender.ordered_map(OrderedMap.from_list([(2, "b"), (1, "a")], fn (a, b) -> a - b), 0, int_to_string, ShellRender.quote)
"OrderedMap{1 => \"a\", 2 => \"b\"}"A Queue: Queue[1, 2, … n more], as list, front to back.
Examples
march> ShellRender.queue(Queue.from_list([1, 2, 3]), 1, int_to_string) == "Queue[1, … 2 more]"
trues as a March string literal: quoted, with double quotes, backslashes, control bytes and an interpolation opener escaped. \n, \r and \t use their short escapes, other control bytes and DEL become \xNN, and $ is escaped only when followed by {. Bytes >= 128 pass through.
Examples
march> ShellRender.quote("hi")
"\"hi\""
march> ShellRender.quote("a\tb")
"\"a\\tb\""s unquoted, cut after limit codepoints with … n more chars (limit <= 0 keeps all of it): the shell prints a string at the top of a result this way, and the payload of a top-level one-field constructor (Ok("…"), as Actor.inspect_state returns its already rendered state).
Examples
march> ShellRender.raw("hello", 3) == "hel… 2 more chars"
true
march> ShellRender.raw("hello", 10)
"hello"A named record, in derive Show's form: Name { a = 1, b = 2 }. Each field arrives rendered as a = 1.
Examples
march> ShellRender.record("Point", ["x = 1", "y = 2"])
"Point { x = 1, y = 2 }"An RRB vector: RRB.Vec[1, 2, … n more], as list, in index order.
Examples
march> ShellRender.rrb_vec(RRB.from_list([1, 2, 3]), 0, int_to_string)
"RRB.Vec[1, 2, 3]"A Set: Set{1, 2, … n more}, as list, in the set's iteration order.
Examples
march> ShellRender.set(Set.from_list([3, 1, 2], fn a -> fn b -> a < b), 0, int_to_string)
"Set{1, 2, 3}"The most bytes show_cut keeps of a hand-written Show impl's string: 16 KiB.
Examples
march> ShellRender.show_cap()
16384A hand-written Show impl's string, cut at 16 KiB (on a codepoint boundary) with … (n more bytes); it cannot take an element limit. A string of at most show_cap() bytes is returned unchanged.
Examples
march> ShellRender.show_cut("short")
"short"A SortedSet: SortedSet{1, 2, … n more}, as list, in order.
Examples
march> ShellRender.sorted_set(SortedSet.from_list([3, 1, 2], fn (a, b) -> a - b), 2, int_to_string) == "SortedSet{1, 2, … 1 more}"
trues quoted (see quote), cut after limit codepoints with … n more chars. limit <= 0 keeps all of it. The cut counts codepoints but n is computed from the grapheme count, so the two can disagree for text with combining marks.
Examples
march> ShellRender.string("hello", 0)
"\"hello\""
march> ShellRender.string("hello", 3) == "\"hel\"… 2 more chars"
trueA tuple: (a, b), its parts already rendered.
Examples
march> ShellRender.tuple(["1", "true"])
"(1, true)"