1.\" $NetBSD: m4.1,v 1.14 2002/02/08 01:36:27 ross Exp $ 2.\" @(#) $OpenBSD: m4.1,v 1.23 2001/09/29 11:56:18 espie Exp $ 3.\" 4.\" 5.Dd January 26, 1993 6.Dt M4 1 7.Os 8.Sh NAME 9.Nm m4 10.Nd macro language processor 11.Sh SYNOPSIS 12.Nm "" 13.Op Fl Pg 14.Oo 15.Fl D Ns Ar name Ns Op Ar =value 16.Oc 17.Op Fl I Ar dirname 18.Op Fl U Ns Ar name 19.Op Fl d Ar flags 20.Op Fl o Ar trfile 21.Op Fl t Ar name 22.Sh DESCRIPTION 23The 24.Nm 25utility is a macro processor that can be used as a front end to any 26language (e.g., C, ratfor, fortran, lex, and yacc). 27.Nm 28reads from the standard input and writes 29the processed text to the standard output. 30.Pp 31Macro calls have the form name(argument1[, argument2, ..., argumentN]). 32.Pp 33There cannot be any space following the macro name and the open 34parenthesis 35.Pq Ql ( . 36If the macro name is not followed by an open 37parenthesis it is processed with no arguments. 38.Pp 39Macro names consist of a leading alphabetic or underscore 40possibly followed by alphanumeric or underscore characters, e.g., 41valid macro names match the pattern 42.Dq [a-zA-Z_][a-zA-Z0-9_]* . 43.Pp 44In arguments to macros, leading unquoted space, tab, and newline 45.Pq Ql \en 46characters are ignored. 47To quote strings, use left and right single 48quotes (e.g., 49.Sq \ this is a string with a leading space ) . 50You can change the quote characters with the 51.Ic changequote 52built-in macro. 53.Pp 54Most built-ins don't make any sense without arguments, and hence are not 55recognized as special when not followed by an open parenthesis. 56.Pp 57The options are as follows: 58.Bl -tag -width "-Dname[=value]xxx" 59.It Fl D Ns Ar name Ns Oo 60.Ar =value 61.Oc 62Define the symbol 63.Ar name 64to have some value (or 65.Dv NULL ) . 66.It Fl I Ar "dirname" 67Add directory 68.Ar dirname 69to the include path. 70.It Fl P 71Prefixes all 72.Nm 73builtin macros with the string 74.Ql m4_ . 75This changes the macro names 76.Ql dnl 77to 78.Ql m4_dnl , 79.Ql index 80to 81.Ql m4_index , 82and so forth. 83.It Fl "U" Ns Ar "name" 84Undefine the symbol 85.Ar name . 86.It Fl d Ar "flags" 87Set trace flags. 88.Ar flags 89may hold the following: 90.Bl -tag -width Ds 91.It Ar a 92print macro arguments. 93.It Ar c 94print macro expansion over several lines. 95.It Ar e 96print result of macro expansion. 97.It Ar f 98print filename location. 99.It Ar l 100print line number. 101.It Ar q 102quote arguments and expansion with the current quotes. 103.It Ar t 104start with all macros traced. 105.It Ar x 106number macro expansions. 107.It Ar V 108turn on all options. 109.El 110.Pp 111By default, trace is set to 112.Qq eq . 113.It Fl g 114Activate GNU-m4 compatibility mode. 115In this mode, changequote with 116two empty parameters deactivates quotes, translit handles simple character 117ranges (e.g., a-z), regular expressions mimic emacs behavior, 118and the number of diversions is unlimited. 119.It Fl o Ar trfile 120Specify the tracing output file for 121.Fl t ; 122tracing defaults to printing to 123.Ql stderr . 124.It Fl t Ar macro 125Turn tracing on for 126.Ar macro . 127.El 128.Sh SYNTAX 129.Nm 130provides the following built-in macros. 131They may be redefined, losing their original meaning. 132Return values are null unless otherwise stated. 133.Bl -tag -width changequotexxx 134.It Ic builtin 135Calls a built-in by its name, overriding possible redefinitions. 136.It Ic changecom 137Change the start and end comment sequences. 138The default is the pound sign 139.Pq Ql # 140and the newline character. 141With no arguments comments are turned off. 142The maximum length for a comment marker is five characters. 143.It Ic changequote 144Defines the quote symbols to be the first and second arguments. 145The symbols may be up to five characters long. 146If no arguments are 147given it restores the default open and close single quotes. 148.It Ic decr 149Decrements the argument by 1. 150The argument must be a valid numeric string. 151.It Ic define 152Define a new macro named by the first argument to have the 153value of the second argument. 154Each occurrence of 155.Ql $n 156(where 157.Ar n 158is 0 through 9) is replaced by the 159.Ar n Ns 'th 160argument. 161.Ql $0 162is the name of the calling macro. 163Undefined arguments are replaced by a null string. 164.Ql $# 165is replaced by the number of arguments; 166.Ql $* 167is replaced by all arguments comma separated; 168.Ql $@ 169is the same as 170.Ql $* 171but all arguments are quoted against further expansion. 172.It Ic defn 173Returns the quoted definition for each argument. 174This can be used to rename 175macro definitions (even for built-in macros). 176.It Ic divert 177There are 10 output queues (numbered 0-9). 178At the end of processing 179.Nm 180concatenates all the queues in numerical order to produce the 181final output. 182Initially the output queue is 0. 183The divert 184macro allows you to select a new output queue (an invalid argument 185passed to divert causes output to be discarded). 186.It Ic divnum 187Returns the current output queue number. 188.It Ic dnl 189Discard input characters up to and including the next newline. 190.It Ic dumpdef 191Prints the names and definitions for the named items, or for everything 192if no arguments are passed. 193.It Ic errprint 194Prints the first argument on the standard error output stream. 195.It Ic esyscmd 196Pass its first argument to a shell and returns the shell's standard output. 197Note that the shell shares its standard input and standard error with 198.Nm 199.It Ic eval 200Computes the first argument as an arithmetic expression using 32-bit 201arithmetic. 202Operators are the standard C ternary, arithmetic, logical, 203shift, relational, bitwise, and parentheses operators. 204You can specify 205octal, decimal, and hexadecimal numbers as in C. 206The second argument (if any) 207specifies the radix for the result and the third argument (if any) 208specifies the minimum number of digits in the result. 209.It Ic expr 210This is an alias for 211.Ic eval . 212.It Ic ifdef 213If the macro named by the first argument is defined then return the second 214argument, otherwise the third. 215If there is no third argument, the value is 216.Dv NULL . 217The word 218.Qq unix 219is predefined. 220.It Ic ifelse 221If the first argument matches the second argument then 222.Ic ifelse 223returns 224the third argument. 225If the match fails the three arguments are 226discarded and the next three arguments are used until there is 227zero or one arguments left, either this last argument or 228.Dv NULL 229is returned if no other matches were found. 230.It Ic include 231Returns the contents of the file specified in the first argument. 232If the file is not found as is, look through the include path: 233first the directories specified with 234.Fl I 235on the command line, then the environment variable 236.Ev M4PATH , 237as a colon-separated list of directories. 238Include aborts with an error message if the file cannot be included. 239.It Ic incr 240Increments the argument by 1. 241The argument must be a valid numeric string. 242.It Ic index 243Returns the index of the second argument in the first argument (e.g., 244.Ic index(the quick brown fox jumped, fox) 245returns 16). 246If the second 247argument is not found index returns \-1. 248.It Ic indir 249Indirectly calls the macro whose name is passed as the first arguments, 250with the remaining arguments passed as first, ... arguments. 251.It Ic len 252Returns the number of characters in the first argument. 253Extra arguments 254are ignored. 255.It Ic m4exit 256Immediately exits with the return value specified by the first argument, 2570 if none. 258.It Ic m4wrap 259Allows you to define what happens at the final 260.Dv EOF , 261usually for cleanup purposes (e.g., 262.Ic m4wrap("cleanup(tempfile)") 263causes the macro cleanup to be 264invoked after all other processing is done). 265.It Ic maketemp 266Translates the string 267.Dq XXXXX 268in the first argument with the current process 269ID leaving other characters alone. 270This can be used to create unique 271temporary file names. 272.It Ic paste 273Includes the contents of the file specified by the first argument without 274any macro processing. 275Aborts with an error message if the file cannot be 276included. 277.It Ic patsubst 278Substitutes a regular expression in a string with a replacement string. 279Usual substitution patterns apply: an ampersand 280.Pq Ql \*[Am] 281is replaced by the string matching the regular expression. 282The string 283.Ql \e# , 284where 285.Ql # 286is a digit, is replaced by the corresponding back-reference. 287.It Ic popdef 288Restores the 289.Ic pushdef Ns ed 290definition for each argument. 291.It Ic pushdef 292Takes the same arguments as 293.Ic define , 294but it saves the definition on a 295stack for later retrieval by 296.Ic popdef . 297.It Ic regexp 298Finds a regular expression in a string. 299If no further arguments are given, 300it returns the first match position or \-1 if no match. 301If a third argument 302is provided, it returns the replacement string, with sub-patterns replaced. 303.It Ic shift 304Returns all but the first argument, the remaining arguments are 305quoted and pushed back with commas in between. 306The quoting 307nullifies the effect of the extra scan that will subsequently be 308performed. 309.It Ic sinclude 310Similar to 311.Ic include , 312except it ignores any errors. 313.It Ic spaste 314Similar to 315.Ic paste , 316except it ignores any errors. 317.It Ic substr 318Returns a substring of the first argument starting at the offset specified 319by the second argument and the length specified by the third argument. 320If no third argument is present it returns the rest of the string. 321.It Ic syscmd 322Passes the first argument to the shell. 323Nothing is returned. 324.It Ic sysval 325Returns the return value from the last 326.Ic syscmd . 327.It Ic traceon 328Enables tracing of macro expansions for the given arguments, or for all 329macros if no argument is given. 330.It Ic traceoff 331Disables tracing of macro expansions for the given arguments, or for all 332macros if no argument is given. 333.It Ic translit 334Transliterate the characters in the first argument from the set 335given by the second argument to the set given by the third. 336You cannot use 337.Xr tr 1 338style abbreviations. 339.It Ic undefine 340Removes the definition for the macro specified by the first argument. 341.It Ic undivert 342Flushes the named output queues (or all queues if no arguments). 343.It Ic unix 344A pre-defined macro for testing the OS platform. 345.It Ic __line__ 346Returns the current file's line number. 347.It Ic __file__ 348Returns the current file's name. 349.El 350.Sh STANDARDS 351The 352.Nm 353utility is expected to be a superset of the 354.St -xcu5 355specification, and includes some extensions also present in GNU 356.Nm "" . 357.Pp 358The 359.Fl s 360option 361.Po 362.Xr cpp 1 's 363#line directives 364.Pc 365is currently not supported. 366Flags 367.Fl I , 368.Fl d , 369.Fl t 370are non-standard. 371.Pp 372The output format of tracing and of 373.Ic dumpdef 374are not specified in any standard, 375are likely to change and should not be relied upon. 376The current format of tracing is closely modelled on GNU 377.Nm "" , 378to allow 379.Nm autoconf 380to work. 381.Pp 382For portability, one should not use the macros 383.Ic builtin , 384.Ic esycmd , 385.Ic expr , 386.Ic indir , 387.Ic paste , 388.Ic patsubst , 389.Ic regexp , 390.Ic spaste , 391.Ic unix , 392.Ic __line__ , 393.Ic __file__ . 394.Pp 395All builtins do expand without arguments in many other 396.Nm "" . 397.Sh AUTHORS 398Ozan Yigit \*[Lt]oz@sis.yorku.ca\*[Gt] and Richard A. O'Keefe (ok@cs.rmit.edu.au). 399GNU-m4 compatibility extensions by Marc Espie \*[Lt]espie@cvs.openbsd.org\*[Gt]. 400