[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 1. Introduction and preliminaries

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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 1.1 Introduction to `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] | [ ? ]

## 1.2 Historical references

`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 frontend 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.

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] | [ ? ]

## 1.3 Problems and bugs

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 (Internet) 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] | [ ? ]

## 1.4 Using this manual

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-->'`. Thus

    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 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!

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.,

Composite: example (string, [count = ``1'`], [argument]…)

  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 April, 16 2008 using texi2html 1.76.