1# Macros
2
3A macro is created using a "`define`" statement:
4
5~~~ pikchr toggle
6$r = 0.2in
7linerad = 0.75*$r
8linewid = 0.25
9
10# Start and end blocks
11#
12box "define-statement" bold fit
13line down 50% from last box.sw
14START: dot rad 250% color black
15X0: last.e
16move right 3.2in
17END: box wid 5% ht 25% fill black
18X9: last.w
19
20# The main rule
21#
22arrow from X0 right 2*linerad+arrowht
23oval "\"define\"" fit
24arrow
25oval "MACRONAME" fit
26arrow
27oval "{...}" fit
28line right to X9
29~~~
30
31A define statement consists of the keyword "`define`" followed by
32an identifier that is the name of the macro and then the body of
33the macro contained within (possibly nested) curly braces.
34
35After a macro is defined, the body of the macro is substituted in
36place of any subsquent occurrence of the identifier that is the
37macro name.  The macro name can occur anywhere.  The substitution
38is performed by the lexical analyzer, before tokens are identified
39and sent into the parser.  Note this distinction:  The "`define`"
40statement used to create a new macro is recognized by the parser,
41but the expansion of the macro is subsequent text happens in the
42lexical analyzer.
43
44## Parameters
45
46The invocation of a macro can be followed immediately by a
47parenthesized list of parameters.  The open-parenthesis must immediately
48follow the macro name with no intervening whitespace.  Parameters are
49comma-separated.  There can be at most 9 parameters.
50
51When parameters are present, they are substituted in the macro body
52in place of "`$1`", "`$2`", ..., "`$9`" in the macro body.  If
53"$N" (for N between 1 and 9) occurs in the macro body but there are
54fewer than N parameters, then the "$N" is omitted.
55
56## Nested Macros
57
58Macros can be nested up to a maximum depth that is determined at
59compile-time.  (The current limit is 10.)
60
61Arguments to nested macros can be arbitrary text, or a single "$N"
62parameter, but not both.
63
64## Macros cannot be undefined or redefined
65
66Once created, a macro cannot be redefined.  If you attempt to redefine
67a macro by providing a second "`define`" statement with the same macro
68name, the macro name will be replaced by the previous macro body definition
69during lexical analysis, likely resulting in a syntax error.
70