Next: Copy Mode, Previous: Writing Macros, Up: Writing Macros [Contents][Index]
Macro calls and string interpolations optionally accept a list of arguments; recall Calling Macros. At the time such an interpolation takes place, these parameters can be examined using a register and a variety of escape sequences starting with ‘\$’. All such escape sequences are interpreted even in copy mode, a fact we shall motivate and explain below (see Copy Mode).
The count of parameters available to a macro or string is kept in this
read-only register. The shift
request can change its value.
Any individual parameter can be accessed by its position in the list of arguments to the macro call, numbered from left to right starting at 1, with one of the following escape sequences.
Interpolate the nth, nnth, or nnnth parameter. The
first form expects only a single digit (1≤n≤9)), the
second two digits (01≤nn≤99)), and the third any
positive integer nnn. Macros and strings accept an unlimited
number of parameters.
\$
is interpreted even in copy mode.118
Shift the parameters n places (1 by default). This is a
“left shift”: what was parameter i becomes parameter
i-n. The parameters formerly in positions 1
to n are no longer available. Shifting by a non-positive
amount performs no operation. The register .$
is adjusted
accordingly.
In practice, parameter interpolations are usually seen prefixed with an
extra escape character. This is because the \$
family of escape
sequences is interpreted even in copy mode.119
In some cases it is convenient to interpolate all of the parameters at
once (to pass them to a request, for instance). The \$*
escape
catenates the parameters, separating them with spaces. \$@
is
similar, surrounding each parameter with double quotes and separating
them with spaces. If not in compatibility mode, the interpolation depth
of double quotes is preserved (see Calling Macros). \$^
interpolates all parameters as if they were arguments to the ds
request.
.de foo . tm $1='\\$1' . tm $2='\\$2' . tm $*='\\$*' . tm $@='\\$@' . tm $^='\\$^' .. .foo " This is a "test" error→ $1=' This is a ' error→ $2='test"' error→ $*=' This is a test"' error→ $@='" This is a " "test""' error→ $^='" This is a "test"'
\$*
is useful when writing a macro that doesn’t need to
distinguish its arguments, or even to not interpret them; examples
include macros that produce diagnostic messages by wrapping the
tm
or ab
requests. Use \$@
when writing a macro
that may need to shift its parameters and/or wrap a macro or request
that finds the count significant. If in doubt, prefer \$@
to
\$*
. An application of \$^
is seen in trace.tmac,
which redefines some requests and macros for debugging purposes.
Interpolate the name by which the macro being interpreted was called.
The als
request can cause a macro to have more than one name.
Applying string interpolation to a macro does not change this name.
.de foo . tm \\$0 .. .als bar foo . .de aaa . foo .. .de bbb . bar .. .de ccc \\*[foo]\\ .. .de ddd \\*[bar]\\ .. . .aaa error→ foo .bbb error→ bar .ccc error→ ccc .ddd error→ ddd
Next: Copy Mode, Previous: Writing Macros, Up: Writing Macros [Contents][Index]