Info Catalog groff: Writing Macros groff: Writing Macros groff: Copy Mode

groff: Parameters

 
 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 (⇒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
 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 (⇒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
 

Info Catalog groff: Writing Macros groff: Writing Macros groff: Copy Mode