Render

// `PrintLine` formats text and sends it straight to the console. `Render`, from the Format
// package, does the same formatting but hands the text back as a `String`, to be kept, measured,
// passed on or printed later:
//
//     Render(allocator, pattern, values...) -> String ! FormatError
//
// The result is fallible because two things can go wrong. The String needs memory, and the
// pattern itself can be wrong: a spec that does not parse, a spec the value cannot honour, or
// a different number of placeholders than values. A wrong pattern is found before anything is
// written, so a failure never leaves half a rendering behind.
import Allocator::{ Allocator, SystemAllocator };
import Format::Render;
import Io::PrintLine;
import Text::{ FormatError, String };

// Builds a code such as "INV-0042" once, as a value the caller owns.
func InvoiceCode(allocator: Allocator, number: int) -> String ! FormatError {
    return Render(allocator, "INV-{:04}", number);
}

// Reports either outcome of a render. `FormatError` is a variant, so the cases that carry a
// position or counts can be taken apart; the rest print their own description.
func Show(outcome: String ! FormatError) {
    match outcome {
        .Success(text) => PrintLine("rendered  {}", text),
        .Failure(error) => match error {
            .InvalidSpecification(at) => PrintLine("refused   bad spec at byte {}", at),
            .ArgumentCountMismatch(wanted, given) =>
                PrintLine("refused   {} placeholders but {} values", wanted, given),
            else => PrintLine("refused   {}", error)
        }
    }
}

func Main() -> ! FormatError {
    var system = SystemAllocator();
    let allocator: Allocator = system;

    // Each call produces a String that lives on after it, unlike a printed line.
    let first = InvoiceCode(allocator, 7)?;
    let second = InvoiceCode(allocator, 42)?;
    PrintLine("codes     {} and {}, {} bytes each", first, second, first.Length());

    // A pattern that works, then three ways a pattern can be wrong, each refused with its own
    // case. `PrintLine` refuses the same patterns too, but its `IoError` can only say the
    // request was invalid, not where or why.
    Show(Render(allocator, "{} of {}", 3, 10));
    Show(Render(allocator, "[{:>>>}]", 3));
    // The compiler counts the placeholders of a pattern written in the call itself, so
    // `Render(allocator, "{}, {} and {}", 3, 4)` does not build: "format string has 3
    // placeholders, but 2 arguments were provided". A pattern that arrives as a value is
    // counted only when it runs.
    let pattern = "{}, {} and {}";
    Show(Render(allocator, pattern, 3, 4));
    Show(Render(allocator, "{:x}", "text"));
}