Web Paging - m4 macros

This page highlights the built-in macros implemented by a standard m4 preprocessor (SysV variety). All macros are of the form name(arg1, arg2, ..., argn). Any whitespace before an argument is ignored. The macro name and the open parenthesis `(' must NOT have any intervening whitespace.

m4 makes available the following built-in macros. These macros may be redefined, but once this is done the original meaning is lost. Their values are null unless otherwise stated.

Note that to display the m4 macros here in this web page, the macros were "disabled" by inserting pairs of quotes (`') in the middle of the macro names, thus making them unrecognizable by the m4 preprocessor.

---

 
     define          changecom       eval            sysval     
     undefine        divert          len             maketemp   
     defn            undivert        index           m4exit     
     pushdef         divnum          substr          m4wrap     
     popdef          dnl             translit        errprint   
     ifdef           ifelse          include         dumpdef    
     shift           incr            sinclude        traceon    
     changequote     decr            syscmd          traceoff   

GNU m4 extensions

     format          regexp          patsubst        esyscmd     
     builtin         indir

Modified GNU m4

     redirect        rednum

---

define

the second argument is installed as the value of the macro whose name is the first argument. Each occurrence of $n in the replacement text, where n is a digit, is replaced by the n-th argument. Argument 0 is the name of the macro; missing arguments are replaced by the null string; $# is replaced by the number of arguments; $* is replaced by a list of all the arguments separated by commas; $@ is like $*, but each argument is quoted (with the current quotes).

undefine

removes the definition of the macro named in its argument.

defn

returns the quoted definition of its argument(s). It is useful for renaming macros, especially built-ins.

pushdef

like define, but saves any previous definition.

popdef

removes current definition of its argument(s), exposing the previous one, if any.

ifdef

if the first argument is defined, the value is the second argument, otherwise the third. If there is no third argument, the value is null. The word unix is predefined.

shift

returns all but its first argument. The other arguments are quoted and pushed back with commas in between. The quoting nullifies the effect of the extra scan that will subsequently be performed.

changequote

change quote symbols to the first and second arguments. The symbols may be up to five characters long for the GNU version. changequote without arguments restores the original values (that is, `').

changecom

change left and right comment markers from the default # and new-line. With no arguments, the comment mechanism is effectively disabled. With one argument, the left marker becomes the argument and the right marker becomes new-line. With two arguments, both markers are affected. Comment markers may be up to five characters long.

divert

m4 maintains 10 output streams, numbered 0-9. The final output is the concatenation of the streams in numerical order; initially stream 0 is the current stream. The divert macro changes the current output stream to its (digit- string) argument. Output diverted to a stream other than 0 through 9 is discarded.

undivert

causes immediate output of text from diversions named as arguments, or all diversions if no argument. Text may be undiverted into another diversion. Undiverting discards the diverted text.

divnum

returns the value of the current output stream.

dnl

reads and discards characters up to and including the next new-line.

ifelse

has three or more arguments. If the first argument is the same string as the second, then the value is the third argument. If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6 and 7. Otherwise, the value is either the fourth string, or, if it is not present, null.

incr

returns the value of its argument incremented by 1. The value of the argument is calculated by interpreting an initial digit-string as a decimal number.

decr

returns the value of its argument decremented by 1.

eval

evaluates its argument as an arithmetic expression, using 32-bit arithmetic. Operators include +, -, *, /, %, ** (exponentiation), bitwise &, |, ^, and ~; relationals; parentheses. Octal and hex numbers may be specified as in C. The second argument specifies the radix for the result; the default is 10. The third argument may be used to specify the minimum number of digits in the result.

len

returns the number of characters in its argument.

index

returns the position in its first argument where the second argument begins (zero origin), or -1 if the second argument does not occur.

substr

returns a substring of its first argument. The second argument is a zero origin number selecting the first character; the third argument indicates the length of the substring. A missing third argument is taken to be large enough to extend to the end of the first string.

translit

transliterates the characters in its first argument from the set given by the second argument to the set given by the third. No abbreviations are permitted.

include

returns the contents of the file named in the argument.

sinclude

is identical to include, except that it says nothing if the file is inaccessible.

syscmd

executes the UNIX System command given in the first argument. No value is returned.

sysval

is the return code from the last call to syscmd.

maketemp

fills in a string of XXXXX in its argument with the current process ID.

m4exit

causes immediate exit from m4. Argument 1, if given, is the exit code; the default is 0.

m4wrap

argument 1 will be pushed back at final EOF; example: m4wrap(`cleanup()')

errprint

prints its argument on the diagnostic output file.

dumpdef

prints current names and definitions, for the named items, or for all if no arguments are given.

traceon

with no arguments, turns on tracing for all macros (including built-ins). Otherwise, turns on tracing for named macros.

traceoff

turns off trace globally and for any macros specified. Macros specifically traced by traceon can be untraced only by specific calls to traceoff.

format

Formatted output can be made with `format':

format(FORMAT-STRING, ...)

which works much like the C function `printf'. The first argument is a format string, which can contain `%' specifications, and the expansion of `format' is the formatted string. This is a GNU extension.

regexp

Searching for regular expressions is done with the built-in `regexp':

regexp(STRING, REGEXP, opt REPLACEMENT)

which searches for REGEXP in STRING. The syntax for regular expressions is the same as in GNU Emacs.

If REPLACEMENT is omitted, `regexp' expands to the index of the first match of REGEXP in STRING. If REGEXP does not match anywhere in STRING, it expands to -1. This is a GNU extension.

patsubst

Global substitution in a string is done by `patsubst':

patsubst(STRING, REGEXP, opt REPLACEMENT)

which searches STRING for matches of REGEXP, and substitutes REPLACEMENT for each match. The syntax for regular expressions is the same as in GNU Emacs.

The parts of STRING that are not covered by any match of REGEXP are copied to the expansion. Whenever a match is found, the search proceeds from the end of the match, so a character from STRING will never be substituted twice. If REGEXP matches a string of zero length, the start position for the search is incremented, to avoid infinite loops.

When a replacement is to be made, REPLACEMENT is inserted into the expansion, with `\N' substituted by the text matched by the Nth parenthesized sub-expression of REGEXP, `\&' being the text the entire regular expression matched.

The REPLACEMENT argument can be omitted, in which case the text matched by REGEXP is deleted. This is a GNU extension.

esyscmd

If you want `m4' to read the output of a UNIX command, use `esyscmd':

esyscmd(SHELL-COMMAND)

which expands to the standard output of the shell command SHELL-COMMAND.

Prior to executing the command, `m4' flushes its output buffers. The default standard input and error output of SHELL-COMMAND are the same as those of `m4'. The error output of SHELL-COMMAND is not a part of the expansion: it will appear along with the error output of `m4'. This is a GNU extension.

builtin

Built-in macros can be called indirectly with `builtin':

builtin(NAME, ...)

which results in a call to the built-in NAME, which is passed the rest of the arguments. This can be used, if NAME has been given another definition that has covered the original.

The macro `builtin' is recognized only with parameters. This is a GNU extension.

indir

Any macro can be called indirectly with `indir':

indir(NAME, ...)

which results in a call to the macro NAME, which is passed the rest of the arguments. This can be used to call macros with "illegal" names (`define' allows such names to be defined)

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'. This is a GNU extension.

redirect

redirects the output to the specified file descriptor ranging from 1 through 9. If the argument is not in this range then redirection defaults to stdout (or equal to 1). This has no effect if the output has been diverted and any redirection must be to a valid opened file or else it's lost. Only two file descriptors are defined by default, that is stdout = 1 and stderr = 2. Other file descriptors can be opened with the Bourne shell "n>filename" commandline redirection. This is a special macro only available through the Modified GNU m4.

rednum

gives the value of the current redirection file descriptor number, an integer value ranging from 1 to 9. This is a special macro only available through the Modified GNU m4.