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