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