Macros: source that writes source
the system macros, seeing an expansion, and macro libraries of your own

Table of Contents

A macro is a name with the macro mark < at its end; u_se<, which imports a library, is the one met first. A call is written like a dyadic function with a string on each side, "left" n_ame< "right", and before the program is checked the macro replaces the call with source it writes from the two texts. Whatever a macro writes is then read, type-checked and run like code you typed. Every block below is run by xetal through ob-xetal, and its result recorded under it.

The system macros

The system macros are always there; no import is needed. They are written in X_eTaL like any macro library, in lib/System.xtlm (built into xetal and loaded before every file), each with a comment saying what it does and an example. A side of a call that takes nothing is written @: @ l_ine< @. The first three choose and repeat code.

i_f<: one of two expressions

"c" i_f< "a; b" is the value of a when c holds, else of b. The condition is evaluated when the program runs, and only the expression chosen is evaluated, so the 1 / 0 below never is:

x ← -3
"x > 0" i̲f< "1; -1"
10 × "x > 0" i̲f< "1; -1"
"x < 0" i̲f< "0; 1 / 0"

⍝ typed:
⍝   x := -3
⍝   "x > 0" i_f< "1; -1"
⍝   10 * "x > 0" i_f< "1; -1"
⍝   "x < 0" i_f< "0; 1 / 0"
-1
-10
0.0

The macro writes a guard in a lambda of no argument, applied at once; inside an expression it is parenthesized. xetal expand shows the program after the macros have written their source:

$ xetal expand -e '"x > 0" i_f< "1; -1"'
{ @ -> (x > 0) ? 1; -1 } @
$ xetal expand -e '10 * "x > 0" i_f< "1; -1"'
10 * ({ @ -> (x > 0) ? 1; -1 } @)

Both expressions are checked and must have one type, which is why the third line gives 0.0: 1 / 0 is a Float, so the 0 is one too.

u_nless<: statements run unless a condition holds

"c" u_nless< "b" runs the statements b unless c holds. It is there for what b does (printing, here), so its own value is @ (Unit, the value that stands for nothing), shown like any other value of a statement:

n ← 4
"n = 0" u̲nless< "p_rint! 100 / n"

⍝ typed:
⍝   n := 4
⍝   "n = 0" u_nless< "p_rint! 100 / n"
25.0
@

It writes { @ -> (n = 0) ? @; p_rint! 100 / n; @ } @.

e_ach<: a statement per word

"w1 w2" e_ach< "template" writes one copy of the template for each word on its left, with $w in it replaced by the word. A family of definitions is the use a function cannot serve, since a function cannot make names:

"m_ax m_in" e̲ach< "u:$w/ := { '$w r_/ _r }"
ᵘm̲ax/ 3 1 4 1 5
ᵘm̲in/ 3 1 4 1 5

⍝ typed:
⍝   "m_ax m_in" e_ach< "u:$w/ := { '$w r_/ _r }"
⍝   u:m_ax/ 3 1 4 1 5
⍝   u:m_in/ 3 1 4 1 5
5
1

It wrote u:m_ax/ := { 'm_ax r_/ _r } and u:m_in/ := { 'm_in r_/ _r }, one per line: e_ach< writes statements, so it stands as a statement of its own.

f_ormat<: text with values in it

@ f_ormat< "text {expr}" puts the value of each {expr}, any expression, into the text, as the function f_ormat writes it (a Bool as 0 or 1); {{ and }} are braces (Rust's format!):

v ← 3 1 2
@ f̲ormat< "v = {v}, its sum {'+ r_/ v}, sorted? {v m_atch s_ort v}, {{braces}}"

⍝ typed:
⍝   v := 3 1 2
⍝   @ f_ormat< "v = {v}, its sum {'+ r_/ v}, sorted? {v m_atch s_ort v}, {{braces}}"
v = 3 1 2, its sum 6, sorted? 0, {braces}

It writes "v = " c_at (f_ormat (v)) c_at .... An unclosed {, an empty {} or a lone } is an error before the program runs, and a type error inside a hole is reported where it was written in the string.

d_bg<, c_heck< and a_ssert<: looking, checking and asserting

@ d_bg< "expr" gives the value of expr after writing it, as written, with its value and its place, on standard error (Rust's dbg!). "cond" c_heck< "message" (or @ for no message) reports a condition that does not hold, as written, and the program goes on. "cond" a_ssert< "message" stops the program there, as Rust's assert! does. Standard error shows:

$ xetal eval -e 'x := 6
y := 1 + @ d_bg< "x * 2"
y'
[-e:2] x * 2 = 12
13
$ xetal eval -e 'x := 6
"x > 10" c_heck< "x is big"'
check failed: x > 10 (x is big) [-e:2]
@
$ xetal eval -e 'x := 6
"x > 10" a_ssert< "x is big"'
error[assertion]: assertion failed: x > 10 (x is big)
 --> -e:2:1
  |
2 | "x > 10" a_ssert< "x is big"
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

p_anic<: stopping

@ p_anic< "message {expr}" stops the program with error[panic] and the message, formatted as f_ormat< does, at the call. It stands where any value may, an Int or a text:

$ xetal eval -e 'u:s_ize := { k -> k > 3 ? @ p_anic< "bad grid size {k}"; k * 2 }
u:s_ize 2
u:s_ize 5'
4
error[panic]: bad grid size 5
 --> -e:1:27
  |
1 | u:s_ize := { k -> k > 3 ? @ p_anic< "bad grid size {k}"; k * 2 }
  |                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What the compiler knows

Some macros give what only the compiler knows, through hooks no ordinary function can call:

Call Gives
@ l_ine< @ the line the call is written on
@ f_ile< @ the file it is written in (-e for command-line text)
@ i_nclude< "data.txt" the text of a file beside it, as a string (Rust's include_str!)
@ c_fg< "web" 1 when the fact holds: the platform, cli or web, or a flag set with xetal --cfg NAME
"code" e_rror< "message" a compile error at the call (Rust's compile_error!)
@ c̲fg< "cli"
@ c̲fg< "web"

⍝ typed:
⍝   @ c_fg< "cli"
⍝   @ c_fg< "web"
1
0

A macro of yours can write e_rror< into its text to refuse a call: the error is reported at your call, with your code and message.

Macros of your own

A macro library is a file ending in .xtlm. It defines its macros as m:n_ame<, each an ordinary function of the two texts, left and right, that gives the text replacing the call. The standard library Macros (lib/Macros.xtlm) is a small example:

⍝│ A small macro library, an example of macros of your own (MC10). A
⍝│ macro is an ordinary function of the source text written on each
⍝│ side of its call; the text it gives replaces the call, then is read
⍝│ as code. Import it with an alias of your own, "x:" u_se< "Macros",
⍝│ and see what a program becomes with xetal expand FILE. The contract
⍝│ lines above a macro (MC31) say the shape of call it takes (checked
⍝│ before it runs), whether it copies its text (every name and number
⍝│ must reach the expansion) or parses it, and the names it binds for
⍝│ your text.

⍝━━ Statements and definitions

⍝│ Run the statements on the right when the condition on the left
⍝│ holds; the value is @ either way (the other way round from the
⍝│ system macro u_nless<).
⍝│ takes: code code
⍝│ >> "x:" u_se< "Macros"
⍝│ >> c"1 < 2" x:w_hen< c"p_rint! 7"
⍝│ 7
⍝│ @
ᵐw̲hen< ← { cond body → "{ @ -> (n_ot " c̲at cond c̲at ") ? @; " c̲at body c̲at "; @ } @" }

⍝│ Define the function named on the left (in u:) as the lambda body on
⍝│ the right, its name written as text.
⍝│ takes: text code
⍝│ >> "x:" u_se< "Macros"
⍝│ >> "s_quare" x:d_ef< c"_r * _r"
⍝│ >> u:s_quare 7
⍝│ 49
ᵐd̲ef< ← { name body → "u:" c̲at name c̲at " := { " c̲at body c̲at " }" }

⍝━━ Checks

⍝│ The line "ok: label" when the condition on the left holds, else
⍝│ "FAIL: label (cond)", the condition shown as it was written, which a
⍝│ function, given only the condition's value, cannot do.
⍝│ takes: code text
⍝│ >> "x:" u_se< "Macros"
⍝│ >> c"5 = 2 * 2" x:t_est< "doubling"
⍝│ FAIL: doubling (5 = 2 * 2)
ᵐt̲est< ← { cond label → "{ @ -> (" c̲at cond c̲at ") ? \"ok: " c̲at label c̲at "\"; \"FAIL: " c̲at label c̲at " (" c̲at cond c̲at ")\" } @" }

⍝━━ Names a macro binds

⍝│ The expression on the right with x as 3: the macro binds x around
⍝│ your expression and writes it as it is, so your x is its x. A name a
⍝│ macro writes stays as written; that is how an anaphor works, and a
⍝│ macro that wants a name of its own asks for one (t_wice< below).
⍝│ binds: x
⍝│ takes: @ code
⍝│ >> "x:" u_se< "Macros"
⍝│ >> x := 10
⍝│ >> @ x:b_inds< c"x + 1"
⍝│ 4
ᵐb̲inds< ← { @ e → "{ @ -> x := 3; " c̲at e c̲at " } @" }

⍝│ Twice the expression on the right: the macro binds a local of its
⍝│ own around your expression, a fresh name from []G_ENSYM (g1:t, say),
⍝│ so a t of your own is still yours.
⍝│ takes: @ code
⍝│ >> "x:" u_se< "Macros"
⍝│ >> t := 5
⍝│ >> @ x:t_wice< c"t + 1"
⍝│ 12
ᵐt̲wice< ← { @ e →
  t ← ⎕G̲ENSYM "t"
  "{ @ -> " c̲at t c̲at " := 2; " c̲at t c̲at " * (" c̲at e c̲at ") } @"
}

⍝│ The text on the right with it bound to the value of the expression
⍝│ on the left (an anaphoric macro: it is meant for your text, declared
⍝│ below, so your text cannot bind an it of its own).
⍝│ binds: it
⍝│ takes: code code
⍝│ >> "x:" u_se< "Macros"
⍝│ >> c"3 + 4" x:w_ith< c"it * it"
⍝│ 49
ᵐw̲ith< ← { e body → "{ @ -> it := (" c̲at e c̲at "); " c̲at body c̲at " } @" }

⍝ typed:
⍝   m:w_hen< := { cond body -> "{ @ -> (n_ot " c_at cond c_at ") ? @; " c_at body c_at "; @ } @" }
⍝   m:d_ef< := { name body -> "u:" c_at name c_at " := { " c_at body c_at " }" }
⍝   m:t_est< := { cond label -> "{ @ -> (" c_at cond c_at ") ? \"ok: " c_at label c_at "\"; \"FAIL: " c_at label c_at " (" c_at cond c_at ")\" } @" }
⍝   m:b_inds< := { @ e -> "{ @ -> x := 3; " c_at e c_at " } @" }
⍝   m:t_wice< := { @ e ->
⍝     t := []G_ENSYM "t"
⍝     "{ @ -> " c_at t c_at " := 2; " c_at t c_at " * (" c_at e c_at ") } @"
⍝   }
⍝   m:w_ith< := { e body -> "{ @ -> it := (" c_at e c_at "); " c_at body c_at " } @" }

It is imported like any library, under a prefix of your choosing: "m:" u_se< "Macros" finds Macros.xtlm (and Macros.xtl, had there been one in the same directory: a library and its macro library share one prefix). Its macros are called with that prefix:

"m:" u̲se< "Macros"
"s_quare" ᵐd̲ef< "_r * _r"
ᵘs̲quare 7
"4 = 2 + 2" ᵐt̲est< "addition"
"5 = 2 * 2" ᵐt̲est< "doubling"

⍝ typed:
⍝   "m:" u_se< "Macros"
⍝   "s_quare" m:d_ef< "_r * _r"
⍝   u:s_quare 7
⍝   "4 = 2 + 2" m:t_est< "addition"
⍝   "5 = 2 * 2" m:t_est< "doubling"
49
ok: addition
FAIL: doubling (5 = 2 * 2)

m:d_ef< made a function from a name given as text. m:t_est< shows its condition as it was written, which a function, given only the condition's value, could not: it wrote { @ -> (5 = 2 * 2) ? "ok: doubling"; "FAIL: doubling (5 = 2 * 2)" } @.

A macro runs when the program is expanded, before it is checked: the macro library is loaded, its function is applied to the two texts, and the text it gives replaces the call. That text may call macros again; expansion stops with an error when macros nest more than 32 deep.

Mistakes it catches

A macro takes a string, or @ for none, on each side:

x i_f< "1; 2"
error[bad-macro-call]: i_f< takes a string, or @ for none, on each side: "left" i_f< "right"

A macro a macro library does not define is an error listing those it does:

"x:" u_se< "Macros"
"a" x:n_ope< "b"
error[not-exported]: x:n_ope< is not defined by that macro library; it defines w_hen<, d_ef<, t_est<

Macros are defined only in macro libraries, as m: names ending in <:

u:f_< := { a b -> a }
error[misdefined-macro]: macros are defined in macro libraries (.xtlm files), as m:n_ame<

And an error in code written inside a macro's argument is reported where it was written, inside the string. The whole program of this document is demos/macros.xtl; xetal expand demos/macros.xtl shows it after expansion.

Literate documents · Live demo · Repository