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 traceoffGNU m4 extensionsformat regexp patsubst esyscmd builtin indirModified GNU m4redirect 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':
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.format(FORMAT-STRING, ...)
- regexp
- Searching for regular expressions is done with the built-in `regexp':
which searches for REGEXP in STRING. The syntax for regular expressions is the same as in GNU Emacs.regexp(STRING, REGEXP, opt REPLACEMENT)
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':
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.patsubst(STRING, REGEXP, opt REPLACEMENT)
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':
which expands to the standard output of the shell command SHELL-COMMAND.esyscmd(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':
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.builtin(NAME, ...)
The macro `builtin' is recognized only with parameters. This is a GNU extension.
- indir
- Any macro can be called indirectly with `indir':
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)indir(NAME, ...)
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.
Last Modified:
Brought to you by: R.K. Owen,Ph.D.
This page is http://owen.sj.ca.us/rkowen/howto/webpaging/m4.html