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→’. 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.19

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.