m4
m4
This manual is for GNU M4 (version 1.4.11, 31 March 2008), a package containing an implementation of the m4 macro language.
Copyright © 1989, 1990, 1991, 1992, 1993, 1994, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”
GNU m4 is an implementation of the traditional UNIX macro
processor. It is mostly SVR4 compatible, although it has some
extensions (for example, handling more than 9 positional parameters
to macros). m4 also has builtin functions for including
files, running shell commands, doing arithmetic, etc. Autoconf needs
GNU m4 for generating configure scripts, but not for
running them.
GNU m4 was originally written by René Seindal, with
subsequent changes by François Pinard and other volunteers
on the Internet. All names and email addresses can be found in the
files m4-1.4.11/AUTHORS and
m4-1.4.11/THANKS from the GNU M4
distribution.
This is release 1.4.11. It is now considered stable: future releases in the 1.4.x series are only meant to fix bugs, increase speed, or improve documentation. However...
An experimental feature, which would improve m4 usefulness,
allows for changing the syntax for what is a word in m4.
You should use:
./configure --enable-changeword
if you want this feature compiled in. The current implementation
slows down m4 considerably and is hardly acceptable. In the
future, m4 2.0 will come with a different set of new features
that provide similar capabilities, but without the inefficiencies, so
changeword will go away and you should not count on it.
--- The Detailed Node Listing ---
Introduction and preliminaries
Invoking m4
Lexical and syntactic conventions
How to invoke macros
How to define new macros
Conditionals, loops, and recursion
How to debug macros and input
Input control
File inclusion
Diverting and undiverting output
Macros for text handling
Macros for doing arithmetic
Macros for running shell commands
Miscellaneous builtin macros
Fast loading of frozen state
Compatibility with other versions of m4
Correct version of some examples
How to make copies of the overall M4 package
How to make copies of this manual
Indices of concepts and macros
This first chapter explains what GNU m4 is, where m4
comes from, how to read and use this documentation, how to call the
m4 program, and how to report bugs about it. It concludes by
giving tips for reading the remainder of the manual.
The following chapters then detail all the features of the m4
language.
m4m4 is a macro processor, in the sense that it copies its
input to the output, expanding macros as it goes. Macros are either
builtin or user-defined, and can take any number of arguments.
Besides just doing macro expansion, m4 has builtin functions
for including named files, running shell commands, doing integer
arithmetic, manipulating text in various ways, performing recursion,
etc.... m4 can be used either as a front-end to a compiler,
or as a macro processor in its own right.
The m4 macro processor is widely available on all UNIXes, and has
been standardized by POSIX.
Usually, only a small percentage of users are aware of its existence.
However, those who find it often become committed users. The
popularity of GNU Autoconf, which requires GNU
m4 for generating configure scripts, is an incentive
for many to install it, while these people will not themselves
program in m4. GNU m4 is mostly compatible with the
System V, Release 3 version, except for some minor differences.
See Compatibility, for more details.
Some people find m4 to be fairly addictive. They first use
m4 for simple problems, then take bigger and bigger challenges,
learning how to write complex sets of m4 macros along the way.
Once really addicted, users pursue writing of sophisticated m4
applications even to solve simple problems, devoting more time
debugging their m4 scripts than doing real work. Beware that
m4 may be dangerous for the health of compulsive programmers.
GPM was an important ancestor of m4. See
C. Stratchey: “A General Purpose Macro generator”, Computer Journal
8,3 (1965), pp. 225 ff. GPM is also succinctly described into
David Gries classic “Compiler Construction for Digital Computers”.
The classic B. Kernighan and P.J. Plauger: “Software Tools”,
Addison-Wesley, Inc. (1976) describes and implements a Unix
macro-processor language, which inspired Dennis Ritchie to write
m3, a macro processor for the AP-3 minicomputer.
Kernighan and Ritchie then joined forces to develop the original
m4, as described in “The M4 Macro Processor”, Bell
Laboratories (1977). It had only 21 builtin macros.
While GPM was more pure, m4 is meant to deal with
the true intricacies of real life: macros can be recognized without
being pre-announced, skipping whitespace or end-of-lines is easier,
more constructs are builtin instead of derived, etc.
Originally, the Kernighan and Plauger macro-processor, and then
m3, formed the engine for the Rational FORTRAN preprocessor,
that is, the Ratfor equivalent of cpp. Later, m4
was used as a front-end for Ratfor, C and Cobol.
René Seindal released his implementation of m4, GNU
m4,
in 1990, with the aim of removing the artificial limitations in many
of the traditional m4 implementations, such as maximum line
length, macro size, or number of macros.
The late Professor A. Dain Samples described and implemented a further
evolution in the form of M5: “User's Guide to the M5 Macro
Language: 2nd edition”, Electronic Announcement on comp.compilers
newsgroup (1992).
François Pinard took over maintenance of GNU m4 in
1992, until 1994 when he released GNU m4 1.4, which was
the stable release for 10 years. It was at this time that GNU
Autoconf decided to require GNU m4 as its underlying
engine, since all other implementations of m4 had too many
limitations.
More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which
addressed some long standing bugs in the venerable 1.4 release. Then in
2005, Gary V. Vaughan collected together the many patches to
GNU m4 1.4 that were floating around the net and
released 1.4.3 and 1.4.4. And in 2006, Eric Blake joined the team and
prepared patches for the release of 1.4.5, 1.4.6, 1.4.7, and 1.4.8. The
1.4.x series remains open for bug fixes, including releases 1.4.9,
1.4.10, and 1.4.11 in 2007.
Meanwhile, development has continued on new features for m4, such
as dynamic module loading and additional builtins. When complete,
GNU m4 2.0 will start a new series of releases.
If you have problems with GNU M4 or think you've found a bug, please report it. Before reporting a bug, make sure you've actually found a real bug. Carefully reread the documentation and see if it really says you can do what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation!
Before reporting a bug or trying to fix it yourself, try to isolate it
to the smallest possible input file that reproduces the problem. Then
send us the input file and the exact results m4 gave you. Also
say what you expected to occur; this will help us decide whether the
problem was really in the documentation.
Once you've got a precise problem, send e-mail to
bug-m4@gnu.org. Please include the version number of m4
you are using. You can get this information with the command
m4 --version. Also provide details about the platform you are
executing on.
Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation or are just obscure features, please report them too.
This manual contains a number of examples of m4 input and output,
and a simple notation is used to distinguish input, output and error
messages from m4. Examples are set out from the normal text, and
shown in a fixed width font, like this
This is an example of an example!
To distinguish input from output, all output from m4 is prefixed
by the string `=>', and all error messages by the string
`error-->'. When showing how command line options affect matters,
the command line is shown with a prompt `$ like this',
otherwise, you can assume that a simple m4 invocation will work.
Thus:
$ command line to invoke m4
Example of input line
=>Output line from m4
error-->and an error message
The sequence `^D' in an example indicates the end of the input file. The sequence `<NL>' refers to the newline character. The majority of these examples are self-contained, and you can run them with similar results by invoking m4 -d. In fact, the testsuite that is bundled in the GNU M4 package consists of the examples in this document! Some of the examples assume that your current directory is located where you unpacked the installation, so if you plan on following along, you may find it helpful to do this now:
$ cd m4-1.4.11
As each of the predefined macros in m4 is described, a prototype
call of the macro will be shown, giving descriptive names to the
arguments, e.g.,
This is a sample prototype. There is not really a macro named
example, but this documents that if there were, it would be a Composite macro, rather than a Builtin. It requires at least one argument, string. Remember that inm4, there must not be a space between the macro name and the opening parenthesis, unless it was intended to call the macro without any arguments. The brackets around count and argument show that these arguments are optional. If count is omitted, the macro behaves as if count were `1', whereas if argument is omitted, the macro behaves as if it were the empty string. A blank argument is not the same as an omitted argument. For example, `example(`a')', `example(`a',`1')', and `example(`a',`1',)' would behave identically with count set to `1'; while `example(`a',)' and `example(`a',`')' would explicitly pass the empty string for count. The ellipses (`...') show that the macro processes additional arguments after argument, rather than ignoring them.
All macro arguments in m4 are strings, but some are given
special interpretation, e.g., as numbers, file names, regular
expressions, etc. The documentation for each macro will state how the
parameters are interpreted, and what happens if the argument cannot be
parsed according to the desired interpretation. Unless specified
otherwise, a parameter specified to be a number is parsed as a decimal,
even if the argument has leading zeros; and parsing the empty string as
a number results in 0 rather than an error, although a warning will be
issued.
This document consistently writes and uses builtin, without a
hyphen, as if it were an English word. This is how the builtin
primitive is spelled within m4.
m4The format of the m4 command is:
m4 [option...] [file...]
All options begin with `-', or if long option names are used, with
`--'. A long option name need not be written completely, any
unambiguous prefix is sufficient. POSIX requires m4 to
recognize arguments intermixed with files, even when
POSIXLY_CORRECT is set in the environment. Most options take
effect at startup regardless of their position, but some are documented
below as taking effect after any files that occurred earlier in the
command line. The argument -- is a marker to denote the end of
options.
With short options, options that do not take arguments may be combined into a single command line argument with subsequent options, options with mandatory arguments may be provided either as a single command line argument or as two arguments, and options with optional arguments must be provided as a single argument. In other words, m4 -QPDfoo -d a -d+f is equivalent to m4 -Q -P -D foo -d -d+f -- ./a, although the latter form is considered canonical.
With long options, options with mandatory arguments may be provided with
an equal sign (`=') in a single argument, or as two arguments, and
options with optional arguments must be provided as a single argument.
In other words, m4 --def foo --debug a is equivalent to
m4 --define=foo --debug= -- ./a, although the latter form is
considered canonical (not to mention more robust, in case a future
version of m4 introduces an option named --default).
m4 understands the following options, grouped by functionality.
Several options control the overall operation of m4:
--helpm4 without reading any input files or performing any other
actions.
--versionm4 without reading any input files or
performing any other actions.
-E--fatal-warnings-i--interactive-em4 interactive. This means that all
output will be unbuffered, and interrupts will be ignored. The
spelling -e exists for compatibility with other m4
implementations, and issues a warning because it may be withdrawn in a
future version of GNU M4.
-P--prefix-builtins-Q--quiet--silent--warn-macro-sequence[=REGEXP]define or
pushdef). Empty matches are ignored; therefore, supplying the
empty string as REGEXP disables any warning. If the optional
REGEXP is not supplied, then the default regular expression is
`\$\({[^}]*}\|[0-9][0-9]+\)' (a literal `$' followed by
multiple digits or by an open brace), since these sequences will
change semantics in the default operation of GNU M4 2.0 (due
to a change in how more than 9 arguments in a macro definition will be
handled, see Arguments). Providing an alternate regular
expression can provide a useful reverse lookup feature of finding
where a macro is defined to have a given definition.
-W REGEXP--word-regexp=REGEXPm4
implementations (see Changeword).
Several options allow m4 to behave more like a preprocessor.
Macro definitions and deletions can be made on the command line, the
search path can be altered, and the output file can track where the
input came from. These features occur with the following options:
-D NAME[=VALUE]--define=NAME[=VALUE]-I DIRECTORY--include=DIRECTORYm4 search DIRECTORY for included files that are not
found in the current working directory. See Search Path, for more
details. This option may be given more than once.
-s--synclinesm4 is used as a
front end to a compiler. Source file name and line number information
is conveyed by directives of the form `#line linenum
"file"', which are inserted as needed into the middle of the
output. Such directives mean that the following line originated or was
expanded from the contents of input file file at line
linenum. The `"file"' part is often omitted when
the file name did not change from the previous directive.
Synchronization directives are always given on complete lines by themselves. When a synchronization discrepancy occurs in the middle of an output line, the associated synchronization directive is delayed until the next newline that does not occur in the middle of a quoted string or comment.
define(`twoline', `1
2')
=>#line 2 "stdin"
=>
changecom(`/*', `*/')
=>
define(`comment', `/*1
2*/')
=>#line 5
=>
dnl no line
hello
=>#line 7
=>hello
twoline
=>1
=>#line 8
=>2
comment
=>/*1
=>2*/
one comment `two
three'
=>#line 10
=>one /*1
=>2*/ two
=>three
goodbye
=>#line 12
=>goodbye
-U NAME--undefine=NAMEThere are some limits within m4 that can be tuned. For
compatibility, m4 also accepts some options that control limits
in other implementations, but which are automatically unbounded (limited
only by your hardware and operating system constraints) in GNU
m4.
-G--traditional-H NUM--hashsize=NUM-L NUM--nesting-limit=NUMThe precise effect of this option might be more correctly associated
with textual nesting than dynamic recursion. It has been useful
when some complex m4 input was generated by mechanical means.
Most users would never need this option. If shown to be obtrusive,
this option (which is still experimental) might well disappear.
This option does not have the ability to break endless
rescanning loops, since these do not necessarily consume much memory
or stack space. Through clever usage of rescanning loops, one can
request complex, time-consuming computations from m4 with useful
results. Putting limitations in this area would break m4 power.
There are many pathological cases: `define(`a', `a')a' is
only the simplest example (but see Compatibility). Expecting GNU
m4 to detect these would be a little like expecting a compiler
system to detect and diagnose endless loops: it is a quite hard
problem in general, if not undecidable!
-B NUM-S NUM-T NUMm4, but
do nothing in this implementation. They may disappear in future
releases, and issue a warning to that effect.
-N NUM--diversions=NUMm4, and were controlling the number of
possible diversions which could be used at the same time. They do nothing,
because there is no fixed limit anymore. They may disappear in future
releases, and issue a warning to that effect.
GNU m4 comes with a feature of freezing internal state
(see Frozen files). This can be used to speed up m4
execution when reusing a common initialization script.
-F FILE--freeze-state=FILE-R FILE--reload-state=FILEFinally, there are several options for aiding in debugging m4
scripts.
-d[FLAGS]--debug[=FLAGS]--debugfile=FILE-o FILE--error-output=FILEdumpdef output, debug messages, and trace output to the
named FILE. Warnings, error messages, and errprint output
are still printed to standard error. If unspecified, debug output goes
to standard error; if empty, debug output is discarded. See Debug Output, for more details. The spellings -o and
--error-output are misleading and inconsistent with other
GNU tools; for now they are silently accepted as synonyms of
--debugfile, but in a future version of M4, using them will
cause a warning to be issued.
-l NUM--arglength=NUM-t NAME--trace=NAMEThe remaining arguments on the command line are taken to be input file names. If no names are present, standard input is read. A file name of - is taken to mean standard input. It is conventional, but not required, for input files to end in `.m4'.
The input files are read in the sequence given. Standard input can be read more than once, so the file name - may appear multiple times on the command line; this makes a difference when input is from a terminal or other special file type. It is an error if an input file ends in the middle of argument collection, a comment, or a quoted string.
The options --define (-D), --undefine (-U), --synclines (-s), and --trace (-t) only take effect after processing input from any file names that occur earlier on the command line. For example, assume the file foo contains:
$ cat foo
bar
The text `bar' can then be redefined over multiple uses of foo:
$ m4 -Dbar=hello foo -Dbar=world foo
=>hello
=>world
If none of the input files invoked m4exit (see M4exit), the
exit status of m4 will be 0 for success, 1 for general failure
(such as problems with reading an input file), and 63 for version
mismatch (see Using frozen files).
If you need to read a file whose name starts with a -, you can specify it as `./-file', or use -- to mark the end of options.
As m4 reads its input, it separates it into tokens. A
token is either a name, a quoted string, or any single character, that
is not a part of either a name or a string. Input to m4 can also
contain comments. GNU m4 does not yet understand
multibyte locales; all operations are byte-oriented rather than
character-oriented (although if your locale uses a single byte
encoding, such as ISO-8859-1, you will not notice a difference).
However, m4 is eight-bit clean, so you can
use non-ascii characters in quoted strings (see Changequote),
comments (see Changecom), and macro names (see Indir), with the
exception of the nul character (the zero byte `'\0'').
A name is any sequence of letters, digits, and the character `_'
(underscore), where the first character is not a digit. m4 will
use the longest such sequence found in the input. If a name has a
macro definition, it will be subject to macro expansion
(see Macros). Names are case-sensitive.
Examples of legal names are: `foo', `_tmp', and `name01'.
m4A quoted string is a sequence of characters surrounded by quote strings, defaulting to ``' and `'', where the nested begin and end quotes within the string are balanced. The value of a string token is the text, with one level of quotes stripped off. Thus
`'
=>
is the empty string, and double-quoting turns into single-quoting.
``quoted''
=>`quoted'
The quote characters can be changed at any time, using the builtin macro
changequote. See Changequote, for more information.
m4 inputComments in m4 are normally delimited by the characters `#'
and newline. All characters between the comment delimiters are ignored,
but the entire comment (including the delimiters) is passed through to
the output—comments are not discarded by m4.
Comments cannot be nested, so the first newline after a `#' ends the comment. The commenting effect of the begin-comment string can be inhibited by quoting it.
$ m4
`quoted text' # `commented text'
=>quoted text # `commented text'
`quoting inhibits' `#' `comments'
=>quoting inhibits # comments
The comment delimiters can be changed to any string at any time, using
the builtin macro changecom. See Changecom, for more
information.
Any character, that is neither a part of a name, nor of a quoted string, nor a comment, is a token by itself. When not in the context of macro expansion, all of these tokens are just copied to output. However, during macro expansion, whitespace characters (space, tab, newline, formfeed, carriage return, vertical tab), parentheses (`(' and `)'), comma (`,'), and dollar (`$') have additional roles, explained later.
m4 copies input to outputAs m4 reads the input token by token, it will copy each token
directly to the output immediately.
The exception is when it finds a word with a macro definition. In that
case m4 will calculate the macro's expansion, possibly reading
more input to get the arguments. It then inserts the expansion in front
of the remaining input. In other words, the resulting text from a macro
call will be read and parsed into tokens again.
m4 expands a macro as soon as possible. If it finds a macro call
when collecting the arguments to another, it will expand the second call
first. This process continues until there are no more macro calls to
expand and all the input has been consumed.
For a running example, examine how m4 handles this input:
format(`Result is %d', eval(`2**15'))
First, m4 sees that the token `format' is a macro name, so
it collects the tokens `(', ``Result is %d'', `,',
and ` ', before encountering another potential macro. Sure
enough, `eval' is a macro name, so the nested argument collection
picks up `(', ``2**15'', and `)', invoking the eval macro
with the lone argument of `2**15'. The expansion of
`eval(2**15)' is `32768', which is then rescanned as the five
tokens `3', `2', `7', `6', and `8'; and
combined with the next `)', the format macro now has all its
arguments, as if the user had typed:
format(`Result is %d', 32768)
The format macro expands to `Result is 32768', and we have another round of scanning for the tokens `Result', ` ', `is', ` ', `3', `2', `7', `6', and `8'. None of these are macros, so the final output is
=>Result is 32768
As a more complicated example, we will contrast an actual code example from the Gnulib project1, showing both a buggy approach and the desired results. The user desires to output a shell assignment statement that takes its argument and turns it into a shell variable by converting it to uppercase and prepending a prefix. The original attempt looks like this:
changequote([,])dnl
define([gl_STRING_MODULE_INDICATOR],
[
dnl comment
GNULIB_]translit([$1],[a-z],[A-Z])[=1
])dnl
gl_STRING_MODULE_INDICATOR([strcase])
=>
=> GNULIB_strcase=1
=>
Oops – the argument did not get capitalized. And although the manual
is not able to easily show it, both lines that appear empty actually
contain two trailing spaces. By stepping through the parse, it is easy
to see what happened. First, m4 sees the token
`changequote', which it recognizes as a macro, followed by
`(', `[', `,', `]', and `)' to form the
argument list. The macro expands to the empty string, but changes the
quoting characters to something more useful for generating shell code
(unbalanced ``' and `'' appear all the time in shell scripts,
but unbalanced `[]' tend to be rare). Also in the first line,
m4 sees the token `dnl', which it recognizes as a builtin
macro that consumes the rest of the line, resulting in no output for
that line.
The second line starts a macro definition. m4 sees the token
`define', which it recognizes as a macro, followed by a `(',
`[gl_STRING_MODULE_INDICATOR]', and `,'. Because an unquoted
comma was encountered, the first argument is known to be the expansion
of the single-quoted string token, or `gl_STRING_MODULE_INDICATOR'.
Next, m4 sees `<NL>', ` ', and ` ', but this
whitespace is discarded as part of argument collection. Then comes a
rather lengthy single-quoted string token, `[<NL> dnl
comment<NL> GNULIB_]'. This is followed by the token
`translit', which m4 recognizes as a macro name, so a nested
macro expansion has started.
The arguments to the translit are found by the tokens `(',
`[$1]', `,', `[a-z]', `,', `[A-Z]', and finally
`)'. All three string arguments are expanded (or in other words,
the quotes are stripped), and since neither `$' nor `1' need
capitalization, the result of the macro is `$1'. This expansion is
rescanned, resulting in the two literal characters `$' and
`1'.
Scanning of the outer macro resumes, and picks up with `[=1<NL> ]', and finally `)'. The collected pieces of expanded text are concatenated, with the end result that the macro `gl_STRING_MODULE_INDICATOR' is now defined to be the sequence `<NL> dnl comment<NL> GNULIB_$1=1<NL> '. Once again, `dnl' is recognized and avoids a newline in the output.
The final line is then parsed, beginning with ` ' and ` ' that are output literally. Then `gl_STRING_MODULE_INDICATOR' is recognized as a macro name, with an argument list of `(', `[strcase]', and `)'. Since the definition of the macro contains the sequence `$1', that sequence is replaced with the argument `strcase' prior to starting the rescan. The rescan sees `<NL>' and four spaces, which are output literally, then `dnl', which discards the text ` comment<NL>'. Next comes four more spaces, also output literally, and the token `GNULIB_strcase', which resulted from the earlier parameter substitution. Since that is not a macro name, it is output literally, followed by the literal tokens `=', `1', `<NL>', and two more spaces. Finally, the original `<NL>' seen after the macro invocation is scanned and output literally.
Now for a corrected approach. This rearranges the use of newlines and whitespace so that less whitespace is output (which, although harmless to shell scripts, can be visually unappealing), and fixes the quoting issues so that the capitalization occurs when the macro `gl_STRING_MODULE_INDICATOR' is invoked, rather then when it is defined.
changequote([,])dnl
define([gl_STRING_MODULE_INDICATOR],
[dnl comment
GNULIB_[]translit([$1], [a-z], [A-Z])=1dnl
])dnl
gl_STRING_MODULE_INDICATOR([strcase])
=> GNULIB_STRCASE=1
The parsing of the first line is unchanged. The second line sees the
name of the macro to define, then sees the discarded `<NL>'
and two spaces, as before. But this time, the next token is
`[dnl comment<NL> GNULIB_[]translit([$1], [a-z],
[A-Z])=1dnl<NL>]', which includes nested quotes, followed by
`)' to end the macro definition and `dnl' to skip the
newline. No early expansion of translit occurs, so the entire
string becomes the definition of the macro.
The final line is then parsed, beginning with two spaces that are
output literally, and an invocation of
gl_STRING_MODULE_INDICATOR with the argument `strcase'.
Again, the `$1' in the macro definition is substituted prior to
rescanning. Rescanning first encounters `dnl', and discards
` comment<NL>'. Then two spaces are output literally. Next
comes the token `GNULIB_', but that is not a macro, so it is
output literally. The token `[]' is an empty string, so it does
not affect output. Then the token `translit' is encountered.
This time, the arguments to translit are parsed as `(',
`[strcase]', `,', ` ', `[a-z]', `,', ` ',
`[A-Z]', and `)'. The two spaces are discarded, and the
translit results in the desired result `STRCASE'. This is
rescanned, but since it is not a macro name, it is output literally.
Then the scanner sees `=' and `1', which are output
literally, followed by `dnl' which discards the rest of the
definition of gl_STRING_MODULE_INDICATOR. The newline at the
end of output is the literal `<NL>' that appeared after the
invocation of the macro.
The order in which m4 expands the macros can be further explored
using the trace facilities of GNU m4 (see Trace).
This chapter covers macro invocation, macro arguments and how macro expansion is treated.
Macro invocations has one of the forms
name
which is a macro invocation without any arguments, or
name(arg1, arg2, ..., argn)
which is a macro invocation with n arguments. Macros can have any number of arguments. All arguments are strings, but different macros might interpret the arguments in different ways.
The opening parenthesis must follow the name directly, with no spaces in between. If it does not, the macro is called with no arguments at all.
For a macro call to have no arguments, the parentheses must be left out. The macro call
name()
is a macro call with one argument, which is the empty string, not a call with no arguments.
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. 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, see Invoking m4) 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, See 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. See 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.
When a name is seen, and it has a macro definition, it will be expanded as a macro.
If the name is followed by an opening parenthesis, the arguments will be collected before the macro is called. If too few arguments are supplied, the missing arguments are taken to be the empty string. However, some builtins are documented to behave differently for a missing optional argument than for an explicit empty string. If there are too many arguments, the excess arguments are ignored. Unquoted leading whitespace is stripped off all arguments, but whitespace generated by a macro expansion or occurring after a macro that expanded to an empty string remains intact. Whitespace includes space, tab, newline, carriage return, vertical tab, and formfeed.
define(`macro', `$1')
=>
macro( unquoted leading space lost)
=>unquoted leading space lost
macro(` quoted leading space kept')
=> quoted leading space kept
macro(
divert `unquoted space kept after expansion')
=> unquoted space kept after expansion
macro(macro(`
')`whitespace from expansion kept')
=>
=>whitespace from expansion kept
macro(`unquoted trailing whitespace kept'
)
=>unquoted trailing whitespace kept
=>
Normally m4 will issue warnings if a builtin macro is called
with an inappropriate number of arguments, but it can be suppressed with
the --quiet command line option (or --silent, or
-Q, see Invoking m4). For user
defined macros, there is no check of the number of arguments given.
$ m4
index(`abc')
error-->m4:stdin:1: Warning: too few arguments to builtin `index'
=>0
index(`abc',)
=>0
index(`abc', `b', `ignored')
error-->m4:stdin:3: Warning: excess arguments to builtin `index' ignored
=>1
$ m4 -Q
index(`abc')
=>0
index(`abc',)
=>0
index(`abc', `b', `ignored')
=>1
Macros are expanded normally during argument collection, and whatever commas, quotes and parentheses that might show up in the resulting expanded text will serve to define the arguments as well. Thus, if foo expands to `, b, c', the macro call
bar(a foo, d)
is a macro call with four arguments, which are `a ', `b', `c' and `d'. To understand why the first argument contains whitespace, remember that unquoted leading whitespace is never part of an argument, but trailing whitespace always is.
It is possible for a macro's definition to change during argument collection, in which case the expansion uses the definition that was in effect at the time the opening `(' was seen.
define(`f', `1')
=>
f(define(`f', `2'))
=>1
f
=>2
It is an error if the end of file occurs while collecting arguments.
hello world
=>hello world
define(
^D
error-->m4:stdin:2: ERROR: end of file in argument list
Each argument has unquoted leading whitespace removed. Within each argument, all unquoted parentheses must match. For example, if foo is a macro,
foo(() (`(') `(')
is a macro call, with one argument, whose value is `() (() ('. Commas separate arguments, except when they occur inside quotes, comments, or unquoted parentheses. See Pseudo Arguments, for examples.
It is common practice to quote all arguments to macros, unless you are sure you want the arguments expanded. Thus, in the above example with the parentheses, the `right' way to do it is like this:
foo(`() (() (')
It is, however, in certain cases necessary (because nested expansion
must occur to create the arguments for the outer macro) or convenient
(because it uses fewer characters) to leave out quotes for some
arguments, and there is nothing wrong in doing it. It just makes life a
bit harder, if you are not careful to follow a consistent quoting style.
For consistency, this manual follows the rule of thumb that each layer
of parentheses introduces another layer of single quoting, except when
showing the consequences of quoting rules. This is done even when the
quoted string cannot be a macro, such as with integers when you have not
changed the syntax via changeword (see Changeword).
The quoting rule of thumb of one level of quoting per parentheses has a nice property: when a macro name appears inside parentheses, you can determine when it will be expanded. If it is not quoted, it will be expanded prior to the outer macro, so that its expansion becomes the argument. If it is single-quoted, it will be expanded after the outer macro. And if it is double-quoted, it will be used as literal text instead of a macro name.
define(`active', `ACT, IVE')
=>
define(`show', `$1 $1')
=>
show(active)
=>ACT ACT
show(`active')
=>ACT, IVE ACT, IVE
show(``active'')
=>active active
When the arguments, if any, to a macro call have been collected, the macro is expanded, and the expansion text is pushed back onto the input (unquoted), and reread. The expansion text from one macro call might therefore result in more macros being called, if the calls are included, completely or partially, in the first macro calls' expansion.
Taking a very simple example, if foo expands to `bar', and bar expands to `Hello', the input
$ m4 -Dbar=Hello -Dfoo=bar
foo
=>Hello
will expand first to `bar', and when this is reread and expanded, into `Hello'.
Macros can be defined, redefined and deleted in several different ways. Also, it is possible to redefine a macro without losing a previous value, and bring back the original value at a later time.
The normal way to define or redefine macros is to use the builtin
define:
Defines name to expand to expansion. If expansion is not given, it is taken to be empty.
The expansion of
defineis void. The macrodefineis recognized only with parameters.
The following example defines the macro foo to expand to the text `Hello World.'.
define(`foo', `Hello world.')
=>
foo
=>Hello world.
The empty line in the output is there because the newline is not
a part of the macro definition, and it is consequently copied to
the output. This can be avoided by use of the macro dnl.
See Dnl, for details.
The first argument to define should be quoted; otherwise, if the
macro is already defined, you will be defining a different macro. This
example shows the problems with underquoting, since we did not want to
redefine one:
define(foo, one)
=>
define(foo, two)
=>
one
=>two
GNU m4 normally replaces only the topmost
definition of a macro if it has several definitions from pushdef
(see Pushdef). Some other implementations of m4 replace all
definitions of a macro with define. See Incompatibilities,
for more details.
As a GNU extension, the first argument to define does
not have to be a simple word.
It can be any text string, even the empty string. A macro with a
non-standard name cannot be invoked in the normal way, as the name is
not recognized. It can only be referenced by the builtins indir
(see Indir) and defn (see Defn).
Arrays and associative arrays can be simulated by using non-standard macro names.
Provide access to entries within an array.
arrayreads the entry at location index, andarray_setassigns value to location index.
define(`array', `defn(format(``array[%d]'', `$1'))')
=>
define(`array_set', `define(format(``array[%d]'', `$1'), `$2')')
=>
array_set(`4', `array element no. 4')
=>
array_set(`17', `array element no. 17')
=>
array(`4')
=>array element no. 4
array(eval(`10 + 7'))
=>array element no. 17
Change the `%d' to `%s' and it is an associative array.
Macros can have arguments. The nth argument is denoted by
$n in the expansion text, and is replaced by the nth actual
argument, when the macro is expanded. Replacement of arguments happens
before rescanning, regardless of how many nesting levels of quoting
appear in the expansion. Here is an example of a macro with
two arguments.
Expands to arg2 followed by arg1, effectively exchanging their order.
define(`exch', `$2, $1')
=>
exch(`arg1', `arg2')
=>arg2, arg1
This can be used, for example, if you like the arguments to
define to be reversed.
define(`exch', `$2, $1')
=>
define(exch(``expansion text'', ``macro''))
=>
macro
=>expansion text
See Quoting Arguments, for an explanation of the double quotes.
(You should try and improve this example so that clients of exch
do not have to double quote; or see Answers).
As a special case, the zeroth argument, $0, is always the name
of the macro being expanded.
define(`test', ``Macro name: $0'')
=>
test
=>Macro name: test
If you want quoted text to appear as part of the expansion text, remember that quotes can be nested in quoted strings. Thus, in
define(`foo', `This is macro `foo'.')
=>
foo
=>This is macro foo.
The `foo' in the expansion text is not expanded, since it is a quoted string, and not a name.
GNU m4 allows the number following the `$' to
consist of one or more digits, allowing macros to have any number of
arguments. The extension of accepting multiple digits is incompatible
with POSIX, and is different than traditional implementations
of m4, which only recognize one digit. Therefore, future
versions of GNU M4 will phase out this feature. To portably
access beyond the ninth argument, you can use the argn macro
documented later (see Shift).
POSIX also states that `$' followed immediately by `{' in a macro definition is implementation-defined. This version of M4 passes the literal characters `${' through unchanged, but M4 2.0 will implement an optional feature similar to sh, where `${11}' expands to the eleventh argument, to replace the current recognition of `$11'. Meanwhile, if you want to guarantee that you will get a literal `${' in output when expanding a macro, even when you upgrade to M4 2.0, you can use nested quoting to your advantage:
define(`foo', `single quoted $`'{1} output')
=>
define(`bar', ``double quoted $'`{2} output'')
=>
foo(`a', `b')
=>single quoted ${1} output
bar(`a', `b')
=>double quoted ${2} output
To help you detect places in your M4 input files that might change in behavior due to the changed behavior of M4 2.0, you can use the --warn-macro-sequence command-line option (see Invoking m4) with the default regular expression. This will add a warning any time a macro definition includes `$' followed by multiple digits, or by `{'. The warning is not enabled by default, because it triggers a number of warnings in Autoconf 2.61 (and Autoconf uses -E to treat warnings as errors), and because it will still be possible to restore older behavior in M4 2.0.
$ m4 --warn-macro-sequence
define(`foo', `$001 ${1} $1')
error-->m4:stdin:1: Warning: definition of `foo' contains sequence `$001'
error-->m4:stdin:1: Warning: definition of `foo' contains sequence `${1}'
=>
foo(`bar')
=>bar ${1} bar
There is a special notation for the number of actual arguments supplied, and for all the actual arguments.
The number of actual arguments in a macro call is denoted by $#
in the expansion text.
define(`nargs', `$#')
=>
nargs
=>0
nargs()
=>1
nargs(`arg1', `arg2', `arg3')
=>3
nargs(`commas can be quoted, like this')
=>1
nargs(arg1#inside comments, commas do not separate arguments
still arg1)
=>1
nargs((unquoted parentheses, like this, group arguments))
=>1
Remember that `#' defaults to the comment character; if you forget quotes to inhibit the comment behavior, your macro definition may not end where you expected.
dnl Attempt to define a macro to just `$#'
define(underquoted, $#)
oops)
=>
underquoted
=>0)
=>oops
The notation $* can be used in the expansion text to denote all
the actual arguments, unquoted, with commas in between. For example
define(`echo', `$*')
=>
echo(arg1, arg2, arg3 , arg4)
=>arg1,arg2,arg3 ,arg4
Often each argument should be quoted, and the notation $@ handles
that. It is just like $*, except that it quotes each argument.
A simple example of that is:
define(`echo', `$@')
=>
echo(arg1, arg2, arg3 , arg4)
=>arg1,arg2,arg3 ,arg4
Where did the quotes go? Of course, they were eaten, when the expanded
text were reread by m4. To show the difference, try
define(`echo1', `$*')
=>
define(`echo2', `$@')
=>
define(`foo', `This is macro `foo'.')
=>
echo1(foo)
=>This is macro This is macro foo..
echo1(`foo')
=>This is macro foo.
echo2(foo)
=>This is macro foo.
echo2(`foo')
=>foo
See Trace, if you do not understand this. As another example of the difference, remember that comments encountered in arguments are passed untouched to the macro, and that quoting disables comments.
define(`echo1', `$*')
=>
define(`echo2', `$@')
=>
define(`foo', `bar')
=>
echo1(#foo'foo
foo)
=>#foo'foo
=>bar
echo2(#foo'foo
foo)
=>#foobar
=>bar'
A `$' sign in the expansion text, that is not followed by anything
m4 understands, is simply copied to the macro expansion, as any
other text is.
define(`foo', `$$$ hello $$$')
=>
foo
=>$$$ hello $$$
If you want a macro to expand to something like `$12', the
judicious use of nested quoting can put a safe character between the
$ and the next character, relying on the rescanning to remove the
nested quote. This will prevent m4 from interpreting the
$ sign as a reference to an argument.
define(`foo', `no nested quote: $1')
=>
foo(`arg')
=>no nested quote: arg
define(`foo', `nested quote around $: `$'1')
=>
foo(`arg')
=>nested quote around $: $1
define(`foo', `nested empty quote after $: $`'1')
=>
foo(`arg')
=>nested empty quote after $: $1
define(`foo', `nested quote around next character: $`1'')
=>
foo(`arg')
=>nested quote around next character: $1
define(`foo', `nested quote around both: `$1'')
=>
foo(`arg')
=>nested quote around both: arg
A macro definition can be removed with undefine:
For each argument, remove the macro name. The macro names must necessarily be quoted, since they will be expanded otherwise.
The expansion of
undefineis void. The macroundefineis recognized only with parameters.
foo bar blah
=>foo bar blah
define(`foo', `some')define(`bar', `other')define(`blah', `text')
=>
foo bar blah
=>some other text
undefine(`foo')
=>
foo bar blah
=>foo other text
undefine(`bar', `blah')
=>
foo bar blah
=>foo bar blah
Undefining a macro inside that macro's expansion is safe; the macro still expands to the definition that was in effect at the `('.
define(`f', ``$0':$1')
=>
f(f(f(undefine(`f')`hello world')))
=>f:f:f:hello world
f(`bye')
=>f(bye)
It is not an error for name to have no macro definition. In that
case, undefine does nothing.
It is possible to rename an already defined macro. To do this, you need
the builtin defn:
Expands to the quoted definition of each name. If an argument is not a defined macro, the expansion for that argument is empty.
If name is a user-defined macro, the quoted definition is simply the quoted expansion text. If, instead, there is only one name and it is a builtin, the expansion is a special token, which points to the builtin's internal definition. This token is only meaningful as the second argument to
define(andpushdef), and is silently converted to an empty string in most other contexts. Combining a builtin with anything else is not supported; a warning is issued and the builtin is omitted from the final expansion.The macro
defnis recognized only with parameters.
Its normal use is best understood through an example, which shows how to
rename undefine to zap:
define(`zap', defn(`undefine'))
=>
zap(`undefine')
=>
undefine(`zap')
=>undefine(zap)
In this way, defn can be used to copy macro definitions, and also
definitions of builtin macros. Even if the original macro is removed,
the other name can still be used to access the definition.
The fact that macro definitions can be transferred also explains why you
should use $0, rather than retyping a macro's name in its
definition:
define(`foo', `This is `$0'')
=>
define(`bar', defn(`foo'))
=>
bar
=>This is bar
Macros used as string variables should be referred through defn,
to avoid unwanted expansion of the text:
define(`string', `The macro dnl is very useful
')
=>
string
=>The macro
defn(`string')
=>The macro dnl is very useful
=>
However, it is important to remember that m4 rescanning is purely
textual. If an unbalanced end-quote string occurs in a macro
definition, the rescan will see that embedded quote as the termination
of the quoted string, and the remainder of the macro's definition will
be rescanned unquoted. Thus it is a good idea to avoid unbalanced
end-quotes in macro definitions or arguments to macros.
define(`foo', a'a)
=>
define(`a', `A')
=>
define(`echo', `$@')
=>
foo
=>A'A
defn(`foo')
=>aA'
echo(foo)
=>AA'
On the other hand, it is possible to exploit the fact that defn
can concatenate multiple macros prior to the rescanning phase, in order
to join the definitions of macros that, in isolation, have unbalanced
quotes. This is particularly useful when one has used several macros to
accumulate text that M4 should rescan as a whole. In the example below,
note how the use of defn on l in isolation opens a string,
which is not closed until the next line; but used on l and
r together results in nested quoting.
define(`l', `<[>')define(`r', `<]>')
=>
changequote(`[', `]')
=>
defn([l])defn([r])
])
=><[>]defn([r])
=>)
defn([l], [r])
=><[>][<]>
Using defn to generate special tokens for builtin macros outside
of expected contexts can sometimes trigger warnings. But most of the
time, such tokens are silently converted to the empty string.
$ m4 -d
defn(`defn')
=>
define(defn(`divnum'), `cannot redefine a builtin token')
error-->m4:stdin:2: Warning: define: invalid macro name ignored
=>
divnum
=>0
len(defn(`divnum'))
=>0
Also note that defn with multiple arguments can only join text
macros, not builtins, although a future version of GNU M4 may
lift this restriction.
$ m4 -d
define(`a', `A')define(`AA', `b')
=>
traceon(`defn', `define')
=>
defn(`a', `divnum', `a')
error-->m4:stdin:3: Warning: cannot concatenate builtin `divnum'
error-->m4trace: -1- defn(`a', `divnum', `a') -> ``A'`A''
=>AA
define(`mydivnum', defn(`divnum', `divnum'))mydivnum
error-->m4:stdin:4: Warning: cannot concatenate builtin `divnum'
error-->m4:stdin:4: Warning: cannot concatenate builtin `divnum'
error-->m4trace: -2- defn(`divnum', `divnum')
error-->m4trace: -1- define(`mydivnum', `')
=>
traceoff(`defn', `define')
=>
It is possible to redefine a macro temporarily, reverting to the
previous definition at a later time. This is done with the builtins
pushdef and popdef:
Analogous to
defineandundefine.These macros work in a stack-like fashion. A macro is temporarily redefined with
pushdef, which replaces an existing definition of name, while saving the previous definition, before the new one is installed. If there is no previous definition,pushdefbehaves exactly likedefine.If a macro has several definitions (of which only one is accessible), the topmost definition can be removed with
popdef. If there is no previous definition,popdefbehaves likeundefine.The expansion of both
pushdefandpopdefis void. The macrospushdefandpopdefare recognized only with parameters.
define(`foo', `Expansion one.')
=>
foo
=>Expansion one.
pushdef(`foo', `Expansion two.')
=>
foo
=>Expansion two.
pushdef(`foo', `Expansion three.')
=>
pushdef(`foo', `Expansion four.')
=>
popdef(`foo')
=>
foo
=>Expansion three.
popdef(`foo', `foo')
=>
foo
=>Expansion one.
popdef(`foo')
=>
foo
=>foo
If a macro with several definitions is redefined with define, the
topmost definition is replaced with the new definition. If it is
removed with undefine, all the definitions are removed,
and not only the topmost one. However, POSIX allows other
implementations that treat define as replacing an entire stack
of definitions with a single new definition, so to be portable to other
implementations, it may be worth explicitly using popdef and
pushdef rather than relying on the GNU behavior of
define.
define(`foo', `Expansion one.')
=>
foo
=>Expansion one.
pushdef(`foo', `Expansion two.')
=>
foo
=>Expansion two.
define(`foo', `Second expansion two.')
=>
foo
=>Second expansion two.
undefine(`foo')
=>
foo
=>foo
Local variables within macros are made with pushdef and
popdef. At the start of the macro a new definition is pushed,
within the macro it is manipulated and at the end it is popped,
revealing the former definition.
It is possible to temporarily redefine a builtin with pushdef
and defn.
Any macro can be called indirectly with indir:
Results in a call to the macro name, which is passed the rest of the arguments args. If name is not defined, an error message is printed, and the expansion is void.
The macro
indiris recognized only with parameters.
This can be used to call macros with computed or “invalid”
names (define allows such names to be defined):
define(`$$internal$macro', `Internal macro (name `$0')')
=>
$$internal$macro
=>$$internal$macro
indir(`$$internal$macro')
=>Internal macro (name $$internal$macro)
The point is, here, that larger macro packages can have private macros
defined, that will not be called by accident. They can only be
called through the builtin indir.
One other point to observe is that argument collection occurs before
indir invokes name, so if argument collection changes the
value of name, that will be reflected in the final expansion.
This is different than the behavior when invoking macros directly,
where the definition that was in effect before argument collection is
used.
$ m4 -d
define(`f', `1')
=>
f(define(`f', `2'))
=>1
indir(`f', define(`f', `3'))
=>3
indir(`f', undefine(`f'))
error-->m4:stdin:4: undefined macro `f'
=>
When handed the result of defn (see Defn) as one of its
arguments, indir defers to the invoked name for whether a
token representing a builtin is recognized or flattened to the empty
string.
$ m4 -d
indir(defn(`defn'), `divnum')
error-->m4:stdin:1: Warning: indir: invalid macro name ignored
=>
indir(`define', defn(`defn'), `divnum')
error-->m4:stdin:2: Warning: define: invalid macro name ignored
=>
indir(`define', `foo', defn(`divnum'))
=>
foo
=>0
indir(`divert', defn(`foo'))
error-->m4:stdin:5: empty string treated as 0 in builtin `divert'
=>
Builtin macros can be called indirectly with builtin:
Results in a call to the builtin name, which is passed the rest of the arguments args. If name does not name a builtin, an error message is printed, and the expansion is void.
The macro
builtinis recognized only with parameters.
This can be used even if name has been given another definition that has covered the original, or been undefined so that no macro maps to the builtin.
pushdef(`define', `hidden')
=>
undefine(`undefine')
=>
define(`foo', `bar')
=>hidden
foo
=>foo
builtin(`define', `foo', defn(`divnum'))
=>
foo
=>0
builtin(`define', `foo', `BAR')
=>
foo
=>BAR
undefine(`foo')
=>undefine(foo)
foo
=>BAR
builtin(`undefine', `foo')
=>
foo
=>foo
The name argument only matches the original name of the builtin,
even when the --prefix-builtins option (or -P,
see Invoking m4) is in effect. This is different
from indir, which only tracks current macro names.
$ m4 -P
m4_builtin(`divnum')
=>0
m4_builtin(`m4_divnum')
error-->m4:stdin:2: undefined builtin `m4_divnum'
=>
m4_indir(`divnum')
error-->m4:stdin:3: undefined macro `divnum'
=>
m4_indir(`m4_divnum')
=>0
Note that indir and builtin can be used to invoke builtins
without arguments, even when they normally require parameters to be
recognized; but it will provoke a warning, and result in a void expansion.
builtin
=>builtin
builtin()
error-->m4:stdin:2: undefined builtin `'
=>
builtin(`builtin')
error-->m4:stdin:3: Warning: too few arguments to builtin `builtin'
=>
builtin(`builtin',)
error-->m4:stdin:4: undefined builtin `'
=>
Macros, expanding to plain text, perhaps with arguments, are not quite enough. We would like to have macros expand to different things, based on decisions taken at run-time. For that, we need some kind of conditionals. Also, we would like to have some kind of loop construct, so we could do something a number of times, or while some condition is true.
There are two different builtin conditionals in m4. The first is
ifdef:
If name is defined as a macro,
ifdefexpands to string-1, otherwise to string-2. If string-2 is omitted, it is taken to be the empty string (according to the normal rules).The macro
ifdefis recognized only with parameters.
ifdef(`foo', ``foo' is defined', ``foo' is not defined')
=>foo is not defined
define(`foo', `')
=>
ifdef(`foo', ``foo' is defined', ``foo' is not defined')
=>foo is defined
ifdef(`no_such_macro', `yes', `no', `extra argument')
error-->m4:stdin:4: Warning: excess arguments to builtin `ifdef' ignored
=>no
The other conditional, ifelse, is much more powerful. It can be
used as a way to introduce a long comment, as an if-else construct, or
as a multibranch, depending on the number of arguments supplied:
Used with only one argument, the
ifelsesimply discards it and produces no output.If called with three or four arguments,
ifelseexpands into equal, if string-1 and string-2 are equal (character for character), otherwise it expands to not-equal. A final fifth argument is ignored, after triggering a warning.If called with six or more arguments, and string-1 and string-2 are equal,
ifelseexpands into equal-1, otherwise the first three arguments are discarded and the processing starts again.The macro
ifelseis recognized only with parameters.
Using only one argument is a common m4 idiom for introducing a
block comment, as an alternative to repeatedly using dnl. This
special usage is recognized by GNU m4, so that in this
case, the warning about missing arguments is never triggered.
ifelse(`some comments')
=>
ifelse(`foo', `bar')
error-->m4:stdin:2: Warning: too few arguments to builtin `ifelse'
=>
Using three or four arguments provides decision points.
ifelse(`foo', `bar', `true')
=>
ifelse(`foo', `foo', `true')
=>true
define(`foo', `bar')
=>
ifelse(foo, `bar', `true', `false')
=>true
ifelse(foo, `foo', `true', `false')
=>false