GNU Info

(m4.info)Inhibiting Invocation

---

Next: Macro Arguments Prev: Invocation Up: Macros

---

Enter node , (file) or (file)node

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.  Note: Changeword 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:

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

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

     `'divert
     divert`'

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)')
     x`'y

   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')
     macro(v)`'dnl

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

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