1.\" 2.\" @(#) $Id$ 3.\" 4.Dd January 26, 1993 5.Dt m4 1 6.Os 7.Sh NAME 8.Nm m4 9.Nd macro language processor 10.Sh SYNOPSIS 11.Nm m4 12.Oo 13.Fl D Ns Ar name Ns Op Ar =value 14.Oc 15.Op Fl U Ns Ar name 16.Op Ar filename 17\|.\|.\|. 18.Sh DESCRIPTION 19The 20.Nm m4 21utility is a macro processor that can be used as a front end to any 22language (e.g., C, ratfor, fortran, lex, and yacc). 23Each of the argument files is processed in order. 24If there are no files, or if a filename is \`-\', the standard input is read. 25The processed text is sent to the standard output. 26.Pp 27Macro calls have the form name(argument1[, argument2, ...,] argumentN). 28.Pp 29There cannot be any space following the macro name and the open 30parentheses '('. If the macro name is not followed by an open 31parentheses it is processed with no arguments. 32.Pp 33Macro names consist of a leading alphabetic or underscore 34possibly followed by alphanumeric or underscore characters, therefore 35valid macro names match this pattern [a-zA-Z_][a-zA-Z0-9_]*. 36.Pp 37In arguments to macros, leading unquoted space, tab and newline 38characters are ignored. To quote strings use left and right single 39quotes (e.g., ` this is a string with a leading space'). You can change 40the quote characters with the changequote built-in macro. 41.Pp 42The options are as follows: 43.Bl -tag -width "-Dname[=value]xxx" 44.It Fl D Ns Ar name Ns Oo 45.Ar =value 46.Oc 47Define the symbol 48.Ar name 49to have some value (or NULL). 50.It Fl "U" Ns Ar "name" 51Undefine the symbol 52.Ar name . 53.El 54.Sh SYNTAX 55.Nm m4 56provides the following built-in macros. They may be 57redefined, loosing their original meaning. 58Return values are NULL unless otherwise stated. 59.Bl -tag -width changequotexxx 60.It changecom 61Change the start and end comment sequences. The default is 62the pound sign `#' and the newline character. With no arguments 63comments are turned off. The maximum length for a comment marker is 64five characters. 65.It changequote 66Defines the quote symbols to be the first and second arguments. 67The symbols may be up to five characters long. If no arguments are 68given it restores the default open and close single quotes. 69.It decr 70Decrements the argument by 1. The argument must be a valid numeric string. 71.It define 72Define a new macro named by the first argument to have the 73value of the second argument. Each occurrence of $n (where n 74is 0 through 9) is replaced by the n'th argument. $0 is the name 75of the calling macro. Undefined arguments are replaced by a 76NULL string. $# is replaced by the number of arguments; $* 77is replaced by all arguments comma separated; $@ is the same 78as $* but all arguments are quoted against further expansion. 79.It defn 80Returns the quoted definition for each argument. This can be used to rename 81macro definitions (even for built-in macros). 82.It divert 83There are 10 output queues (numbered 0-9). 84At the end of processing 85.Nm m4 86concatenates all the queues in numerical order to produce the 87final output. Initially the output queue is 0. The divert 88macro allows you to select a new output queue (an invalid argument 89passed to divert causes output to be discarded). 90.It divnum 91Returns the current output queue number. 92.It dnl 93Discard input characters up to and including the next newline. 94.It dumpdef 95Prints the names and definitions for the named items, or for everything 96if no arguments are passed. 97.It errprint 98Prints the first argument on the standard error output stream. 99.It eval 100Computes the first argument as an arithmetic expression using 32-bit 101arithmetic. Operators are the standard C ternary, arithmetic, logical, 102shift, relational, bitwise, and parentheses operators. You can specify 103octal, decimal, and hexadecimal numbers as in C. The second argument (if 104any) specifies the radix for the result and the third argument (if 105any) specifies the minimum number of digits in the result. 106.It expr 107This is an alias for eval. 108.It ifdef 109If the macro named by the first argument is defined then return the second 110argument, otherwise the third. If there is no third argument, 111the value is NULL. The word `unix' is predefined. 112.It ifelse 113If the first argument matches the second argument then ifelse returns 114the third argument. If the match fails the three arguments are 115discarded and the next three arguments are used until there is 116zero or one arguments left, either this last argument or NULL is 117returned if no other matches were found. 118.It include 119Returns the contents of the file specified in the first argument. 120Include aborts with an error message if the file cannot be included. 121.It incr 122Increments the argument by 1. The argument must be a valid numeric string. 123.It index 124Returns the index of the second argument in the first argument (e.g., 125index(the quick brown fox jumped, fox) returns 16). If the second 126argument is not found index returns -1. 127.It len 128Returns the number of characters in the first argument. Extra arguments 129are ignored. 130.It m4exit 131Immediately exits with the return value specified by the first argument, 1320 if none. 133.It m4wrap 134Allows you to define what happens at the final EOF, usually for cleanup 135purposes (e.g., m4wrap("cleanup(tempfile)") causes the macro cleanup to 136invoked after all other processing is done.) 137.It maketemp 138Translates the string XXXXX in the first argument with the current process 139ID leaving other characters alone. This can be used to create unique 140temporary file names. 141.It paste 142Includes the contents of the file specified by the first argument without 143any macro processing. Aborts with an error message if the file cannot be 144included. 145.It popdef 146Restores the pushdef'ed definition for each argument. 147.It pushdef 148Takes the same arguments as define, but it saves the definition on a 149stack for later retrieval by popdef. 150.It shift 151Returns all but the first argument, the remaining arguments are 152quoted and pushed back with commas in between. The quoting 153nullifies the effect of the extra scan that will subsequently be 154performed. 155.It sinclude 156Similar to include, except it ignores any errors. 157.It spaste 158Similar to paste, except it ignores any errors. 159.It substr 160Returns a substring of the first argument starting at the offset specified 161by the second argument and the length specified by the third argument. 162If no third argument is present it returns the rest of the string. 163.It syscmd 164Passes the first argument to the shell. Nothing is returned. 165.It sysval 166Returns the return value from the last syscmd. 167.It translit 168Transliterate the characters in the first argument from the set 169given by the second argument to the set given by the third. You cannot 170use 171.Xr tr 1 172style abbreviations. 173.It undefine 174Removes the definition for the macro specified by the first argument. 175.It undivert 176Flushes the named output queues (or all queues if no arguments). 177.It unix 178A pre-defined macro for testing the OS platform. 179.El 180.Sh AUTHOR 181Ozan Yigit <oz@sis.yorku.ca> and Richard A. O'Keefe (ok@goanna.cs.rmit.OZ.AU) 182