1.\" $NetBSD: m4.1,v 1.18 2003/06/27 21:57:43 wiz 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 Sq ( . 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 Sq \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.Dq m4_ . 75This changes the macro names 76.Dq dnl 77to 78.Dq m4_dnl , 79.Dq index 80to 81.Dq 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 stderr. 123.It Fl t Ar macro 124Turn tracing on for 125.Ar macro . 126.El 127.Sh SYNTAX 128.Nm 129provides the following built-in macros. 130They may be redefined, losing their original meaning. 131Return values are null unless otherwise stated. 132.Bl -tag -width changequotexxx 133.It Ic builtin 134Calls a built-in by its name, overriding possible redefinitions. 135.It Ic changecom 136Change the start and end comment sequences. 137The default is the pound sign 138.Pq Sq # 139and the newline character. 140With no arguments comments are turned off. 141The maximum length for a comment marker is five characters. 142.It Ic changequote 143Defines the quote symbols to be the first and second arguments. 144The symbols may be up to five characters long. 145If no arguments are 146given it restores the default open and close single quotes. 147.It Ic decr 148Decrements the argument by 1. 149The argument must be a valid numeric string. 150.It Ic define 151Define a new macro named by the first argument to have the 152value of the second argument. 153Each occurrence of 154.Dq $n 155(where 156.Ar n 157is 0 through 9) is replaced by the 158.Ar n Ns 'th 159argument. 160.Dq $0 161is the name of the calling macro. 162Undefined arguments are replaced by a null string. 163.Dq $# 164is replaced by the number of arguments; 165.Dq $* 166is replaced by all arguments comma separated; 167.Dq $@ 168is the same as 169.Dq $* 170but all arguments are quoted against further expansion. 171.It Ic defn 172Returns the quoted definition for each argument. 173This can be used to rename 174macro definitions (even for built-in macros). 175.It Ic divert 176There are 10 output queues (numbered 0-9). 177At the end of processing 178.Nm 179concatenates all the queues in numerical order to produce the 180final output. 181Initially the output queue is 0. 182The divert 183macro allows you to select a new output queue (an invalid argument 184passed to divert causes output to be discarded). 185.It Ic divnum 186Returns the current output queue number. 187.It Ic dnl 188Discard input characters up to and including the next newline. 189.It Ic dumpdef 190Prints the names and definitions for the named items, or for everything 191if no arguments are passed. 192.It Ic errprint 193Prints the first argument on the standard error output stream. 194.It Ic esyscmd 195Pass its first argument to a shell and returns the shell's standard output. 196Note that the shell shares its standard input and standard error with 197.Nm . 198.It Ic eval 199Computes the first argument as an arithmetic expression using 32-bit 200arithmetic. 201Operators are the standard C ternary, arithmetic, logical, 202shift, relational, bitwise, and parentheses operators. 203You can specify 204octal, decimal, and hexadecimal numbers as in C. 205The second argument (if any) 206specifies the radix for the result and the third argument (if any) 207specifies the minimum number of digits in the result. 208.It Ic expr 209This is an alias for 210.Ic eval . 211.It Ic ifdef 212If the macro named by the first argument is defined then return the second 213argument, otherwise the third. 214If there is no third argument, the value is 215.Dv NULL . 216The word 217.Qq unix 218is predefined. 219.It Ic ifelse 220If the first argument matches the second argument then 221.Ic ifelse 222returns 223the third argument. 224If the match fails the three arguments are 225discarded and the next three arguments are used until there is 226zero or one arguments left, either this last argument or 227.Dv NULL 228is returned if no other matches were found. 229.It Ic include 230Returns the contents of the file specified in the first argument. 231If the file is not found as is, look through the include path: 232first the directories specified with 233.Fl I 234on the command line, then the environment variable 235.Ev M4PATH , 236as a colon-separated list of directories. 237Include aborts with an error message if the file cannot be included. 238.It Ic incr 239Increments the argument by 1. 240The argument must be a valid numeric string. 241.It Ic index 242Returns the index of the second argument in the first argument (e.g., 243.Ic index(the quick brown fox jumped, fox) 244returns 16). 245If the second 246argument is not found index returns \-1. 247.It Ic indir 248Indirectly calls the macro whose name is passed as the first arguments, 249with the remaining arguments passed as first, ... arguments. 250.It Ic len 251Returns the number of characters in the first argument. 252Extra arguments 253are ignored. 254.It Ic m4exit 255Immediately exits with the return value specified by the first argument, 2560 if none. 257.It Ic m4wrap 258Allows you to define what happens at the final 259.Dv EOF , 260usually for cleanup purposes (e.g., 261.Ic m4wrap("cleanup(tempfile)") 262causes the macro cleanup to be 263invoked after all other processing is done). 264.It Ic maketemp 265Translates the string 266.Dq XXXXX 267in the first argument with the current process 268ID leaving other characters alone. 269This can be used to create unique 270temporary file names. 271.It Ic paste 272Includes the contents of the file specified by the first argument without 273any macro processing. 274Aborts with an error message if the file cannot be 275included. 276.It Ic patsubst 277Substitutes a regular expression in a string with a replacement string. 278Usual substitution patterns apply: an ampersand 279.Pq Sq \*[Am] 280is replaced by the string matching the regular expression. 281The string 282.Dq \e# , 283where 284.Sq # 285is a digit, is replaced by the corresponding back-reference. 286.It Ic popdef 287Restores the 288.Ic pushdef Ns ed 289definition for each argument. 290.It Ic pushdef 291Takes the same arguments as 292.Ic define , 293but it saves the definition on a 294stack for later retrieval by 295.Ic popdef . 296.It Ic regexp 297Finds a regular expression in a string. 298If no further arguments are given, 299it returns the first match position or \-1 if no match. 300If a third argument 301is provided, it returns the replacement string, with sub-patterns replaced. 302.It Ic shift 303Returns all but the first argument, the remaining arguments are 304quoted and pushed back with commas in between. 305The quoting 306nullifies the effect of the extra scan that will subsequently be 307performed. 308.It Ic sinclude 309Similar to 310.Ic include , 311except it ignores any errors. 312.It Ic spaste 313Similar to 314.Ic paste , 315except it ignores any errors. 316.It Ic substr 317Returns a substring of the first argument starting at the offset specified 318by the second argument and the length specified by the third argument. 319If no third argument is present it returns the rest of the string. 320.It Ic syscmd 321Passes the first argument to the shell. 322Nothing is returned. 323.It Ic sysval 324Returns the return value from the last 325.Ic syscmd . 326.It Ic traceon 327Enables tracing of macro expansions for the given arguments, or for all 328macros if no argument is given. 329.It Ic traceoff 330Disables tracing of macro expansions for the given arguments, or for all 331macros if no argument is given. 332.It Ic translit 333Transliterate the characters in the first argument from the set 334given by the second argument to the set given by the third. 335You cannot use 336.Xr tr 1 337style abbreviations. 338.It Ic undefine 339Removes the definition for the macro specified by the first argument. 340.It Ic undivert 341Flushes the named output queues (or all queues if no arguments). 342.It Ic unix 343A pre-defined macro for testing the OS platform. 344.It Ic __line__ 345Returns the current file's line number. 346.It Ic __file__ 347Returns the current file's name. 348.El 349.Sh STANDARDS 350The 351.Nm 352utility is expected to be a superset of the 353.St -xcu5 354specification, and includes some extensions also present in GNU 355.Nm . 356.Pp 357The 358.Fl s 359option 360.Po 361.Xr cpp 1 Ns 's 362#line directives 363.Pc 364is currently not supported. 365Flags 366.Fl I , 367.Fl d , 368.Fl t 369are non-standard. 370.Pp 371The output format of tracing and of 372.Ic dumpdef 373are not specified in any standard, 374are likely to change and should not be relied upon. 375The current format of tracing is closely modelled on GNU 376.Nm , 377to allow 378.Nm autoconf 379to work. 380.Pp 381For portability, one should not use the macros 382.Ic builtin , 383.Ic esycmd , 384.Ic expr , 385.Ic indir , 386.Ic paste , 387.Ic patsubst , 388.Ic regexp , 389.Ic spaste , 390.Ic unix , 391.Ic __line__ , 392.Ic __file__ . 393.Pp 394All builtins do expand without arguments in many other 395.Nm . 396.Sh AUTHORS 397Ozan Yigit \*[Lt]oz@sis.yorku.ca\*[Gt] and Richard A. O'Keefe (ok@cs.rmit.edu.au). 398GNU-m4 compatibility extensions by Marc Espie \*[Lt]espie@cvs.openbsd.org\*[Gt]. 399