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