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