1.\" Copyright (c) 1989, 1990 The Regents of the University of California. 2.\" All rights reserved. The Berkeley software License Agreement 3.\" specifies the terms and conditions for redistribution. 4.\" 5.\" The code is derived from software contributed to Berkeley by 6.\" Ozan Yigit. 7.\" 8.\" %sccs.include.redist.man% 9.\" 10.\" @(#)m4.1 6.8 (Berkeley) 03/14/91 11.\" 12.Vx 13.Vx 14.Dd 15.Dt M4 1 16.Sh NAME 17.Nm m4 18.Nd macro language preprocessor for Ratfor and Pascal 19.Sh SYNOPSIS 20.Nm m4 21.Op options 22.Sh DESCRIPTION 23.Nm M4 24is a macro language 25preprocessor 26for Ratfor, Pascal, and similar languages which do not 27have a built-in macro processing capability. 28M4 reads standard input, and writes the results to the standard output. 29.Pp 30The options and their effects are as follows: 31.Pp 32.Tw _Dname[=Val] 33.Tp Cx Fl D 34.Ar name 35.Op Ar \&=Val 36.Cx 37Defines 38.Ar name 39to 40.Ar val 41or to null in 42the absence of 43.Ar val . 44.Tp Cx Fl U 45.Ar name 46.Cx 47undefines 48.Ar name . 49.Tp 50.Pp 51The 52.Nm m4 53processor provides a kind of 54.Nm C 55like syntax and 56some of the macro functions will 57be familiar: 58.Tw \&undiver 59.Tp Ic define 60.Ar define(name [, val]) 61.br 62the second argument is installed as the value of the macro 63whose name is the first argument. If there is no second argument, 64the value is null. 65Each occurrence of 66.Cx Ic $ 67.Ar n 68.Cx 69in the replacement text, 70where 71.Ar n 72is a digit, 73is replaced by the 74.Cx Ar n 75.Cx \'th 76.Cx 77argument. 78Argument 0 is the name of the macro; 79missing arguments are replaced by the null string. 80.Tp Ic defn 81.Ar defn(name [, name ...]) 82.br 83returns the quoted definition of its argument(s). Useful in renaming 84macros. 85.Tp Ic undefine 86.Ar undefine(name [, name ...]) 87.br 88removes the definition of the macro(s) named. If there is 89more than one definition for the named macro, (due to previous use of 90.Ic pushdef ) 91all definitions are removed. 92.Tp Ic pushdef 93.Ar pushdef(name [, val]) 94.br 95like 96.Ic define , 97but saves any previous definition by stacking the current definition. 98.Tp Ic popdef 99.Ar popdef(name [, name ...]) 100.br 101removes current definition of its argument(s), 102exposing the previous one if any. 103.Tp Ic ifdef 104.Ar ifdef(name, if-def [, ifnot-def]) 105.br 106if the first argument is defined, the value is the second argument, 107otherwise the third. 108If there is no third argument, the value is null. 109.Tp Ic shift 110.Ar shift(arg, arg, arg, ...) 111.br 112returns all but its first argument. 113The other arguments are quoted and pushed back with 114commas in between. 115The quoting nullifies the effect of the extra scan that 116will subsequently be performed. 117.Tp Ic changequote 118.Ar changequote(lqchar, rqchar) 119.br 120change quote symbols to the first and second arguments. 121With no arguments, the quotes are reset back to the default 122characters (i.e., 123.Ic \*(ga 124and 125.Ic \*(aa ). 126.Tp Ic changecom 127.Ar changecom(lcchar, rcchar) 128.br 129change left and right comment markers from the default 130.Ic # 131and 132.Ic newline . 133With no arguments, the comment mechanism is reset back to 134the default characters. 135With one argument, the left marker becomes the argument and 136the right marker becomes newline. 137With two arguments, both markers are affected. 138.Tp Ic divert 139.Ar divert(divnum) 140.br 141.Nm m4 142maintains 10 output streams, 143numbered 0-9. initially stream 0 is the current stream. 144The 145.Ic divert 146macro changes the current output stream to its (digit-string) 147argument. 148Output diverted to a stream other than 0 through 9 149disappears into bitbucket. 150.Tp Ic undivert 151.Ar undivert([divnum [, divnum ...]) 152.br 153causes immediate output of text from diversions named as 154argument(s), or all diversions if no argument. 155Text may be undiverted into another diversion. 156Undiverting discards the diverted text. At the end of input processing, 157.Nm M4 158forces an automatic 159.Ic undivert , 160unless 161.Ic m4wrap 162is defined. 163.Tp Ic divnum 164.Ar divnum() 165.br 166returns the value of the current output stream. 167.Tp Ic dnl 168.Ar dnl() 169.br 170reads and discards characters up to and including the next newline. 171.Tp Ic ifelse 172.Ar ifelse(arg, arg, if-same [, ifnot-same \&| arg,\ arg\ ...]) 173.br 174has three or more arguments. 175If the first argument is the same string as the second, 176then the value is the third argument. 177If not, and if there are more than four arguments, the process is 178repeated with arguments 4, 5, 6 and 7. 179Otherwise, the value is either the fourth string, or, if it is not present, 180null. 181.Tp Ic incr 182.Ar incr(num) 183.br 184returns the value of its argument incremented by 1. 185The value of the argument is calculated 186by interpreting an initial digit-string as a decimal number. 187.Tp Ic decr 188.Ar decr(num) 189.br 190returns the value of its argument decremented by 1. 191.Tp Ic eval 192.Ar eval(expression) 193.br 194evaluates its argument as a constant expression, using integer arithmetic. 195The evaluation mechanism is very similar to that of 196.Xr cpp 197(#if expression). 198The expression can involve only integer constants and character constants, 199possibly connected by the binary operators 200.Ds I 201* / % + - >> << < > 202<= >= == != & ^ && 203.De 204or the unary operators 205.Ic \&~ \&! 206or by the ternary operator 207.Ic \&? \&: . 208Parentheses may be used for grouping. Octal numbers may be specified as 209in C. 210.Tp Ic len 211.Ar len(string) 212.br 213returns the number of characters in its argument. 214.Tp Ic index 215.Ar index(search-string, string) 216.br 217returns the position in its first argument where the second argument 218begins (zero origin), 219or \-1 if the second argument does not occur. 220.Tp Ic substr 221.Ar substr(string, index [, length]) 222.br 223returns a substring of its first argument. 224The second argument is a zero origin 225number selecting the first character (internally treated as an expression); 226the third argument indicates the length of the substring. 227A missing third argument is taken to be large enough to extend to 228the end of the first string. 229.Tp Ic translit 230.Ar translit(source, from [, to]) 231.br 232transliterates the characters in its first argument 233from the set given by the second argument to the set given by the third. 234If the third argument is shorter than the second, all extra characters 235in the second argument are deleted from the first argument. If the third 236argument is missing altogether, all characters in the second argument are 237deleted from the first argument. 238.Tp Ic include 239.Ar include(filename) 240.br 241returns the contents of the file named in the argument. 242.Tp Ic sinclude 243.Ar sinclude(filename) 244.br 245is identical to 246.Ic include , 247except that it 248says nothing if the file is inaccessible. 249.Tp Ic paste 250.Ar paste(filename) 251.br 252returns the contents of the file named in the argument without any 253processing, unlike 254.Ic include . 255.Tp Ic spaste 256.Ar spaste(filename) 257.br 258is identical to 259.Ic paste , 260except that it says nothing if the file is inaccessible. 261.Tp Ic syscmd 262.Ar syscmd(command) 263.br 264executes the 265UNIX 266command given in the first argument. 267No value is returned. 268.Tp Ic sysval 269.Ar sysval() 270.br 271is the return code from the last call to 272.Ic syscmd . 273.Tp Ic maketemp 274.Ar maketemp(string) 275.br 276fills in a string of 277XXXXXX 278in its argument with the current process 279ID. 280.Tp Ic m4exit 281.Ar m4exit([exitcode]) 282.br 283causes immediate exit from 284.Nm m4 . 285Argument 1, if given, is the exit code; 286the default is 0. 287.Tp Ic m4wrap 288.Ar m4wrap(m4-macro-or-built-in) 289.br 290argument 1 will be pushed back at final 291.Ic EOF ; 292.Dl example: m4wrap(`dumptable()'). 293.Tp Ic errprint 294.Ar errprint(str [, str, str, ...]) 295.br 296prints its argument(s) on stderr. If there is more than one argument, 297each argument is separated by a space during the output. 298.Tp Ic dumpdef 299.Ar dumpdef([name, name, ...]) 300.br 301prints current names and definitions, 302for the named items, or for all if no arguments are given. 303.Tp 304.Sh AUTHOR 305Ozan S. Yigit (oz) 306.Sh BUGS 307A sufficiently complex M4 macro set is about as readable 308as 309.Ar APL . 310.Pp 311All complex uses of M4 require the ability to program in deep recursion. 312Previous lisp experience is recommended. 313.Sh EXAMPLES 314The following macro program illustrates the type of things that 315can be done with M4. 316.Pp 317.Ds I 318changequote(<,>) define(HASHVAL,99) dnl 319define(hash,<expr(str(substr($1,1),0)%HASHVAL)>) dnl 320define(str, 321 <ifelse($1,",$2, 322 \t<str(substr(<$1>,1),<expr($2+'substr($1,0,1)')>)>) 323 >) dnl 324define(KEYWORD,<$1,hash($1),>) dnl 325define(TSTART, 326<struct prehash { 327 char *keyword; 328 int hashval; 329} keytab[] = {>) dnl 330define(TEND,< "",0 331};>) 332dnl 333.De 334.Pp 335Thus a keyword table containing the keyword string and its pre-calculated 336hash value may be generated thus: 337.Pp 338.Ds I 339TSTART 340 KEYWORD("foo") 341 KEYWORD("bar") 342 KEYWORD("baz") 343TEND 344.De 345.Pp 346which will expand into: 347.Pp 348.Ds I 349struct prehash { 350 char *keyword; 351 int hashval; 352} keytab[] = { 353 "foo",27, 354 "bar",12, 355 "baz",20, 356 "",0 357}; 358.De 359.Pp 360Presumably, such a table would speed up the installation of the 361keywords into a dynamic hash table. (Note that the above macro 362cannot be used with 363.Nm m4 , 364since 365.Ic eval 366does not handle character constants.) 367.Sh SEE ALSO 368.Xr cc 1 , 369.Xr cpp 1 . 370.Xr m4 1 371.br 372.Em The M4 Macro Processor 373by B. W. Kernighan and D. M. Ritchie. 374.Sh HISTORY 375.Nm M4 376command appeared in Version 7 AT&T UNIX. The 377.Nm m4 378command this page describes is derived from code 379contributed by Ozan S. Yigit. 380