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