COHERENT manpages
This page displays the COHERENT manpage for m4 [Macro processor].
List of available manpages
Index
m4 -- Command Macro processor m4 [file ...] The command m4 processes macros. It allows you to define strings for which m4 is to search, and strings to replace them; m4 then opens file, reads its contents, replaces each macro with its specified replacement string, and writes the results into the standard output stream. m4 can also manipulate files, make conditional decisions, select substrings, and perform arithmetic. The tutorial Introduction to the m4 Macro Processor introduces m4 in detail. m4 reads its files in the order given; if no file is named, then it reads the standard input stream. The file name `-' indicates the standard input. m4 copies input to output until it finds a potential macro. A macro is a string of alphanumerics (letters, digits, or underscores) that begins with a non-digit character and is surrounded by non-alphanumerics. If m4 does not recognize the macro, it simply copies it to the output and continues processing. If m4 recognizes the macro and the next character is a left parenthesis `(', an argument set follows: macro(arg1,..., argn) The arguments are collected by processing them in the same manner as other text (thus, an arguments may itself be another macro), and resulting output text is diverted into storage. m4 stores up to nine arguments; any more will be processed but not saved. An argument set consists of strings of text separated by commas (commas inside quotation marks or parentheses do not terminate an argument), and must contain balanced parentheses that are free of quotation marks (i.e., that are unquoted). m4 strips arguments of unquoted leading space (blanks, tabs, newline characters). m4 then removes the macro and its optional argument set from the input stream, processes them, and replaces them in the input stream with the resulting value. The value becomes the next piece of text to be read. Quotation marks, of the form ` ', inhibit the recognition of macro. m4 strips off one level of quotation marks when it encounters them (quotation marks are nestable). Thus, `macro' is not processed, but is changed to macro and passed on. m4 determines the value of a user-defined macro by taking the text that constitutes the macro's definition and replacing any occurrence within that text of `$n' (where n is `0' through `9') with the text of the nth argument. Argument 0 is the macro itself. m4 recognizes the following predefined macros: changequote[([openquote],[closequote])] Changes the quotation characters. Missing arguments default to ` for open or ' for close. Quotation characters will not nest if they are defined to be the same character. Value is null. decr[(number)] Decrement number (default, 0) by one and returns resulting value. define(macro,definition) Define or redefine macro. If a predefined macro is redefined, its original definition is irrecoverably lost. Value is null. divert[(n)] Redirects output to output stream n (default is zero). The standard output is zero, and one through nine are maintained as temporary files. Any other n results in output being thrown away until the next divert macro. Value is null. divnum Value is current output stream number. dnl Delete to newline: removes all characters from the input stream up to and including the next newline. Value is null. dumpdef[(macros)] Value is quoted definitions of all macros specified, or names and definitions of all defined macros if no arguments. errprint(text) Print text on standard error file. Value is null. eval(expression) Value is a number that is the value of evaluated expression. It recognizes, in order of decreasing precedence: parentheses, **, unary + -, * / %, binary + -, relations, and logicals. Arithmetic is performed in longs. ifdef(macro,defvalue,undefvalue) Return defvalue if macro is defined, and undefvalue if not. ifelse(arg1,arg2,arg3...) Compares arg1 and arg2. If they are the same, returns arg3. If not, and arg4 is the last argument, return arg4. Otherwise, the process repeats, comparing arg4 and arg5, and so on. Like other m4 macros, this takes a maximum of nine arguments. include(file) Value is the entire contents of the file argument. If file is not accessible, a fatal error results. incr[(number)] Increments given number (default, zero) by one and returns resulting value. index(text,pattern) Value is a number corresponding to position of pattern in text. If pattern does not occur in text, value is -1. len(text) Value is a number that corresponds to length of text. maketemp(filenameXXXXXX) Value is filename with last six characters, usually XXXXXX, replaced with current process id and a single letter. Same as the COHERENT system call mktemp(). sinclude(file) Value is the entire contents of file. If file is not accessible, return null and continue processing. substr(text[,start[,count]]) Value is a substring of text. start may be left-oriented (nonnegative) or right-oriented (negative). count specifies how many characters to the right (if positive) or to the left (if negative) to return. If absent, it is assumed to be large and of the same sign as start. If start is omitted, it is assumed to be zero if count is positive or omitted, or -1 if count is negative. syscmd(command) Pass command to the shell for execution. Value is null. Same as system call system. translit(text,characters[,replacements]) Replaces characters in text with the corresponding characters from replacements. If the replacements is absent or too short, replace characters with a null character. Value is text with specified replacements. undefine(macro) Remove macro definition. Value is null. If a predefined macro is redefined, its original definition is irrecoverably lost. undivert[(stream[,...])] Dumps each specified stream into the current output stream. With no arguments, undivert dumps all output streams in numeric order. m4 will not dump any output stream into itself. At the end of processing, m4 automatically dumps all diverted text to standard output in numeric order. Value is null. See Also commands, mktemp(), system Introduction to the m4 Macro Processor