v0.4.0

#Format

#Format is the one attribute written before a parameter. It marks a char8[..] parameter as a format string, followed by a variadic parameter whose arguments fill its placeholders. When a call passes a string literal for it, the compiler counts the placeholders against the arguments and refuses a mismatch while compiling, rather than leaving it to fail at run time.

format-parameter = "#Format" identifier ":" "char8[..]"

The standard printing functions are declared this way:

pub func PrintLine(#Format format: char8[..], args: &Display...) -> IoError?

A function of your own takes it just as well; the compiler recognizes no package or function by name, only the attribute:

import Io::PrintLine;
import Format::Display;

func Log(level: int, #Format format: char8[..], args: &Display...) {
    PrintLine(format, args...);
}

func Main() -> int {
    Log(1, "{} of {}", 3, 4);       // 3 of 4
    Log(1, "{{}} {:x}", 255);       // {} ff
    return 0;
}

Placeholders

A placeholder is {} or {:spec}; {{ and }} are literal braces and count for nothing. A call whose literal has a different number of placeholders than arguments is an error:

error: format string has 2 placeholders, but 1 argument was provided
  note: format parameter 'format' of 'Log' declared at 'Src/Main.rux':4:32
  help: pass one argument for each '{}' placeholder

Only a literal can be counted. A format held in a variable, a spread argument such as args..., and a spec the formatter itself would reject are left to the formatter's check at run time.

Named placeholders

A placeholder may name the value it writes instead: {name} and {name:spec} name a binding in scope — a local, a parameter, a module constant or variable, or self — or a field path through one, and write it as {} and {:spec} would write the same value passed as an argument:

import Io::PrintLine;

struct Point {
    x: int;
    y: int;
}

func Main() -> int {
    let key = "origin";
    let point = Point { x: 3, y: 4 };
    PrintLine("{key} = ({point.x}, {point.y:>4})");   // origin = (3,    4)
    return 0;
}

The compiler rewrites such a literal into the positional literal and the values its names stand for, so the run-time formatter is unchanged. Only a literal passed for a #Format parameter is read this way; anywhere else "{key}" is plain text. One literal names every placeholder or none, and a literal with named placeholders takes no arguments after it. Only names are allowed in the braces — a call or an operator is passed as an argument to a {} placeholder instead:

error: format string mixes named and positional placeholders
  help: name every placeholder or none
error: format placeholder '{Twice(count)}' must name a binding or a field path

A name that nothing declares is reported where the placeholder writes it.

Rules

MistakeError
no variadic parameter after it'#Format' parameter 'format' must be followed by a variadic parameter
on the variadic parameter itself'#Format' cannot be applied to variadic parameter 'args'
on two parameters'#Format' is already applied to parameter 'a'
on the receiver'#Format' cannot be applied to the receiver 'self'
with an argument'#Format' does not accept arguments
another name before a parameterunknown parameter attribute '#Trim'

A function has at most one format string, and the variadic parameter it counts against must be the last parameter.

See also