WEP: Template Format Specifiers

Context

A template string interpolates an expression with an optional format specifier: `value: ${x:spec}`. The specifier language decides which formats are expressible, which are silently wrong, and which are rejected.

Wado follows Rust's mini-language. Two of Rust's omissions are kept:

• No g/G (C's adaptive format). Its output switches between fixed-point and exponential by magnitude, so a caller cannot tell from the specifier which one a given value will take.
• No p (pointer). Wado has no pointer types.

Decision

Grammar

interpolation := '${' expression [ ':' spec ] '}'
spec          := [[fill] align] ['+'] ['#'] ['0'] [width] ['.' precision] [type]
align         := '<' | '^' | '>'
type          := 'b' | 'o' | 'x' | 'X' | 'e' | 'E' | 'f' | '?'
width         := digit+
precision     := digit+

Every part of spec is optional; spec itself is not. The grammar is closed — each of these is a compile error:

Rejecting the unknown is what keeps a printf-ism like ${x:08d} from rendering as ${x:08} with the d dropped.

Whitespace around the specifier is trimmed, as it is around the expression: ${ x : 5 } reads as ${x:5}.

fill is any character the interpolation scanner does not read as structure while splitting ${…}: not ', ", `, {, }, nor a / that opens a comment.

The parser separates :: from a specifier : by lookahead:

Format types

A type that does not implement the trait a specifier names is a compile error. Display is not derived for a struct or variant, so ${x} on one without a hand-written impl is rejected and ${x:?} is the debug form. Inspect holds for every type. See WEP: Trait Derivation Policy.

f selects no trait of its own: Display already honours precision, so ${x:.2f} and ${x:.2} render the same. It exists so a float format reads as one.

b/o/x/X render a negative signed integer as the two's complement bit pattern of its own width: ${-1 as i32:x} → ffffffff.

e/E render an integer mantissa with trailing zeros stripped (${1200:e} → 1.2e3), or with precision + 1 digits rounded half to even when a precision is given (${1250:.1e} → 1.2e3, ${1350:.1e} → 1.4e3). A carry moves the exponent up a decade (${99:.0e} → 1e2).

Fill, alignment and width

width is a minimum, counted in characters — not bytes, not display columns:

`${42:5}`        // "   42"    default alignment
`${42:<5}`       // "42   "
`${42:^5}`       // " 42  "    left-biased when the padding is odd
`${42:>5}`       // "   42"
`${42:_>5}`      // "___42"
`${"あい":>6}`    // "    あい"  two characters, six bytes

The default alignment is right for every type. A fill character of any width pads by whole characters.

Sign

+ renders a sign on a non-negative number; without it only a negative number carries one. It has no effect on a non-numeric value.

`${42:+}`        // "+42"
`${-42:+}`       // "-42"

Zero padding

0 is a flag, not a width digit: ${x:0.2f} is zero-padding plus a precision. Padding goes after the sign and any radix prefix, and wins over an explicit fill and alignment:

`${42:05}`       // "00042"
`${-42:08}`      // "-0000042"
`${-42:*<08}`    // "-0000042"
`${42:#08x}`     // "0x00002a"
`${-1200.0:012e}` // "-0000001.2e3"

Alternate form

# sets Formatter.alternate; it selects no trait. Each implementation reads the flag, or ignores it:

${x:#X} prefixes 0x, not 0X — the flag changes the prefix, the type character changes the digits.

A hand-written impl Display may branch on f.alternate. Every primitive ignores it.

Precision

precision means something different per type, as it does in Rust:

Truncation is silent under Display. Inspect marks it: a String gets a ... after the closing quote, a sequence a , ... in place of the dropped elements. The marker does not count toward the precision.

let s = "hello world";
`${s:.5}`        // hello
`${s:.5?}`       // "hello"...
`${s:.20}`       // hello world   (precision >= length: unchanged)

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

One Formatter is shared with the elements a container renders, so precision and width both reach them. A tuple or struct never caps its own arity, but its String and sequence fields honour the active precision, and ${a:6?} pads each element rather than the collection.

The default sequence cap

Inspect of a String or a sequence caps its length at DEFAULT_SEQ_LIMIT (256) even with no precision in the spec, so debug output — power-assert operand dumps included — stays readable. Display never applies the cap.

Formatter.precision therefore distinguishes three states, two of them negative sentinels:

PRECISION_INFINITE has no surface syntax — .N cannot write a negative — so it is reachable only by building a Formatter directly.

Interpolated expression

The expression before : is arbitrary, where Rust's is a name or an index:

`${x + 1}`
`${x * 2:x}`
`${p.x + p.y}`
`${arr.len()}`

Consequences

Choosing between ${x} and ${x:e} is the caller's, on every float. That is the cost of dropping g: the specifier names the notation, so the output shape does not depend on the value.

A specifier that does not apply is a compile error rather than a rendering, so adding a format trait to a type is a source-compatible change while removing one is not.

Known gaps

• [ ] Dynamic width and precision: the grammar takes literal digits, so neither can be computed. Rust's width$ form names argument-list positions Wado does not have. format_spec holds the spec as text, not as anything that could carry an expression.
• [ ] A parameter with no meaning for its operand is dropped rather than rejected, against the closed grammar's intent: precision on an integer, + on a String, # on e/E. Only the type checker knows which combination is meaningless, so the check belongs in template synthesis.
• [ ] 0 pads a non-numeric value with zeros (${true:08} → 0000true), and every type defaults to right alignment. Rust ignores the flag outside numbers and defaults a non-numeric value to left. Formatter carries no "this operand is a number" fact to decide with.

References

• WEP: Format Traits
• WEP: Inspect (Debug Output)
• WEP: Trait Derivation Policy
• WEP: Type Stringification
• Rust std::fmt