Renderingen-US

Experimental through version 1. Version 0 was alpha. This is the first language release: the interface is relatively stable, not frozen. Nothing is promised stable until version 2.

format

Translation status: English reader-locale proof. Term names and code fences follow the en pack; supporting prose may still be English.

Creates a formatted string with § placeholders.

Syntax: \"<template>\"(<args>...)

Category#

format

Examples#

radix/corpus/reference/keyword/scriptum/scriptum.fab (canonical · keyword)#

Creates a formatted string with § placeholders.

# =============================================================================
# format — Creates a formatted string with `§` placeholders.
# =============================================================================
#
# What this teaches:
#   • String template interpolation — `"template § and §"(arg1, arg2)` replaces
#     `§` placeholders with positional arguments
#   • Templates can contain any expression as an argument, not just variables
#
# Common mistakes:
#   • Confusing `format` (template desugaring into function calls) with bare `§` interpolation outside of the template syntax.
#
# See also: read, line
# =============================================================================

# format — string-template interpolation ("§" slots)
#
# "literal § more §"(arg1, arg2)   -- each § replaced by the corresponding arg
#
# GRAMMAR:
#   templateExpr :← stringLit '(' exprList ')'
#
# EXPECTED OUTPUT:
#   Salve greeting, persona notice, and computed sum string.

main {
    let string name ← "Marcus"
    let int aetas ← 30

    # One slot
    let string salutatio ← "Salve, §!"(name)
    print salutatio

    # Multiple slots
    let string notitia ← "§ habet annos §"(name, aetas)
    print notitia

    # With an expression
    let string sum ← "10 + 20 ← §"(10 + 20)
    print sum
}

Expected output:

Salve, Marcus!
Marcus habet annos 30
10 + 20 ← 30

radix/corpus/reference/reject/scriptum/template-arity-reject.fab (supporting · reject)#

A template needs one actual per value slot; too few arguments are refused by name.

# =============================================================================
# format — one actual per value slot
# =============================================================================
#
# What this teaches:
#   • A template application is checked against its slot count before it is
#     lowered: `"§ §"` has two value slots, so it needs two actuals.
#   • The arity defect is reported as `template_application_arity_mismatch`
#     and lowering stops instead of producing a template with unfilled slots.
#
# Common mistakes:
#   • Supplying one argument for a template with two `§` slots.
#
# See also: read, line — and the positive twin `scriptum.fab`.
# =============================================================================

# format arity reject — expected compile failure
#
# This exemplum intentionally fails to compile.

main {
    let string out ← "§ §"("x")
    print out
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/scriptum/template-hole-gap-reject.fab (supporting · reject)#

Numbered holes address positions; a gap in the numbering is refused even when the count matches.

# =============================================================================
# format — numbered holes must be contiguous
# =============================================================================
#
# What this teaches:
#   • `§N` addresses argument N, so `"§0 and §2"` names positions 0 and 2 and
#     leaves position 1 unread.
#   • A gap in the numbering is a gap, not an arity defect: the count may
#     happen to match while a position is still unfilled, and the call is
#     refused as `template_hole_index_gap`.
#
# Common mistakes:
#   • Skipping a number in a numbered template and passing one argument per
#     printed hole, expecting the positions to close up.
#
# See also: read, line — and the positive twin `scriptum.fab`.
# =============================================================================

# format numbered-hole gap reject — expected compile failure
#
# This exemplum intentionally fails to compile.

main {
    let string out ← "§0 and §2"("a", "b", "c")
    print out
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/scriptum/template-mixed-reject.fab (supporting · reject)#

Labeled and positional actuals cannot be mixed in one template application.

# =============================================================================
# format — mixed labeled and positional actuals
# =============================================================================
#
# What this teaches:
#   • One application is either all-labeled (named holes) or all-positional
#     (anonymous `§` holes); the two forms do not mix.
#
# Common mistakes:
#   • Writing a positional argument next to a labeled one in the same call.
#
# See also: format, named-holes, forma
#
# This exemplum intentionally fails to compile.
# =============================================================================

main {
    let string out ← "§{a} §"("x", a: "y")
    print out
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/scriptum/template-type-args-reject.fab (supporting · reject)#

Template application carries no explicit type arguments after the literal.

# =============================================================================
# format — type arguments on a template application
# =============================================================================
#
# What this teaches:
#   • A string-template application is not a generic call: a turbofish between
#     the literal and its argument list is parsed and then refused in lowering.
#
# Common mistakes:
#   • Annotating the result through `<string>` instead of writing the type slot
#     on the binding (`let string s ← "§"("x")`).
#
# See also: format, named-holes, forma
#
# This exemplum intentionally fails to compile.
# =============================================================================

main {
    let string s ← "§"<string>("x")
    print s
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/scriptum/template-unfillable-reject.fab (supporting · reject)#

A named template hole with no matching labeled actual is a lowering error.

# =============================================================================
# format — named hole left unfilled
# =============================================================================
#
# What this teaches:
#   • Every named hole (`§{b}`) must be filled by a labeled actual of the same
#     name; a labeled actual naming no hole is also rejected.
#   • The pinned identity of this exemplum is `unfillable_template_hole`; the
#     stray `extra` label additionally reports `unknown_template_hole_label`.
#
# Common mistakes:
#   • Supplying an unrelated label instead of the one the template names.
#
# See also: format, named-holes, forma
#
# This exemplum intentionally fails to compile.
# =============================================================================

main {
    let string out ← "§{a} §{b}"(a: "x", extra: "y")
    print out
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/scriptum/template-unknown-label-reject.fab (supporting · reject)#

A labeled actual must name a declared hole; an undeclared label is refused by name.

# =============================================================================
# format — a labeled actual must name a declared hole
# =============================================================================
#
# What this teaches:
#   • `§{label}` declares a named hole; a labeled actual `label: value` fills
#     exactly that hole.
#   • An actual whose label names no declared hole is reported as
#     `unknown_template_hole_label` and lowering stops.
#   • The same call also leaves `greet` unfilled, which reports
#     `unfillable_template_hole` alongside; this exemplum pins the unknown
#     label.
#
# Common mistakes:
#   • Passing `other: …` to a template that declares `§{greet}`.
#
# See also: read, line — and the positive twin `scriptum.fab`.
# =============================================================================

# format unknown-label reject — expected compile failure
#
# This exemplum intentionally fails to compile.

main {
    let string out ← "§{greet} world"(other: "salve")
    print out
}

Expected: compilation rejects this example.