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