21.3.2 Macros and macro expansion
Macros are definitions of replacement text and are identified by a
name--as defined by the syntax rules given in 21.3.1 Token scanning.
M4 maintains an internal table of macros, some of which are
built-ins defined when
m4 starts. When a name is found in the
input that matches a name registered in M4's macro table, the
macro invocation in the input is replaced by the macro's
definition in the output. This process is known as
expansion---even if the new text may be shorter! Many beginners
to M4 confuse themselves the moment they start to use phrases
like `I am going to call this particular macro, which returns this
value'. As you will see, macros differ significantly from
functions in other programming languages, regardless of how
similar their syntax may seem. You should instead use phrases like `If
I invoke this macro, it will expand to this text'.
Suppose M4 knows about a simple macro called `foo' that is
defined to be `bar'. Given the following input,
produce the corresponding output:
That is one big foo.
=>That is one big bar.
The period character at the end of this sentence is not permitted in
macro names, thus
m4 knows when to stop scanning the `foo'
token and consult the table of macro definitions for a macro named
Curiously, macros are defined to
m4 using the built-in macro
define. The example shown above would be defined to
with the following input:
define is itself a macro, it too must have an
expansion--by definition, it is the empty string, or void.
m4 will appear to consume macro invocations like these from
the input. The
' characters are M4's default
quote characters and play an important role (21.3.3 Quoting). Additional
built-in macros exist for managing macro definitions (21.4.2 Macro management).
We've explored the simplest kind of macros that exist in M4. To make
macros substantially more useful, M4 extends the concept to macros which
accept a number of arguments (49). If a macro is given arguments, the
macro may address its arguments using the special macro names `$1'
through to `$n', where `n' is the maximum number of arguments
that the macro cares to reference. When such a macro is invoked, the
argument list must be delimited by commas and enclosed in parentheses.
Any whitespace that precedes an argument is discarded, but trailing
whitespace (for example, before the next comma) is preserved. Here is
an example of a macro which expands to its third argument:
That is one big foo(3, `0x', `beef').
=>That is one big beef.
Arguments in M4 are simply text, so they have no type. If a
macro which accepts arguments is invoked,
m4 will expand the
macro regardless of how many arguments are provided. M4 will
not produce errors due to conditions such as a mismatched number of
arguments, or arguments with malformed values/types. It is the
responsibility of the macro to validate the argument list and this is an
important practice when writing GNU Autotools macros. Some common
M4 idioms have developed for this purpose and are covered in
21.4.3 Conditionals. A macro that expects arguments can still be invoked
without arguments--the number of arguments seen by the macro will be
This is still one big foo.
=>That is one big .
A macro invoked with an empty argument list is not empty at all, but
rather is considered to be a single empty string:
This is one big empty foo().
=>That is one big .
It is also important to understand how macros are expanded. It is here
that you will see why an M4 macro is not the same as a
function in any other programming language. The explanation you've been
reading about macro expansion thus far is a little bit simplistic:
macros are not exactly matched in the input and expanded in the output.
In actual fact, the macro's expansion replaces the invocation in the
input stream and it is rescanned for further expansions until
there are none remaining. Here is an illustrative example:
If the token `a1' were to be found in the input,
replace it with `a2' in the input stream and rescan. This
continues until no definition can be found for
a4, at which point
the literal text `a4' will be sent to the output. This is by
far the biggest point of misunderstanding for new M4 users.
The same principles apply for the collection of arguments to macros
which accept arguments. Before a macro's actual arguments are handed to
the macro, they are expanded until there are no more expansions left.
Here is an example--using the built-in
define macro (where the
problems are no different) which highlights the consequences of this.
define will redefine any existing macro:
In this example, we expect `foo' to be defined to `bar' and
then redefined to `baz'. Instead, we've defined a new macro
`bar' that is defined to be `baz'! Why? The second
define invocation has its arguments expanded prior to the
define macro. At this stage, the name `foo'
is expanded to its original definition,
bar. In effect, we've
Sometimes this can be a very useful property, but mostly it serves to
thoroughly confuse the GNU Autotools macro writer. The key is to know that
m4 will expand as much text as it can as early as possible in its
processing. Expansion can be prevented by quoting (50) and is discussed in detail in the