5.24.1 Parameters

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).

Register: \n[.$]

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.

Escape sequence: \$n

Escape sequence: \$(nn

Escape sequence: \$[nnn]

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.

Request: .shift [n]

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.¹⁰⁰

Escape sequence: \$*

Escape sequence: \$@

Escape sequence: \$^

In some cases it is convenient to interpolate all of the parameters at once (to pass them to a request, for instance). The \$* escape concatenates the parameters, separating them with spaces. \$@ is similar, concatenating the parameters, surrounding each 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.

Escape sequence: \$0

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