WEP: Template Format Specifiers

Context

Template strings in Wado support interpolation with format specifiers: `value: {x:spec}`. Different languages provide different sets of format specifiers:

Language Comparison

The Problem with General Format (g/G)

C's %g format specifier automatically switches between fixed-point and exponential notation based on magnitude. While convenient, this has been identified as a "negative legacy" from C:

• Unpredictable output: Values unexpectedly switch to scientific notation
• Production issues: Common source of bugs when output format matters
• User confusion: Developers often encounter this multiple times

Rust's design decision was to exclude g/G format specifiers entirely. Instead:

1. RFC #844 (2015): Community requested %g equivalent for prettier float output
2. RFC #2729: Proposed {:g?} debug formatter
3. Final solution (Rust 1.58): Modified {:?} (Debug) to automatically use exponential notation for very large/small floats, without adding a separate format specifier

This avoided the unpredictability of g while still providing readable output for debugging.

Decision

Wado will use Rust-compatible format specifiers, following Rust's philosophy of explicit, predictable formatting.

Format Specifier Syntax

`{expr}`           // Default (Display trait)
`{expr:spec}`      // With format specifier

Where spec follows Rust's format specification mini-language.

Supported Format Types

Notes:

• No g/G format specifiers. Users must explicitly choose between default {} and exponential {:e}/{:E}.
• No p (Pointer) format specifier. Wado does not have pointer types.
• Negative signed integers format as the two's complement bit pattern of the value's own width under b/o/x/X (e.g. {-1 as i32:x} → "ffffffff"), matching Rust.

Format Parameters

Format specifiers can include additional parameters in this order:

{expr:[[fill]align][sign][#][0][width][.precision]type}

Alignment and Width

Precision

For floating-point numbers, precision specifies decimal places:

println(`{3.14159:.2}`);    // => "3.14"
println(`{100.0:.4}`);      // => "100.0000"
println(`{1.23e5:.1e}`);    // => "1.2e5"

For integers in exponential notation, precision specifies significant digits:

println(`{12345:.2e}`);     // => "1.23e4"

For strings, precision specifies the maximum length in characters, matching Rust's {:.N}. Display truncates silently; Inspect (:?) truncates to the same characters and appends a ... marker (outside the quotes) when truncation actually happened. The marker does not count toward the precision:

let s = "hello world";
println(`{s:.5}`);          // => "hello"
println(`{s:.5?}`);         // => "hello"...   (note: with surrounding quotes)
println(`{s:.20}`);         // => "hello world" (precision >= length: unchanged)

For arrays, precision specifies the maximum number of elements. Display truncates silently; Inspect appends , ... when elements are dropped:

let a: List<i32> = [1, 2, 3, 4, 5];
println(`{a:.3?}`);         // => "[1, 2, 3, ...]"
println(`{a:.3}`);          // => "[1, 2, 3]"

The truncation point is uniform across collection-like types: precision caps the number of rendered items (characters for String, elements for List). A shared Formatter flows into nested element rendering, so an explicit precision also bounds elements inside collections (e.g. long String elements of an List). Tuples and structs are fixed-size, so their own arity is never capped, but their String / List fields still honor the active precision.

Default Inspect cap and the precision sentinels

Inspect / InspectAlt (:? / :#?) of a String or List apply a default length cap of DEFAULT_SEQ_LIMIT (256 items) even when no precision is given, so debug output — including power-assert operand dumps — stays readable. Display never applies the default cap: a plain {s} renders the full value.

To make this work, Formatter.precision uses two negative sentinels instead of a single "unspecified" value:

• PRECISION_DEFAULT (-2): no precision in the spec. Sequence Inspect falls back to DEFAULT_SEQ_LIMIT; every other type (floats, ints, Display) treats it the same as unset (its precision >= 0 check stays false).
• PRECISION_INFINITE (-1): render with no cap; sequence Inspect skips truncation. There is no surface syntax for it yet (the .N grammar cannot produce a negative value), so it is currently reachable only by constructing a Formatter directly — see the TODO in format.wado.

This keeps precision's meaning intact per type (decimal places for floats, max length for sequences) while letting :? cap sequences by default without affecting non-sequence operands.

Sign

Alternate Form

The # flag provides alternate representations:

Complete Examples

// Basic formatting
let x = 42;
println(`{x}`);          // => "42"
println(`{x:?}`);        // => "42"
println(`{x:b}`);        // => "101010"
println(`{x:o}`);        // => "52"
println(`{x:x}`);        // => "2a"
println(`{x:X}`);        // => "2A"
println(`{x:#x}`);       // => "0x2a"

// Width and alignment
println(`{x:5}`);        // => "   42"
println(`{x:<5}`);       // => "42   "
println(`{x:^5}`);       // => " 42  "
println(`{x:>5}`);       // => "   42"
println(`{x:05}`);       // => "00042"

// Floating-point
let pi = 3.14159;
println(`{pi}`);         // => "3.14159"
println(`{pi:.2}`);      // => "3.14"
println(`{pi:+.2}`);     // => "+3.14"
println(`{pi:8.2}`);     // => "    3.14" (width 8, precision 2)
println(`{pi:e}`);       // => "3.14159e0"
println(`{pi:.2e}`);     // => "3.14e0"
println(`{pi:E}`);       // => "3.14159E0"

// Structs
let p = Point { x: 10, y: 20 };
println(`{p}`);          // => "(10, 20)" (if Display implemented)
println(`{p:?}`);        // => "Point { x: 10, y: 20 }" (inspect)

// Arbitrary expressions (Wado extension)
println(`{x + 1}`);      // => "43"
println(`{x * 2:x}`);    // => "54" (84 in hex)
println(`{p.x + p.y}`);  // => "30"
println(`{arr.len()}`);  // => "5"

Interaction with Type Stringification

This WEP extends WEP: Type Stringification:

1. {expr}: Uses Display trait, falls back to inspect
2. {expr:?}: Always uses inspect (compiler intrinsic)
3. {expr:spec}: Uses appropriate trait for spec (e.g., Binary, LowerHex, LowerExp)

Resolution order for {expr:spec}:

1. If type does not support the format trait → compile error
2. Apply format parameters (width, precision, alignment)
3. Return formatted String

Key differences from Rust:

1. Arbitrary expressions: Wado allows any expression in {expr}, while Rust only allows simple value expressions (no method calls, operators, etc. without parentheses)
2. Inspect fallback: Wado provides inspect as a fallback for {} and {:?}, while Rust requires explicit trait implementations
3. Other format specifiers: Format specifiers like {:x} still require the type to support that trait (or be a primitive)
4. No :p specifier: Wado excludes :p since it has no pointer types

Syntax disambiguation: The parser distinguishes :: (scope resolution/turbofish) from : (format specifier) by lookahead:

• {foo::bar} - :: is part of the expression
• {foo::<T>} - ::< is turbofish syntax
• {foo:x} - : starts format specifier

Consequences

Positive

1. Rust familiarity: Developers familiar with Rust can immediately use Wado's format specifiers (except :p)
2. Predictable output: No surprise switches to exponential notation
3. Explicit intent: Developers explicitly choose the format they want
4. Type safety: Format specifiers that don't apply to a type cause compile errors
5. Extensible: Supports {:#?} for pretty-print and other Rust-compatible specifiers
6. Language coherence: Excluding :p aligns with Wado's lack of pointer types

Negative

1. No convenience format: Developers must choose between {} and {:e} for floats
   • Mitigation: Default {} works well for most cases; {:e} is explicit for scientific notation
2. Learning curve: Developers from Python/Go may need to learn Rust's format syntax
   • Mitigation: Rust's format syntax is well-documented and widely used
3. Implementation complexity: Requires implementing all Rust format traits
   • Mitigation: Can implement incrementally, starting with most common specifiers

Implemented Extensions

1. Pretty-print: {:#?} for indented multi-line debug output via InspectAlt trait

Future Extensions

Following Rust's ecosystem, we can add:

1. Dynamic width and precision: Allow runtime values using nested {} syntax
   • Syntax: {value:{width}.{precision}} (Python-style)
   • Rationale: Python's nested {} approach is more consistent with Wado's "arbitrary expressions" philosophy than Rust's $ syntax, which requires argument lists. Variables in the current scope can be referenced directly.
   • Example: let w = 8; let p = 2; println(\{pi:{w}.{p}}`);→" 3.14"`

Migration from Other Languages

For developers coming from other languages:

References

• Rust std::fmt documentation
• RFC #844: Extend fmt to add %g analogous to printf
• RFC #2729: General floating point formatting in Debug
• Rust PR #86479: Automatic exponential formatting in Debug
• WEP: Type Stringification
• WEP: Format Traits
• Go fmt package
• Python f-strings