19.1.1 m4 is greedy

The m4 program is greedy. That is, if a macro is already defined, its value will replace its name in the second declaration. Consider this input file:

define(A,B)
define(A,C)
A B

Here, the first line assigns the value B to the macro named A. The second line notices that A is a define macro, so m4 replaces that A with B and then defines B as having the value C. The output of this file, after processing with m4, will be:

C C

To prevent this kind of greedy behavior (and to prevent the confusion it can create), you may quote an item to prevent m4 from interpreting it. zzz You quote with m4 by surrounding each item with left and right single quotes:

define(A,B)
define(`A',C)
A B

Here, the first line defines A as B as before. But the second line no longer sees A as a macro. Instead, the single quotes allow A to be redefined as C. So the output is now:

C B

Although it is not strictly necessary, we recommend that all macro and value pairs be quoted. The above should generally be expressed like this:

define(`A',`B')      
define(`A',`C')   
A B

This is the form that we use when illustrating m4 throughout this book.

19.1.2 m4 and dnl

Another problem with m4 is that it replaces its commands with empty lines. The above define commands, for example, will actually print like this:

 a blank line
                            a blank line
A B

To suppress this insertion of blank lines, you can use the special m4 command dnl (for Delete through New Line). That command looks like this:

define(`A',`B')dnl
define(`A',`C')dnl
A B

You can use dnl to remove blank lines where they might prove inconvenient or unsightly in a configuration file.

19.1.3 m4 and arguments

When an m4 macro name is immediately followed by a right parenthesis, it is treated like a function call. Arguments given to it in that role are used to replace $digit expressions in the original definition. For example, suppose the macro CONCAT is defined like this:

define(`CONCAT',`$1$2$3')dnl

and then later used like this:

CONCAT(`host', `.', `domain')

The result will be that host will replace $1, the dot will replace $2, and the domain will replace $3, all jammed tightly together just as `$1$2$3' were:

host.domain

Macro arguments are used to create such techniques as FEATURE() and OSTYPE(), which are described later in this chapter.

19.1.4 m4 diversions

One of the m4 program's strengths is its ability to divide its input into different parts and to later reassemble them in a more logical fashion. Consider, for example, the desire to output all options together. One way to do this is with the m4 program's divert and undivert commands, for example,

divert(1)dnl
O ALIASFILE=/etc/aliases
divert(2)dnl
Pfirst-class=0
divert(1)dnl
O OperatorChars=.:%@!^/[]+
undivert(1)dnl
undivert(2)dnl

Here, the divert(1) causes all subsequent lines (up to the next divert or next undivert) to be held in a buffer numbered one. Buffer one will hold all the options. The second divert switches to buffer two, which is used to hold priorities. The third divert switches back to buffer one.

The undivert(1) causes all the options gathered in buffer one to be output, and the undivert(2) causes the priorities to be output. The result looks like this:

O ALIASFILE=/etc/aliases
O OperatorChars=.:%@!^/[]+
Pfirst-class=0

The diversions used by sendmail's m4 technique are listed in Table 19.1. In general, the macros listed should be used in place of diversion numbers because the meaning of those numbers may be changed in future versions of sendmail.