Info Catalog m4: Define m4: Definitions m4: Pseudo Arguments

m4: Arguments

 
 5.2 Arguments to macros
 =======================
 
 Macros can have arguments.  The Nth argument is denoted by '$n' in the
 expansion text, and is replaced by the Nth actual argument, when the
 macro is expanded.  Replacement of arguments happens before rescanning,
 regardless of how many nesting levels of quoting appear in the
 expansion.  Here is an example of a macro with two arguments.
 
  -- Composite: exch (ARG1, ARG2)
      Expands to ARG2 followed by ARG1, effectively exchanging their
      order.
 
      define(`exch', `$2, $1')
      =>
      exch(`arg1', `arg2')
      =>arg2, arg1
 
    This can be used, for example, if you like the arguments to 'define'
 to be reversed.
 
      define(`exch', `$2, $1')
      =>
      define(exch(``expansion text'', ``macro''))
      =>
      macro
      =>expansion text
 
    ⇒Quoting Arguments, for an explanation of the double quotes.
 (You should try and improve this example so that clients of 'exch' do
 not have to double quote; or ⇒Answers Improved exch.).
 
    As a special case, the zeroth argument, '$0', is always the name of
 the macro being expanded.
 
      define(`test', ``Macro name: $0'')
      =>
      test
      =>Macro name: test
 
    If you want quoted text to appear as part of the expansion text,
 remember that quotes can be nested in quoted strings.  Thus, in
 
      define(`foo', `This is macro `foo'.')
      =>
      foo
      =>This is macro foo.
 
 The 'foo' in the expansion text is _not_ expanded, since it is a quoted
 string, and not a name.
 
    GNU 'm4' allows the number following the '$' to consist of one or
 more digits, allowing macros to have any number of arguments.  The
 extension of accepting multiple digits is incompatible with POSIX, and
 is different than traditional implementations of 'm4', which only
 recognize one digit.  Therefore, future versions of GNU M4 will phase
 out this feature.  To portably access beyond the ninth argument, you can
 use the 'argn' macro documented later (⇒Shift).
 
    POSIX also states that '$' followed immediately by '{' in a macro
 definition is implementation-defined.  This version of M4 passes the
 literal characters '${' through unchanged, but M4 2.0 will implement an
 optional feature similar to 'sh', where '${11}' expands to the eleventh
 argument, to replace the current recognition of '$11'.  Meanwhile, if
 you want to guarantee that you will get a literal '${' in output when
 expanding a macro, even when you upgrade to M4 2.0, you can use nested
 quoting to your advantage:
 
      define(`foo', `single quoted $`'{1} output')
      =>
      define(`bar', ``double quoted $'`{2} output'')
      =>
      foo(`a', `b')
      =>single quoted ${1} output
      bar(`a', `b')
      =>double quoted ${2} output
 
    To help you detect places in your M4 input files that might change in
 behavior due to the changed behavior of M4 2.0, you can use the
 '--warn-macro-sequence' command-line option (⇒Invoking m4
 Operation modes.) with the default regular expression.  This will add a
 warning any time a macro definition includes '$' followed by multiple
 digits, or by '{'.  The warning is not enabled by default, because it
 triggers a number of warnings in Autoconf 2.61 (and Autoconf uses '-E'
 to treat warnings as errors), and because it will still be possible to
 restore older behavior in M4 2.0.
 
      $ m4 --warn-macro-sequence
      define(`foo', `$001 ${1} $1')
      error->m4:stdin:1: Warning: definition of `foo' contains sequence `$001'
      error->m4:stdin:1: Warning: definition of `foo' contains sequence `${1}'
      =>
      foo(`bar')
      =>bar ${1} bar
 

Info Catalog m4: Define m4: Definitions m4: Pseudo Arguments