[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
1.1 Introduction to m4 | ||
1.2 Historical references | ||
1.3 Problems and bugs | ||
1.4 Using this manual |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
m4
m4
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 section Compatibility with other versions of m4
, 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GPM
was an important ancestor of m4
. See
C. Strachey: “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.
More bug fixes were incorporated in 2007, with releases 1.4.9 and
1.4.10. Eric continued with some portability fixes for 1.4.11 and
1.4.12 in 2008, 1.4.13 in 2009, 1.4.14 and 1.4.15 in 2010, and 1.4.16 in
2011.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.16 |
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 in m4
, 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
.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by root on March 13, 2013 using texi2html 1.82.