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