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, m4 would 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 `foo'.

Curiously, macros are defined to m4 using the built-in macro define. The example shown above would be defined to m4 with the following input:

define(`foo', `bar')

Since define is itself a macro, it too must have an expansion--by definition, it is the empty string, or void. Thus, m4 will appear to consume macro invocations like these from the input. The ` and ' 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:

define(`foo', `$3') 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 zero:

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:

define(`foobar', `FUBAR') define(`f', `foo') f()bar =>FUBAR

If the token `a1' were to be found in the input, m4 would 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. Normally, define will redefine any existing macro:

define(foo, bar) define(foo, baz)

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 expanding the define macro. At this stage, the name `foo' is expanded to its original definition, bar. In effect, we've stated:

define(foo, bar) define(bar, baz)

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 following section.