Commit | Line | Data |
---|---|---|
61212793 C |
1 | M4(1) UNIX Reference Manual M4(1) |
2 | ||
3 | N\bNA\bAM\bME\bE | |
4 | m\bm4\b4 - macro language preprocessor for Ratfor and Pascal | |
5 | ||
6 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS | |
7 | m\bm4\b4 [options] | |
8 | ||
9 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN | |
10 | M\bM4\b4 is a macro language preprocessor for Ratfor, Pascal, and similar | |
11 | languages which do not have a built-in macro processing capability. M4 | |
12 | reads standard input, and writes the results to the standard output. | |
13 | ||
14 | The options and their effects are as follows: | |
15 | ||
16 | -\b-D\bD_\bn_\ba_\bm_\be[=_\bV_\ba_\bl] Defines _\bn_\ba_\bm_\be to _\bv_\ba_\bl or to null in the absence of _\bv_\ba_\bl. | |
17 | ||
18 | -\b-U\bU_\bn_\ba_\bm_\be undefines _\bn_\ba_\bm_\be. | |
19 | ||
20 | The m\bm4\b4 processor provides a kind of C\bC like syntax and some of the macro | |
21 | functions will be familiar: | |
22 | ||
23 | d\bde\bef\bfi\bin\bne\be _\bd_\be_\bf_\bi_\bn_\be(_\bn_\ba_\bm_\be [, _\bv_\ba_\bl]) | |
24 | the second argument is installed as the value of the macro | |
25 | whose name is the first argument. If there is no second argu- | |
26 | ment, the value is null. Each occurrence of $\b$_\bn in the | |
27 | replacement text, where _\bn is a digit, is replaced by the _\bn'th | |
28 | argument. Argument 0 is the name of the macro; missing | |
29 | arguments are replaced by the null string. | |
30 | ||
31 | d\bde\bef\bfn\bn _\bd_\be_\bf_\bn(_\bn_\ba_\bm_\be [, _\bn_\ba_\bm_\be ...]) | |
32 | returns the quoted definition of its argument(s). Useful in | |
33 | renaming macros. | |
34 | ||
35 | u\bun\bnd\bde\bef\bfi\bin\bne\be | |
36 | _\bu_\bn_\bd_\be_\bf_\bi_\bn_\be(_\bn_\ba_\bm_\be [, _\bn_\ba_\bm_\be ...]) | |
37 | removes the definition of the macro(s) named. If there is more | |
38 | than one definition for the named macro, (due to previous use | |
39 | of p\bpu\bus\bsh\bhd\bde\bef\bf) all definitions are removed. | |
40 | ||
41 | p\bpu\bus\bsh\bhd\bde\bef\bf _\bp_\bu_\bs_\bh_\bd_\be_\bf(_\bn_\ba_\bm_\be [, _\bv_\ba_\bl]) | |
42 | like d\bde\bef\bfi\bin\bne\be, but saves any previous definition by stacking the | |
43 | current definition. | |
44 | ||
45 | p\bpo\bop\bpd\bde\bef\bf _\bp_\bo_\bp_\bd_\be_\bf(_\bn_\ba_\bm_\be [, _\bn_\ba_\bm_\be ...]) | |
46 | removes current definition of its argument(s), exposing the | |
47 | previous one if any. | |
48 | ||
49 | i\bif\bfd\bde\bef\bf _\bi_\bf_\bd_\be_\bf(_\bn_\ba_\bm_\be, _\bi_\bf-_\bd_\be_\bf [, _\bi_\bf_\bn_\bo_\bt-_\bd_\be_\bf]) | |
50 | if the first argument is defined, the value is the second argu- | |
51 | ment, otherwise the third. If there is no third argument, the | |
52 | value is null. | |
53 | ||
54 | s\bsh\bhi\bif\bft\bt _\bs_\bh_\bi_\bf_\bt(_\ba_\br_\bg, _\ba_\br_\bg, _\ba_\br_\bg, ...) | |
55 | returns all but its first argument. The other arguments are | |
56 | quoted and pushed back with commas in between. The quoting | |
57 | nullifies the effect of the extra scan that will subsequently | |
58 | be performed. | |
59 | ||
60 | c\bch\bha\ban\bng\bge\beq\bqu\buo\bot\bte\be | |
61 | _\bc_\bh_\ba_\bn_\bg_\be_\bq_\bu_\bo_\bt_\be(_\bl_\bq_\bc_\bh_\ba_\br, _\br_\bq_\bc_\bh_\ba_\br) | |
62 | change quote symbols to the first and second arguments. With | |
63 | no arguments, the quotes are reset back to the default charac- | |
64 | ters. (i.e., \*'). | |
65 | ||
66 | c\bch\bha\ban\bng\bge\bec\bco\bom\bm | |
67 | _\bc_\bh_\ba_\bn_\bg_\be_\bc_\bo_\bm(_\bl_\bc_\bc_\bh_\ba_\br, _\br_\bc_\bc_\bh_\ba_\br) | |
68 | change left and right comment markers from the default #\b# and | |
69 | n\bne\bew\bwl\bli\bin\bne\be. With no arguments, the comment mechanism is reset | |
70 | back to the default characters. With one argument, the left | |
71 | marker becomes the argument and the right marker becomes new- | |
72 | line. With two arguments, both markers are affected. | |
73 | ||
74 | d\bdi\biv\bve\ber\brt\bt _\bd_\bi_\bv_\be_\br_\bt(_\bd_\bi_\bv_\bn_\bu_\bm) | |
75 | m\bm4\b4 maintains 10 output streams, numbered 0-9. initially stream | |
76 | 0 is the current stream. The d\bdi\biv\bve\ber\brt\bt macro changes the current | |
77 | output stream to its (digit-string) argument. Output diverted | |
78 | to a stream other than 0 through 9 disappears into bitbucket. | |
79 | ||
80 | u\bun\bnd\bdi\biv\bve\ber\brt\bt | |
81 | _\bu_\bn_\bd_\bi_\bv_\be_\br_\bt([_\bd_\bi_\bv_\bn_\bu_\bm [, _\bd_\bi_\bv_\bn_\bu_\bm ...]) | |
82 | causes immediate output of text from diversions named as | |
83 | argument(s), or all diversions if no argument. Text may be un- | |
84 | diverted into another diversion. Undiverting discards the | |
85 | diverted text. At the end of input processing, M\bM4\b4 forces an au- | |
86 | tomatic u\bun\bnd\bdi\biv\bve\ber\brt\bt, unless m\bm4\b4w\bwr\bra\bap\bp is defined. | |
87 | ||
88 | d\bdi\biv\bvn\bnu\bum\bm _\bd_\bi_\bv_\bn_\bu_\bm() | |
89 | returns the value of the current output stream. | |
90 | ||
91 | d\bdn\bnl\bl _\bd_\bn_\bl() | |
92 | reads and discards characters up to and including the next new- | |
93 | line. | |
94 | ||
95 | i\bif\bfe\bel\bls\bse\be _\bi_\bf_\be_\bl_\bs_\be(_\ba_\br_\bg, _\ba_\br_\bg, _\bi_\bf-_\bs_\ba_\bm_\be [, _\bi_\bf_\bn_\bo_\bt-_\bs_\ba_\bm_\be | _\ba_\br_\bg, _\ba_\br_\bg ...]) | |
96 | has three or more arguments. If the first argument is the same | |
97 | string as the second, then the value is the third argument. If | |
98 | not, and if there are more than four arguments, the process is | |
99 | repeated with arguments 4, 5, 6 and 7. Otherwise, the value is | |
100 | either the fourth string, or, if it is not present, null. | |
101 | ||
102 | i\bin\bnc\bcr\br _\bi_\bn_\bc_\br(_\bn_\bu_\bm) | |
103 | returns the value of its argument incremented by 1. The value | |
104 | of the argument is calculated by interpreting an initial | |
105 | digit-string as a decimal number. | |
106 | ||
107 | d\bde\bec\bcr\br _\bd_\be_\bc_\br(_\bn_\bu_\bm) | |
108 | returns the value of its argument decremented by 1. | |
109 | ||
110 | e\bev\bva\bal\bl _\be_\bv_\ba_\bl(_\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn) | |
111 | evaluates its argument as a constant expression, using integer | |
112 | arithmetic. The evaluation mechanism is very similar to that | |
113 | of cpp (#if expression). The expression can involve only in- | |
114 | teger constants and character constants, possibly connected by | |
115 | the binary operators | |
116 | * / % + - >> << < > | |
117 | <= >= == != & ^ && | |
118 | or the unary operators ~\b~ !\b! or by the ternary operator ?\b? :\b:. | |
119 | Parentheses may be used for grouping. Octal numbers may be | |
120 | specified as in C. | |
121 | ||
122 | l\ble\ben\bn _\bl_\be_\bn(_\bs_\bt_\br_\bi_\bn_\bg) | |
123 | returns the number of characters in its argument. | |
124 | ||
125 | i\bin\bnd\bde\bex\bx _\bi_\bn_\bd_\be_\bx(_\bs_\be_\ba_\br_\bc_\bh-_\bs_\bt_\br_\bi_\bn_\bg, _\bs_\bt_\br_\bi_\bn_\bg) | |
126 | returns the position in its first argument where the second ar- | |
127 | gument begins (zero origin), or -1 if the second argument does | |
128 | not occur. | |
129 | ||
130 | s\bsu\bub\bbs\bst\btr\br _\bs_\bu_\bb_\bs_\bt_\br(_\bs_\bt_\br_\bi_\bn_\bg, _\bi_\bn_\bd_\be_\bx [, _\bl_\be_\bn_\bg_\bt_\bh]) | |
131 | returns a substring of its first argument. The second argument | |
132 | is a zero origin number selecting the first character (inter- | |
133 | nally treated as an expression); the third argument indicates | |
134 | the length of the substring. A missing third argument is taken | |
135 | to be large enough to extend to the end of the first string. | |
136 | ||
137 | t\btr\bra\ban\bns\bsl\bli\bit\bt | |
138 | _\bt_\br_\ba_\bn_\bs_\bl_\bi_\bt(_\bs_\bo_\bu_\br_\bc_\be, _\bf_\br_\bo_\bm [, _\bt_\bo]) | |
139 | transliterates the characters in its first argument from the | |
140 | set given by the second argument to the set given by the third. | |
141 | If the third argument is shorter than the second, all extra | |
142 | characters in the second argument are deleted from the first | |
143 | argument. If the third argument is missing altogether, all | |
144 | characters in the second argument are deleted from the first | |
145 | argument. | |
146 | ||
147 | i\bin\bnc\bcl\blu\bud\bde\be _\bi_\bn_\bc_\bl_\bu_\bd_\be(_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be) | |
148 | returns the contents of the file named in the argument. | |
149 | ||
150 | s\bsi\bin\bnc\bcl\blu\bud\bde\be | |
151 | _\bs_\bi_\bn_\bc_\bl_\bu_\bd_\be(_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be) | |
152 | is identical to i\bin\bnc\bcl\blu\bud\bde\be, except that it says nothing if the | |
153 | file is inaccessible. | |
154 | ||
155 | p\bpa\bas\bst\bte\be _\bp_\ba_\bs_\bt_\be(_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be) | |
156 | returns the contents of the file named in the argument without | |
157 | any processing, unlike i\bin\bnc\bcl\blu\bud\bde\be. | |
158 | ||
159 | s\bsp\bpa\bas\bst\bte\be _\bs_\bp_\ba_\bs_\bt_\be(_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be) | |
160 | is identical to p\bpa\bas\bst\bte\be, except that it says nothing if the file | |
161 | is inaccessible. | |
162 | ||
163 | s\bsy\bys\bsc\bcm\bmd\bd _\bs_\by_\bs_\bc_\bm_\bd(_\bc_\bo_\bm_\bm_\ba_\bn_\bd) | |
164 | executes the UNIX command given in the first argument. No | |
165 | value is returned. | |
166 | ||
167 | s\bsy\bys\bsv\bva\bal\bl _\bs_\by_\bs_\bv_\ba_\bl() | |
168 | is the return code from the last call to s\bsy\bys\bsc\bcm\bmd\bd. | |
169 | ||
170 | m\bma\bak\bke\bet\bte\bem\bmp\bp | |
171 | _\bm_\ba_\bk_\be_\bt_\be_\bm_\bp(_\bs_\bt_\br_\bi_\bn_\bg) | |
172 | fills in a string of XXXXXX in its argument with the current | |
173 | process ID. | |
174 | ||
175 | m\bm4\b4e\bex\bxi\bit\bt _\bm_\b4_\be_\bx_\bi_\bt([_\be_\bx_\bi_\bt_\bc_\bo_\bd_\be]) | |
176 | causes immediate exit from m\bm4\b4. Argument 1, if given, is the | |
177 | exit code; the default is 0. | |
178 | ||
179 | m\bm4\b4w\bwr\bra\bap\bp _\bm_\b4_\bw_\br_\ba_\bp(_\bm_\b4-_\bm_\ba_\bc_\br_\bo-_\bo_\br-_\bb_\bu_\bi_\bl_\bt-_\bi_\bn) | |
180 | argument 1 will be pushed back at final E\bEO\bOF\bF; | |
181 | example: m4wrap(`dumptable()'). | |
182 | ||
183 | e\ber\brr\brp\bpr\bri\bin\bnt\bt | |
184 | _\be_\br_\br_\bp_\br_\bi_\bn_\bt(_\bs_\bt_\br [, _\bs_\bt_\br, _\bs_\bt_\br, ...]) | |
185 | prints its argument(s) on stderr. If there is more than one ar- | |
186 | gument, each argument is separated by a space during the out- | |
187 | put. | |
188 | ||
189 | d\bdu\bum\bmp\bpd\bde\bef\bf _\bd_\bu_\bm_\bp_\bd_\be_\bf([_\bn_\ba_\bm_\be, _\bn_\ba_\bm_\be, ...]) | |
190 | prints current names and definitions, for the named items, or | |
191 | for all if no arguments are given. | |
192 | ||
193 | A\bAU\bUT\bTH\bHO\bOR\bR | |
194 | Ozan S. Yigit (oz) | |
195 | ||
196 | B\bBU\bUG\bGS\bS | |
197 | A sufficiently complex M4 macro set is about as readable as _\bA_\bP_\bL. | |
198 | ||
199 | ||
200 | All complex uses of M4 require the ability to program in deep recursion. | |
201 | Previous lisp experience is recommended. | |
202 | ||
203 | E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS | |
204 | The following macro program illustrates the type of things that can be | |
205 | done with M4. | |
206 | ||
207 | changequote(<,>) define(HASHVAL,99) dnl | |
208 | define(hash,<expr(str(substr($1,1),0)%HASHVAL)>) dnl | |
209 | define(str, | |
210 | <ifelse($1,",$2, | |
211 | <str(substr(<$1>,1),<expr($2+'substr($1,0,1)')>)>) | |
212 | >) dnl | |
213 | define(KEYWORD,<$1,hash($1),>) dnl | |
214 | define(TSTART, | |
215 | <struct prehash { | |
216 | char *keyword; | |
217 | int hashval; | |
218 | } keytab[] = {>) dnl | |
219 | define(TEND,< "",0 | |
220 | };>) | |
221 | dnl | |
222 | ||
223 | Thus a keyword table containing the keyword string and its pre-calculated | |
224 | hash value may be generated thus: | |
225 | ||
226 | TSTART | |
227 | KEYWORD("foo") | |
228 | KEYWORD("bar") | |
229 | KEYWORD("baz") | |
230 | TEND | |
231 | ||
232 | which will expand into: | |
233 | ||
234 | struct prehash { | |
235 | char *keyword; | |
236 | int hashval; | |
237 | } keytab[] = { | |
238 | "foo",27, | |
239 | "bar",12, | |
240 | "baz",20, | |
241 | "",0 | |
242 | }; | |
243 | ||
244 | Presumably, such a table would speed up the installation of the keywords | |
245 | into a dynamic hash table. (Note that the above macro cannot be used with | |
246 | m\bm4\b4, since e\bev\bva\bal\bl does not handle character constants.) | |
247 | ||
248 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
249 | cc(1), cpp(1). m4(1) | |
250 | _\bT_\bh_\be _\bM_\b4 _\bM_\ba_\bc_\br_\bo _\bP_\br_\bo_\bc_\be_\bs_\bs_\bo_\br by B. W. Kernighan and D. M. Ritchie. | |
251 | ||
252 | H\bHI\bIS\bST\bTO\bOR\bRY\bY | |
253 | M\bM4\b4 command appeared in Version 7 AT&T UNIX. The m\bm4\b4 command this page | |
254 | describes is derived from code contributed by Ozan S. Yigit. |