Commit | Line | Data |
---|---|---|
d035a14f BK |
1 | .TH M4 1 |
2 | .SH NAME | |
3 | m4 \- macro processor | |
4 | .SH SYNOPSIS | |
5 | .B m4 | |
6 | [ files ] | |
7 | .SH DESCRIPTION | |
8 | .I M4 | |
9 | is a macro processor | |
10 | intended as a front end for Ratfor, C, and other languages. | |
11 | Each of the argument files is processed in order; | |
12 | if there are no arguments, or if an argument is `\-', | |
13 | the standard input is read. | |
14 | The processed text is written on the standard output. | |
15 | .PP | |
16 | Macro calls | |
17 | have the form | |
18 | .PP | |
19 | name(arg1,arg2, . . . , argn) | |
20 | .br | |
21 | .PP | |
22 | The `(' must immediately follow the name of the macro. | |
23 | If a defined macro name is not followed by a `(', | |
24 | it is deemed to have no arguments. | |
25 | Leading unquoted blanks, tabs, and newlines are ignored while collecting arguments. | |
26 | Potential macro names consist of alphabetic letters, | |
27 | digits, and underscore `\_', where the first character is not a digit. | |
28 | .PP | |
29 | Left and right single quotes (\`\|\') are used to quote strings. | |
30 | The value of a quoted string is the string stripped of the quotes. | |
31 | .PP | |
32 | When a macro name is recognized, | |
33 | its arguments are collected by searching for a matching right | |
34 | parenthesis. | |
35 | Macro evaluation proceeds normally during the collection of the arguments, | |
36 | and any commas or right parentheses | |
37 | which happen to turn up within the value of a nested | |
38 | call are as effective as those in the original input text. | |
39 | After argument collection, | |
40 | the value of the macro is pushed back onto the input stream | |
41 | and rescanned. | |
42 | .PP | |
43 | .I M4 | |
44 | makes available the following built-in macros. | |
45 | They may be redefined, but once this is done the original meaning is lost. | |
46 | Their values are null unless otherwise stated. | |
47 | .TP 10 | |
48 | define | |
49 | The second argument is installed as the value of the macro | |
50 | whose name is the first argument. | |
51 | Each occurrence of $\fIn\fR in the replacement text, | |
52 | where | |
53 | .I n | |
54 | is a digit, | |
55 | is replaced by the | |
56 | .IR n -th | |
57 | argument. | |
58 | Argument 0 is the name of the macro; | |
59 | missing arguments are replaced by the null string. | |
60 | .TP | |
61 | undefine | |
62 | removes the definition of the macro named in its argument. | |
63 | .TP | |
64 | ifdef | |
65 | If the first argument is defined, the value is the second argument, otherwise the third. | |
66 | If there is no third argument, the value is null. | |
67 | The word | |
68 | .I unix | |
69 | is predefined on UNIX versions of | |
70 | .IR m4 . | |
71 | .TP | |
72 | changequote | |
73 | Change quote characters to the first and second arguments. | |
74 | .I Changequote | |
75 | without arguments restores the original values | |
76 | (i.e., \`\|\'). | |
77 | .TP | |
78 | divert | |
79 | .I M4 | |
80 | maintains 10 output streams, | |
81 | numbered 0-9. | |
82 | The final output is the concatenation of the streams | |
83 | in numerical order; | |
84 | initially stream 0 is the current stream. | |
85 | The | |
86 | .I divert | |
87 | macro changes the current output stream to its (digit-string) | |
88 | argument. | |
89 | Output diverted to a stream other than 0 through 9 | |
90 | is discarded. | |
91 | .TP | |
92 | undivert | |
93 | causes immediate output of text from diversions named as | |
94 | arguments, or all diversions if no argument. | |
95 | Text may be undiverted into another diversion. | |
96 | Undiverting discards the diverted text. | |
97 | .TP | |
98 | divnum | |
99 | returns the value of the current output stream. | |
100 | .TP | |
101 | dnl | |
102 | reads and discards characters up to and including the next newline. | |
103 | .TP | |
104 | ifelse | |
105 | has three or more arguments. | |
106 | If the first argument is the same string as the second, | |
107 | then the value is the third argument. | |
108 | If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6 and 7. | |
109 | Otherwise, the value is either the fourth string, or, if it is not present, | |
110 | null. | |
111 | .TP | |
112 | incr | |
113 | returns the value of its argument incremented by 1. | |
114 | The value of the argument is calculated | |
115 | by interpreting an initial digit-string as a decimal number. | |
116 | .TP | |
117 | eval | |
118 | evaluates its argument as an arithmetic expression, using 32-bit arithmetic. | |
119 | Operators include +, \-, \(**, /, %, ^ (exponentiation); relationals; parentheses. | |
120 | .TP | |
121 | len | |
122 | returns the number of characters in its argument. | |
123 | .TP | |
124 | index | |
125 | returns the position in its first argument where the second argument begins (zero origin), | |
126 | or \-1 if the second argument does not occur. | |
127 | .TP | |
128 | substr | |
129 | returns a substring of its first argument. | |
130 | The second argument is a zero origin | |
131 | number selecting the first character; | |
132 | the third argument indicates the length of the substring. | |
133 | A missing third argument is taken to be large enough to extend to | |
134 | the end of the first string. | |
135 | .TP | |
136 | translit | |
137 | transliterates the characters in its first argument | |
138 | from the set given by the second argument to the set given by the third. | |
139 | No abbreviations are permitted. | |
140 | .TP | |
141 | include | |
142 | returns the contents of the file named in the argument. | |
143 | .TP | |
144 | sinclude | |
145 | is identical to | |
146 | .I include, | |
147 | except that it | |
148 | says nothing if the file is inaccessible. | |
149 | .TP | |
150 | syscmd | |
151 | executes the UNIX command given in the first argument. | |
152 | No value is returned. | |
153 | .TP | |
154 | maketemp | |
155 | fills in a string of XXXXX in its argument with the current process id. | |
156 | .TP | |
157 | errprint | |
158 | prints its argument | |
159 | on the diagnostic output file. | |
160 | .TP | |
161 | dumpdef | |
162 | prints current names and definitions, | |
163 | for the named items, or for all if no arguments are given. | |
164 | .dt | |
165 | .SH "SEE ALSO" | |
166 | B. W. Kernighan and D. M. Ritchie, | |
167 | .I The M4 Macro Processor |