Previous: Copy-in Mode, Up: Writing Macros


5.21.2 Parameters

The arguments to a macro or string can be examined using a variety of escapes.

— Register: \n[.$]

The number of arguments passed to a macro or string. This is a read-only number register.

Note that the shift request can change its value.

Any individual argument can be retrieved with one of the following escapes:

— Escape: \$n
— Escape: \$(nn
— Escape: \$[nnn]

Retrieve the nth, nnth or nnnth argument. As usual, the first form only accepts a single number (larger than zero), the second a two-digit number (larger or equal to 10), and the third any positive integer value (larger than zero). Macros and strings can have an unlimited number of arguments. Note that due to copy-in mode, use two backslashes on these in actual use to prevent interpolation until the macro is actually invoked.

— Request: .shift [n]

Shift the arguments 1 position, or as many positions as specified by its argument. After executing this request, argument i becomes argument i-n; arguments 1 to n are no longer available. Shifting by negative amounts is currently undefined.

The register .$ is adjusted accordingly.

— Escape: \$*
— Escape: \$@

In some cases it is convenient to use all of the arguments at once (for example, to pass the arguments along to another macro). The \$* escape concatenates all the arguments separated by spaces. A similar escape is \$@, which concatenates all the arguments with each surrounded by double quotes, and separated by spaces. If not in compatibility mode, the input level of double quotes is preserved (see Request and Macro Arguments).

— Escape: \$^

Handle the parameters of a macro as if they were an argument to the ds or similar requests.

          
          .de foo
          .  tm $1=`\\$1'
          .  tm $2=`\\$2'
          .  tm $*=`\\$*'
          .  tm $@=`\\$@'
          .  tm $^=`\\$^'
          ..
          .foo " This is a "test"
              ⇒ $1=` This is a '
              ⇒ $2=`test"'
              ⇒ $*=` This is a  test"'
              ⇒ $@=`" This is a " "test""'
              ⇒ $^=`" This is a "test"'

This escape is useful mainly for macro packages like trace.tmac which redefines some requests and macros for debugging purposes.

— Escape: \$0

The name used to invoke the current macro. The als request can make a macro have more than one name.

If a macro is called as a string (within another macro), the value of \$0 isn't changed.

          
          .de foo
          .  tm \\$0
          ..
          .als foo bar
          .
          
          .de aaa
          .  foo
          ..
          .de bbb
          .  bar
          ..
          .de ccc
          \\*[foo]\\
          ..
          .de ddd
          \\*[bar]\\
          ..
          .
          
          .aaa
              ⇒ foo
          .bbb
              ⇒ bar
          .ccc
              ⇒ ccc
          .ddd
              ⇒ ddd

See Request and Macro Arguments.