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