Go to the first, previous, next, last section, table of contents.

Preventing macro invocation

An innovation of the m4 language, compared to some of its predecessors (like Stratchey's GPM, for example), is the ability to recognize macro calls without resorting to any special, prefixed invocation character. While generally useful, this feature might sometimes be the source of spurious, unwanted macro calls. So, GNU m4 offers several mechanisms or techniques for inhibiting the recognition of names as macro calls.

First of all, many builtin macros cannot meaningfully be called without arguments. For any of these macros, whenever an opening parenthesis does not immediately follow their name, the builtin macro call is not triggered. This solves the most usual cases, like for `include' or `eval'. Later in this document, the sentence "This macro is recognized only when given arguments" refers to this specific provision.

There is also a command call option (--prefix-builtins, or -P) which requires all builtin macro names to be prefixed by `m4_' for them to be recognized. The option has no effect whatsoever on user defined macros. For example, with this option, one has to write m4_dnl and even m4_m4exit.

If your version of GNU m4 has the changeword feature compiled in, there it offers far more flexibility in specifying the syntax of macro names, both builtin or user-defined. See section Changing the lexical structure of words for more information on this experimental feature.

Of course, the simplest way to prevent a name to be interpreted as a call to an existing macro is to quote it. The remainder of this section studies a little more deeply how quoting affects macro invocation, and how quoting can be used to inhibit macro invocation.

Even if quoting is usually done over the whole macro name, it can also be done over only a few characters of this name. It is also possible to quote the empty string, but this works only inside the name. For example:


all yield the string `divert'. While in both:


the divert builtin macro will be called.

The output of macro evaluations is always rescanned. The following example would yield the string `de', exactly as if m4 has been given `substr(abcde, 3, 2)' as input:

define(`x', `substr(ab')
define(`y', `cde, 3, 2)')

Unquoted strings on either side of a quoted string are subject to being recognized as macro names. In the following example, quoting the empty string allows for the dnl macro to be recognized as such:

define(`macro', `di$1')

Without the quotes, this would rather yield the string `divdnl' followed by an end of line.

Quoting may prevent recognizing as a macro name the concatenation of a macro expansion with the surrounding characters. In this example:

define(`macro', `di$1')

the input will produce the string `divert'. If the quote was removed, the divert builtin would be called instead.

Go to the first, previous, next, last section, table of contents.