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