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