1 .\" @(#) $OpenBSD: m4.1,v 1.24 2002/04/18 18:57:23 espie Exp $
2 .\" $FreeBSD: src/usr.bin/m4/m4.1,v 1.10.2.9 2003/04/26 14:29:55 schweikh Exp $
9 .Nd macro language processor
15 .Op Fl D Ar name Ns Op = Ns Ar value
22 utility is a macro processor that can be used as a front end to any
23 language (e.g., C, ratfor, fortran, lex, and yacc).
25 reads from the standard input and writes
26 the processed text to the standard output.
28 Macro calls have the form
29 .Ic name Ns Pq Ar argument1 Ns Op , Ar argument2 , ... , argumentN .
31 There cannot be any space following the macro name and the open
34 If the macro name is not followed by an open
35 parenthesis it is processed with no arguments.
37 Macro names consist of a leading alphabetic or underscore
38 possibly followed by alphanumeric or underscore characters, e.g.,
39 valid macro names match the pattern
40 .Dq Li [a-zA-Z_][a-zA-Z0-9_]* .
42 In arguments to macros, leading unquoted space, tab, and newline
44 characters are ignored.
45 To quote strings, use left and right single
47 .Sq "\ this is a string with a leading space" ) .
48 You can change the quote characters with the
52 Most built-ins do not make any sense without arguments, and hence are not
53 recognized as special when not followed by an open parenthesis.
55 The options are as follows:
56 .Bl -tag -width indent
62 .It Fl D Ar name Ns Op = Ns Ar value
65 to have some value (or
78 argument may hold the following:
80 .Bl -tag -width indent -compact
84 print macro expansion over several lines
86 print result of macro expansion
88 print filename location
92 quote arguments and expansion with the current quotes
94 start with all macros traced
96 number macro expansions
101 By default, trace is set to
107 Activate GNU-m4 compatibility mode.
110 with two empty parameters deactivates quotes,
112 handles simple character ranges (e.g.,
114 regular expressions mimic
117 and the number of diversions is unlimited.
122 utility provides the following built-in macros.
123 They may be redefined, losing their original meaning.
124 Return values are null unless otherwise stated.
125 .Bl -tag -width ".Ic changequote"
127 Calls a built-in by its name, overriding possible redefinitions.
129 Changes the start and end comment sequences.
130 The default is the pound sign
132 and the newline character.
133 With no arguments, the comment sequence is reset to the default,
136 mode, comments are turned off.
137 The maximum length for a comment marker is five characters.
139 Defines the quote symbols to be the first and second arguments.
140 The symbols may be up to five characters long.
142 given it restores the default open and close single quotes.
144 Decrements the argument by 1.
145 The argument must be a valid numeric string.
147 Define a new macro named by the first argument to have the
148 value of the second argument.
153 is 0 through 9) is replaced by the
157 is the name of the calling macro.
158 Undefined arguments are replaced by a null string.
160 is replaced by the number of arguments;
162 is replaced by all arguments comma separated;
166 but all arguments are quoted against further expansion.
168 Returns the quoted definition for each argument.
169 This can be used to rename
170 macro definitions (even for built-in macros).
172 There are 10 output queues (numbered 0-9).
173 At the end of processing
175 concatenates all the queues in numerical order to produce the
177 Initially the output queue is 0.
180 macro allows you to select a new output queue (an invalid argument
183 causes output to be discarded).
185 Returns the current output queue number.
187 Discards input characters up to and including the next newline.
189 Prints the names and definitions for the named items, or for everything
190 if no arguments are passed.
192 Prints the first argument on the standard error output stream.
194 Passes its first argument to a shell and returns the shell's standard output.
195 Note that the shell shares its standard input and standard error with
198 Computes the first argument as an arithmetic expression using 32-bit
200 Operators are the standard C ternary, arithmetic, logical,
201 shift, relational, bitwise, and parentheses operators.
203 octal, decimal, and hexadecimal numbers as in C.
204 The second argument (if any)
205 specifies the radix for the result, and the third argument (if any)
206 specifies the minimum number of digits in the result.
211 If the macro named by the first argument is defined then return the second
212 argument, otherwise the third.
213 If there is no third argument, the value is
219 If the first argument matches the second argument then
223 If the match fails, the three arguments are
224 discarded and the next three arguments are used until there is
225 zero or one arguments left, either this last argument or
227 is returned if no other matches were found.
229 Returns the contents of the file specified in the first argument.
230 If the file is not found as is, look through the include path:
231 first the directories specified with
233 on the command line, then the environment variable
235 as a colon-separated list of directories.
236 Aborts with an error message if the file cannot be included.
238 Increments the argument by 1.
239 The argument must be a valid numeric string.
241 Returns the index of the second argument in the first argument (e.g.,
242 .Fn index "the quick brown fox jumped" fox
245 argument is not found,
249 Indirectly calls the macro whose name is passed as the first arguments,
250 with the remaining arguments passed as first, etc. arguments.
252 Returns the number of characters in the first argument.
256 Immediately exits with the return value specified by the first argument,
259 Allows you to define what happens at the final
261 usually for cleanup purposes (e.g.,
262 .Fn m4wrap cleanup(tempfile)
266 invoked after all other processing is done).
268 Translates the string
270 in the first argument with the current process
271 ID leaving other characters alone.
272 This can be used to create unique
273 temporary file names.
275 Includes the contents of the file specified by the first argument without
276 any macro processing.
277 Aborts with an error message if the file cannot be
280 Substitutes a regular expression in a string with a replacement string.
281 Usual substitution patterns apply: an ampersand
283 is replaced by the string matching the regular expression.
288 is a digit, is replaced by the corresponding back-reference.
292 definition for each argument.
294 Takes the same arguments as
296 but it saves the definition on a
297 stack for later retrieval by
300 Finds a regular expression in a string.
301 If no further arguments are given,
302 it returns the first match position or \-1 if no match.
304 is provided, it returns the replacement string, with sub-patterns replaced.
306 Returns all but the first argument, the remaining arguments are
307 quoted and pushed back with commas in between.
309 nullifies the effect of the extra scan that will subsequently be
314 except it ignores any errors.
318 except it ignores any errors.
320 Returns a substring of the first argument starting at the offset specified
321 by the second argument and the length specified by the third argument.
322 If no third argument is present it returns the rest of the string.
324 Passes the first argument to the shell.
327 Returns the return value from the last
330 Enables tracing of macro expansions for the given arguments, or for all
331 macros if no argument is given.
333 Disables tracing of macro expansions for the given arguments, or for all
334 macros if no argument is given.
336 Transliterate the characters in the first argument from the set
337 given by the second argument to the set given by the third.
342 Removes the definition for the macros specified by its arguments.
344 Flushes the named output queues (or all queues if no arguments).
346 A pre-defined macro for testing the OS platform.
348 Returns the current file's line number.
350 Returns the current file's name.
357 macro may be used to change the exit status from the input file.
360 follows the Single Unix 2 specification, along with a few extensions taken
368 The output format of tracing and of
370 are not specified in any standard,
371 are likely to change and should not be relied upon.
372 The current format of tracing is closely modeled on GNU-m4,
377 For portability, one should not use the macros
391 All built-ins do expand without arguments in many other
397 implementations have dire size limitations with respect to buffer sizes.
407 command appeared in PWB UNIX.
410 .An Ozan Yigit Aq oz@sis.yorku.ca
412 .An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU .
413 GNU-m4 compatibility extensions by
414 .An Marc Espie Aq espie@cvs.openbsd.org .
tuxillo's projects / dragonfly.git / blob