File: groff.info,  Node: Parameters,  Next: Copy Mode,  Prev: Writing_Macros.php">Writing Macros,  Up: Writing_Macros.php">Writing Macros

5.24.1 Parameters
-----------------

Macro calls and string interpolations optionally accept a list of
arguments; recall *note 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 (*note 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.(1)  (*note
Parameters-Footnote-1::)

 -- 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 (*note 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