Forms

A form is fixed syntax that builds a step, a text or a piece of UI: s!(…), choice!{…}, t![…], and the UI forms such as column![…] and button!{…}. Each form desugars to ordinary struct expressions, closures and calls of standard library items, which a .kis file may also write by hand.

Forms are not macros. There are no macros in Kagari, and the set of forms is fixed by the language. An unknown form name is a syntax error (E0001).

What steps mean for the story is in Steps; what the UI forms build is in the STD Reference, std::ui. This chapter gives their exact syntax and desugaring.

Where forms are allowed

• Forms are allowed only in .kix files. A form in a .kis file is E0001.
• A form is an expression: a name, !, then one of (, [ or {. a != b is never a form.
• Desugaring happens before name resolution, and the desugared code always names the standard library items (std::narrative::push_step, std::ui::button, …), even where a local item has the same name.
• After desugaring, the ordinary rules apply: a step runs only in a scene (E3002), UI functions are fn code (call rules), and so on.

General syntax

form       = name "!" "(" entries ")"
           | name "!" "[" entries "]"
           | name "!" "{" entries "}"
           | "t" "!" "[" { text-item } "]"
entries    = [ entry { "," entry } [ "," ] ]
entry      = attribute | arm | expression
attribute  = name "=" expression
arm        = expression [ "if" expression ] "=>" expression
text-item  = string | ruby | effect | "{" expression "}"
ruby       = "[" string "]" "(" string { "|" string } ")"
effect     = "!" "[" ( string | ruby ) "]" "(" expression ")"

The delimiter tells what a form accepts:

Every form has exactly one delimiter. These are syntax errors (E0001):

• the wrong delimiter (`s!` is written `s!(…)`);
• an attribute in a […] form, an attribute after an element, a duplicate attribute, an attribute the form does not know, a missing required attribute;
• the wrong number of elements;
• an arm (… => …) anywhere but in choice!;
• a comma between the items of t![…], which are juxtaposed.

key = expression is an attribute only directly inside a form; anywhere else = is assignment. Entries are separated by commas, and a trailing comma is allowed.

A brace form (choice!{…}, button!{…}, …) at the start of a statement is block-like: it needs no ; after it. s!(…) and the other forms need one, like any expression statement.

Summary of the forms

s!(…)

s!(t!["It was the last day of summer."]);
s!(who = "Azusa", render = azusa_smiles, t!["Did you forget again?"]);
s!(render = cg_fireworks);
s!(who = "Azusa", history = t!["(Azusa names the date)"], t!["Today is day " {DAY} "."]);

All attributes are optional. The element, if any, must be written as a t![…] form (E0001 otherwise), and it becomes the field text. To show a Text held in a constant, interpolate it: t![{GREETING}].

Each field is Some(value) when the attribute or element is present and None otherwise, and the whole form is a call of push_step, so

s!(who = "Azusa", render = azusa_smiles, t!["Did you forget again?"]);

means

push_step(Say {
    who: Some("Azusa"),
    voice: None,
    render: Some(azusa_smiles),
    text: Some("Did you forget again?"),
    history: None,
});

(t!["Did you forget again?"] is the string itself; see t![…].) The expression has type ().

choice!{…}

enum Confess { Yes, No }

let answer = choice!{
    id = "confess",
    render = azusa_waits,
    t!["Tell her the truth"] => Confess::Yes,
    t!["Say nothing"] if !MET_MIO => Confess::No,
};

Every element is an arm: t![…] => Variant or t![…] if guard => Variant.

• The text must be written as a t![…] form; a plain string literal is E0001.
• The guard is a bool expression, evaluated when the choice is entered. An arm whose guard is false is not offered.
• The value must be a fieldless variant of an enum (E3020). All arms use variants of one enum (E2001 otherwise), and each variant at most once (E3020). The choice! expression has that enum type.

The form desugars to a Choice with one ChoiceArm per arm, in source order; an arm without a guard has shown: true. The example above means

let answer = push_step(Choice {
    id: "confess",
    render: Some(azusa_waits),
    arms: [
        ChoiceArm { text: "Tell her the truth", shown: true, value: Confess::Yes },
        ChoiceArm { text: "Say nothing", shown: !MET_MIO, value: Confess::No },
    ],
});

A choice that can be reached with every arm hidden is E5003. Guards, disabled arms and stable choice ids are explained in Steps.

t![…]

t!["これは" ["数多"]("あまた") "の" ["漢字"]("かん"|"じ") !["赤い"](color_text(rgb(200, 0, 0))) "花。"]

t![…] builds a Text. Its items are juxtaposed, without commas, and are concatenated exactly: no whitespace is added or removed between them.

The whole form is

• "" when it has no items;
• the single item’s expression when it has one item, so t!["Mio"] is "Mio" and t![{DAY}] is to_text(DAY);
• concat([…]) of the items otherwise.

t!["Day " {DAY} ": " !["the festival"](emphasis())]

means

concat(["Day ", to_text(DAY), ": ", effect("the festival", emphasis())])

ruby, mono_ruby, effect, concat and to_text are const fn builtins of std::narrative::text.

Strings

A string item is a string literal with the escapes \n (line break), \r, \t, \\, \", \0 and \u{…}. A line break typed inside the quotes is part of the text as well. A string literal has type Text anywhere, so an attribute such as who = "Mio" needs no t!.

Ruby

[base](readings) puts ruby over base, which is one string literal.

• One reading: group ruby over the whole base.
• Several readings separated by |: mono ruby, one reading per character of the base. The number of readings must equal the number of characters (E3021).

Text effects

![base](effect) shows base, a string literal or a ruby item, with a text effect. effect is an expression of type TextEffect and must be a constant expression (E3022), so a message is still a constant of its step. Effects combine with .and(…); fields set on the right win. Interpolation is not allowed inside the base.

t!["Tell me about " !["you"](emphasis()) "."]
t!["It was " !["here"](dots().and(color_text(rgb(200, 0, 0)))) "."]

The effects (color_text, bold, italic, size, font, outline, shadow, emphasis, dots, speed, speed_scale, reveal_instant, pause, click_wait, mark) are listed in the STD Reference, std::narrative::text.

Pauses and marks

A cue is an effect that acts on the reveal of the text rather than on its look. Its base is usually the empty string:

s!(who = "Mio", render = mio_startled, t!["Wait" ![""](pause(ms(500)).and(mark(1))) "—what?"]);
s!(t!["Read slowly." ![""](click_wait()) "\nThen go on."]);

A mark number used twice in one text is E4010. The exact reveal, pause and mark rules are in the STD Reference, std::narrative::text.

Interpolation

{expr} inserts the value of expr as text. The type of expr must implement the standard trait ToText (E2026 otherwise): Text, String, Int<lo, hi>, the Rust integers, Rat and Decimal. In a pushdown fn, interpolating a finite runtime value such as a story variable is a call of the const fn to_text with a finite argument, which the compiler tabulates.

UI forms

column![
    text!(t!["Text speed: " {speed()}]),
    slider!{value = speed(), on_change = |v| set_speed(v)},
    button!{on_click = || nav::back(), t!["Back"]},
]

The UI forms build Element values of std::ui in fn code. They desugar by these rules:

• Elements. Each element e becomes the closure || e. In column!, row!, button! and toggle!, an element that is written as a t![…] form becomes || ui::label(t![…]).
• Reactive attributes. Every attribute whose name does not start with on_ becomes a closure: key: || expr when the attribute is required, key: Some(|| expr) when it is optional. The UI re-runs the closure when a signal it reads changes.
• Handler attributes. An on_* attribute is passed as written: key: Some(expr).
• Absent optional attributes become None.
• column!, row! and layer! pass the array of element closures directly. The other forms pass a props struct whose fields are the attributes, in the order declared in std::ui, plus a field for the elements.

So

button!{on_click = || nav::back(), t!["Back"]}

means

std::ui::button(std::ui::ButtonProps {
    on_click: Some(|| nav::back()),
    disabled: None,
    style: None,
    children: [|| std::ui::label("Back")],
})

and

slider!{value = speed(), on_change = |v| set_speed(v)}

means

std::ui::slider(std::ui::SliderProps {
    value: || speed(),
    on_change: Some(|v| set_speed(v)),
    step: None,
    disabled: None,
    style: None,
})

A slider’s range is the range of its value’s Int type; there are no min or max attributes.

Writing forms by hand

A .kis file, or a .kix file that prefers it, writes the desugared code directly. Every target is an ordinary public item: push_step, Say, Choice and ChoiceArm are in the prelude, the text builtins are in std::narrative::text, and the UI functions and props structs are in std::ui. Hand-written code gets the same checks as the forms: a hand-written Choice must use a string literal id (E3019) and an array literal of ChoiceArm { … } records with fieldless variants (E3020).