File: m4.info,  Node: Inhibiting Invocation,  Next: Macro Arguments,  Prev: Invocation,  Up: Macros

4.2 Preventing macro invocation
===============================

An innovation of the ‘m4’ language, compared to some of its predecessors
(like Strachey'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.  As a GNU extension, 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 with parameters" refers to this
specific provision of GNU M4, also known as a blind builtin macro.  For
the builtins defined by POSIX that bear this disclaimer, POSIX
specifically states that invoking those builtins without arguments is
unspecified, because many other implementations simply invoke the
builtin as though it were given one empty argument instead.

     $ m4
     eval
     ⇒eval
     eval(`1')
     ⇒1

   There is also a command line option (‘--prefix-builtins’, or ‘-P’,
*note Invoking m4: Operation modes.) that renames all builtin macros
with a prefix of ‘m4_’ at startup.  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’.  It also has no effect on whether a macro
requires parameters.

     $ m4 -P
     eval
     ⇒eval
     eval(`1')
     ⇒eval(1)
     m4_eval
     ⇒m4_eval
     m4_eval(`1')
     ⇒1

   Another alternative is to redefine problematic macros to a name less
likely to cause conflicts, using *note Definitions::.

   If your version of GNU ‘m4’ has the ‘changeword’ feature compiled in,
it offers far more flexibility in specifying the syntax of macro names,
both builtin or user-defined.  *Note Changeword::, for more information
on this experimental feature.

   Of course, the simplest way to prevent a name from being 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 (provided, of
course, that the unquoted portions are not also a macro).  It is also
possible to quote the empty string, but this works only _inside_ the
name.  For example:

     `divert'
     ⇒divert
     `d'ivert
     ⇒divert
     di`ver't
     ⇒divert
     div`'ert
     ⇒divert

all yield the string ‘divert’.  While in both:

     `'divert
     ⇒
     divert`'
     ⇒

the ‘divert’ builtin macro will be called, which expands to the empty
string.

   The output of macro evaluations is always rescanned.  In the
following example, the input ‘x`'y’ yields the string ‘bCD’, exactly as
if ‘m4’ has been given ‘substr(ab`'cde, `1', `3')’ as input:

     define(`cde', `CDE')
     ⇒
     define(`x', `substr(ab')
     ⇒
     define(`y', `cde, `1', `3')')
     ⇒
     x`'y
     ⇒bCD

   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 second ‘macro’ to be recognized as such:

     define(`macro', `m')
     ⇒
     macro(`m')macro
     ⇒mmacro
     macro(`m')`'macro
     ⇒mm

   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')
     ⇒
     macro(`v')`ert'
     ⇒divert
     macro(`v')ert
     ⇒

the input will produce the string ‘divert’.  When the quotes were
removed, the ‘divert’ builtin was called instead.