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 read-only register .$ makes the count of a macro or interpolation’s parameters available to its definition. The shift request dequeues parameters, and thus updates .$’s 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. The formatter interprets \$ even in copy mode.²⁶³

Request: .shift [n]

Shift macro or string parameters n places (by 1 if n omitted): argument i becomes argument i-n; arguments 1 to n become unavailable. The register .$ adjusts its value accordingly. Shifting by a non-positive amount, or outside of a macro or string definition, performs no operation.

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

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