1.\" Copyright (c) 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" The code is derived from software contributed to Berkeley by 5.\" Ozan Yigit. 6.\" 7.\" %sccs.include.proprietary.man% 8.\" 9.\" @(#)m4.1 6.9 (Berkeley) 04/12/91 10.\" 11.Vx 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.Ic \*(ga 122and 123.Ic \*(aa ). 124.Tp Ic changecom 125.Ar changecom(lcchar, rcchar) 126.br 127change left and right comment markers from the default 128.Ic # 129and 130.Ic newline . 131With no arguments, the comment mechanism is reset back to 132the default characters. 133With one argument, the left marker becomes the argument and 134the right marker becomes newline. 135With two arguments, both markers are affected. 136.Tp Ic divert 137.Ar divert(divnum) 138.br 139.Nm m4 140maintains 10 output streams, 141numbered 0-9. initially stream 0 is the current stream. 142The 143.Ic divert 144macro changes the current output stream to its (digit-string) 145argument. 146Output diverted to a stream other than 0 through 9 147disappears into bitbucket. 148.Tp Ic undivert 149.Ar undivert([divnum [, divnum ...]) 150.br 151causes immediate output of text from diversions named as 152argument(s), or all diversions if no argument. 153Text may be undiverted into another diversion. 154Undiverting discards the diverted text. At the end of input processing, 155.Nm M4 156forces an automatic 157.Ic undivert , 158unless 159.Ic m4wrap 160is defined. 161.Tp Ic divnum 162.Ar divnum() 163.br 164returns the value of the current output stream. 165.Tp Ic dnl 166.Ar dnl() 167.br 168reads and discards characters up to and including the next newline. 169.Tp Ic ifelse 170.Ar ifelse(arg, arg, if-same [, ifnot-same \&| arg,\ arg\ ...]) 171.br 172has three or more arguments. 173If the first argument is the same string as the second, 174then the value is the third argument. 175If not, and if there are more than four arguments, the process is 176repeated with arguments 4, 5, 6 and 7. 177Otherwise, the value is either the fourth string, or, if it is not present, 178null. 179.Tp Ic incr 180.Ar incr(num) 181.br 182returns the value of its argument incremented by 1. 183The value of the argument is calculated 184by interpreting an initial digit-string as a decimal number. 185.Tp Ic decr 186.Ar decr(num) 187.br 188returns the value of its argument decremented by 1. 189.Tp Ic eval 190.Ar eval(expression) 191.br 192evaluates its argument as a constant expression, using integer arithmetic. 193The evaluation mechanism is very similar to that of 194.Xr cpp 195(#if expression). 196The expression can involve only integer constants and character constants, 197possibly connected by the binary operators 198.Ds I 199* / % + - >> << < > 200<= >= == != & ^ && 201.De 202or the unary operators 203.Ic \&~ \&! 204or by the ternary operator 205.Ic \&? \&: . 206Parentheses may be used for grouping. Octal numbers may be specified as 207in C. 208.Tp Ic len 209.Ar len(string) 210.br 211returns the number of characters in its argument. 212.Tp Ic index 213.Ar index(search-string, string) 214.br 215returns the position in its first argument where the second argument 216begins (zero origin), 217or \-1 if the second argument does not occur. 218.Tp Ic substr 219.Ar substr(string, index [, length]) 220.br 221returns a substring of its first argument. 222The second argument is a zero origin 223number selecting the first character (internally treated as an expression); 224the third argument indicates the length of the substring. 225A missing third argument is taken to be large enough to extend to 226the end of the first string. 227.Tp Ic translit 228.Ar translit(source, from [, to]) 229.br 230transliterates the characters in its first argument 231from the set given by the second argument to the set given by the third. 232If the third argument is shorter than the second, all extra characters 233in the second argument are deleted from the first argument. If the third 234argument is missing altogether, all characters in the second argument are 235deleted from the first argument. 236.Tp Ic include 237.Ar include(filename) 238.br 239returns the contents of the file named in the argument. 240.Tp Ic sinclude 241.Ar sinclude(filename) 242.br 243is identical to 244.Ic include , 245except that it 246says nothing if the file is inaccessible. 247.Tp Ic paste 248.Ar paste(filename) 249.br 250returns the contents of the file named in the argument without any 251processing, unlike 252.Ic include . 253.Tp Ic spaste 254.Ar spaste(filename) 255.br 256is identical to 257.Ic paste , 258except that it says nothing if the file is inaccessible. 259.Tp Ic syscmd 260.Ar syscmd(command) 261.br 262executes the 263UNIX 264command given in the first argument. 265No value is returned. 266.Tp Ic sysval 267.Ar sysval() 268.br 269is the return code from the last call to 270.Ic syscmd . 271.Tp Ic maketemp 272.Ar maketemp(string) 273.br 274fills in a string of 275XXXXXX 276in its argument with the current process 277ID. 278.Tp Ic m4exit 279.Ar m4exit([exitcode]) 280.br 281causes immediate exit from 282.Nm m4 . 283Argument 1, if given, is the exit code; 284the default is 0. 285.Tp Ic m4wrap 286.Ar m4wrap(m4-macro-or-built-in) 287.br 288argument 1 will be pushed back at final 289.Ic EOF ; 290.Dl example: m4wrap(`dumptable()'). 291.Tp Ic errprint 292.Ar errprint(str [, str, str, ...]) 293.br 294prints its argument(s) on stderr. If there is more than one argument, 295each argument is separated by a space during the output. 296.Tp Ic dumpdef 297.Ar dumpdef([name, name, ...]) 298.br 299prints current names and definitions, 300for the named items, or for all if no arguments are given. 301.Tp 302.Sh AUTHOR 303Ozan S. Yigit (oz) 304.Sh BUGS 305A sufficiently complex M4 macro set is about as readable 306as 307.Ar APL . 308.Pp 309All complex uses of M4 require the ability to program in deep recursion. 310Previous lisp experience is recommended. 311.Sh EXAMPLES 312The following macro program illustrates the type of things that 313can be done with M4. 314.Pp 315.Ds I 316changequote(<,>) define(HASHVAL,99) dnl 317define(hash,<expr(str(substr($1,1),0)%HASHVAL)>) dnl 318define(str, 319 <ifelse($1,",$2, 320 \t<str(substr(<$1>,1),<expr($2+'substr($1,0,1)')>)>) 321 >) dnl 322define(KEYWORD,<$1,hash($1),>) dnl 323define(TSTART, 324<struct prehash { 325 char *keyword; 326 int hashval; 327} keytab[] = {>) dnl 328define(TEND,< "",0 329};>) 330dnl 331.De 332.Pp 333Thus a keyword table containing the keyword string and its pre-calculated 334hash value may be generated thus: 335.Pp 336.Ds I 337TSTART 338 KEYWORD("foo") 339 KEYWORD("bar") 340 KEYWORD("baz") 341TEND 342.De 343.Pp 344which will expand into: 345.Pp 346.Ds I 347struct prehash { 348 char *keyword; 349 int hashval; 350} keytab[] = { 351 "foo",27, 352 "bar",12, 353 "baz",20, 354 "",0 355}; 356.De 357.Pp 358Presumably, such a table would speed up the installation of the 359keywords into a dynamic hash table. (Note that the above macro 360cannot be used with 361.Nm m4 , 362since 363.Ic eval 364does not handle character constants.) 365.Sh SEE ALSO 366.Xr cc 1 , 367.Xr cpp 1 . 368.Xr m4 1 369.br 370.Em The M4 Macro Processor 371by B. W. Kernighan and D. M. Ritchie. 372.Sh HISTORY 373.Nm M4 374command appeared in Version 7 AT&T UNIX. The 375.Nm m4 376command this page describes is derived from code 377contributed by Ozan S. Yigit. 378