File: m4.info,  Node: Arguments,  Next: Pseudo Arguments,  Prev: Define,  Up: Definitions

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

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