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

See 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 see Answers).

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 (see 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 (see Invoking m4) 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