blue_lang_syntax/
forms.rs

1//! The surface forms, one row each: how a form is written, the tatara-lisp
2//! tree it lowers to, and one line on what it means.
3//!
4//! This is the table `blue reference` prints as the grammar card. A reference
5//! written by hand next to a parser drifts the first time the parser changes;
6//! here every row's `example` is parsed by the real parser in
7//! `every_form_lowers_as_its_row_says`, and the tree must be exactly
8//! `lowers_to`. So a row that stops being true is a red build, not a stale
9//! document.
10//!
11//! Operators live in [`crate::parse::INFIX`] and reserved words in
12//! [`crate::parse::SURFACE_KEYWORDS`] / [`crate::parse::BLOCK_KEYWORDS`],
13//! each with its own line; this table holds the forms that are neither.
14
15/// One surface form.
16#[derive(Clone, Copy, Debug)]
17pub struct Form {
18    /// The form as an author writes it. Parsed by the gate.
19    pub example: &'static str,
20    /// The tree `example` parses to, as `Sexp`'s `Display` prints it.
21    pub lowers_to: &'static str,
22    /// One line for a reader.
23    pub doc: &'static str,
24}
25
26/// Every surface form that is not an operator or a keyword.
27pub const FORMS: &[Form] = &[
28    Form {
29        example: "42",
30        lowers_to: "42",
31        doc: "An Int. Six or more digits are grouped by threes, 1_000_000; fewer are not (B0033).",
32    },
33    Form {
34        example: "3.5",
35        lowers_to: "3.5",
36        doc: "A Float.",
37    },
38    Form {
39        example: "\"text\"",
40        lowers_to: "\"text\"",
41        doc: "A string. Escapes: \\n, \\t, \\\", \\\\, \\u{1b}; a character a reader cannot see is always escaped (B0033).",
42    },
43    Form {
44        example: "\"n = #{n}!\"",
45        lowers_to: "(concat (concat \"n = \" n) \"!\")",
46        doc: "Interpolation: any expression inside #{…}, rendered with to_s. A literal that must contain #{ is built with concat(\"#\", \"{\").",
47    },
48    Form {
49        example: ":done",
50        lowers_to: ":done",
51        doc: "A keyword: a name as a value. It may not end in ? or !.",
52    },
53    Form {
54        example: "[1, \"a\"]",
55        lowers_to: "(list 1 \"a\")",
56        doc: "A list. Indexing is nth(i, xs); blue has no xs[i].",
57    },
58    Form {
59        example: "{a: 1, \"k\" => 2}",
60        lowers_to: "(hash-map :a 1 \"k\" 2)",
61        doc: "A map. `a:` is the keyword key :a; `=>` takes any key. Read with get(m, k), extend with assoc(m, k, v).",
62    },
63    Form {
64        example: "{a:, b:}",
65        lowers_to: "(hash-map :a a :b b)",
66        doc: "A map whose values are the variables of the same names: `{a:}` is `{a: a}`. Mix it with `{a:, n: 1}`.",
67    },
68    Form {
69        example: "x = 5",
70        lowers_to: "(define x 5)",
71        doc: "A binding, only as a statement. There is no `let`; a binding lasts to the end of its body.",
72    },
73    Form {
74        example: "f(x, y)",
75        lowers_to: "(f x y)",
76        doc: "A call. This is the one form the formatter writes, except for a function that takes no parameters: that is called by its bare name, now_ms, never now_ms() (B0023), and passed as a value as fn() now_ms end.",
77    },
78    Form {
79        example: "f(a, *xs)",
80        lowers_to: "(apply f a xs)",
81        doc: "A splat: the list's elements are the call's last arguments. The one spelling of apply(f, a, xs) with f a name (B0042).",
82    },
83    Form {
84        example: "cap.status",
85        lowers_to: "(blue-field cap :status)",
86        doc: "A field read: a map's keyword or string key, a keyed list such as exec_capture's result or a parsed JSON object, or an error's kind, message, data, cause or trace. A missing field raises naming the fields there are; get(m, :k) reads one that may be absent.",
87    },
88    Form {
89        example: "x.f(y)",
90        lowers_to: "(f x y)",
91        doc: "A method-style call: the receiver becomes the first argument. Read, and written f(x, y) (B0028).",
92    },
93    Form {
94        example: "xs |> f(a)",
95        lowers_to: "(f xs a)",
96        doc: "A pipe: the value becomes the FIRST argument. Read, and written f(xs, a) (B0028). map(f, xs) is function-first: xs |> map(f) is map(xs, f), an error.",
97    },
98    Form {
99        example: "not x",
100        lowers_to: "(not x)",
101        doc: "Negation; `!x` is read and written `not x` (B0025).",
102    },
103    Form {
104        example: "-x",
105        lowers_to: "(- 0 x)",
106        doc: "Unary minus. The formatter writes 0 - x as -x.",
107    },
108    Form {
109        example: "use(\"retsu\")",
110        lowers_to: "(use \"retsu\")",
111        doc: "Import a bidama by name, found on BLUE_PATH. Every definition it makes joins one flat namespace.",
112    },
113    Form {
114        example: "raise(:parse, \"bad row\")",
115        lowers_to: "(raise :parse \"bad row\")",
116        doc: "Raise an error; raise(:k, \"m\", {data: d, cause: e}) attaches data and the error it wraps, raise(e) raises e again. throw(error(…)) is read as this (B0037).",
117    },
118    Form {
119        example: "risky(x) rescue fallback",
120        lowers_to: "(try (risky x) (catch (_) fallback))",
121        doc: "The value of risky(x), or fallback when it raises. Binds loosest of all, below |>.",
122    },
123    Form {
124        example: "begin\n  risky(x)\nrescue :timeout as e\n  wait(e)\nend",
125        lowers_to: "(try (risky x) (catch (rescued-error) (cond ((blue-rescues? rescued-error :timeout) (let ((e rescued-error)) (wait e))) (else (blue-reraise rescued-error)))))",
126        doc: "Catch by kind, binding the error; `rescue e` (last) catches every error, an unmatched kind raises again, and `ensure` runs on both paths. A def body takes the same clauses without begin.",
127    },
128];
129
130#[cfg(test)]
131mod tests {
132    use super::FORMS;
133    use crate::parse::{keyword_doc, parse_program, BLOCK_KEYWORDS, INFIX, SURFACE_KEYWORDS};
134
135    fn lowered(src: &str) -> String {
136        parse_program(src)
137            .unwrap_or_else(|e| panic!("`{src}` does not parse: {e}"))
138            .iter()
139            .map(ToString::to_string)
140            .collect::<Vec<_>>()
141            .join(" ")
142    }
143
144    /// Red run, 2026-09-29: changing the pipe row's `lowers_to` to
145    /// `(f a xs)` failed with "`xs |> f(a)` lowers to (f xs a), and its row
146    /// says (f a xs)".
147    #[test]
148    fn every_form_lowers_as_its_row_says() {
149        for form in FORMS {
150            let got = lowered(form.example);
151            assert_eq!(
152                got, form.lowers_to,
153                "`{}` lowers to {got}, and its row says {}",
154                form.example, form.lowers_to
155            );
156        }
157    }
158
159    /// Red run, 2026-09-29: emptying the `"%"` row's doc failed with
160    /// "the operator `%` has no doc"; deleting the `"case"` arm of
161    /// `keyword_doc` failed with "the keyword `case` has no doc".
162    #[test]
163    fn every_operator_and_keyword_is_described() {
164        for op in INFIX {
165            assert!(
166                !op.doc.trim().is_empty(),
167                "the operator `{}` has no doc",
168                op.op
169            );
170        }
171        for word in SURFACE_KEYWORDS.iter().chain(BLOCK_KEYWORDS) {
172            assert!(
173                !keyword_doc(word).trim().is_empty(),
174                "the keyword `{word}` has no doc"
175            );
176        }
177        for form in FORMS {
178            assert!(
179                !form.doc.trim().is_empty(),
180                "the form `{}` has no doc",
181                form.example
182            );
183        }
184    }
185}
blue_lang_syntax/forms.rs

blue_lang_syntax/
forms.rs
