| blob | 78bcd6f5f004ee68597b3260a76258b9320d4ea9 |
1 .\" $NetBSD: m4.1,v 1.22 2010/05/14 17:14:28 joerg Exp $
2 .\" @(#) $OpenBSD: m4.1,v 1.56 2009/10/14 17:19:47 sthen Exp $
3 .\"
4 .\" Copyright (c) 1989, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" This code is derived from software contributed to Berkeley by
8 .\" Ozan Yigit at York University.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .\" $FreeBSD: src/usr.bin/m4/m4.1,v 1.30 2012/11/17 01:54:24 svnexp Exp $
35 .\"
36 .Dd October 14, 2009
37 .Dt M4 1
38 .Os
39 .Sh NAME
40 .Nm m4
41 .Nd macro language processor
42 .Sh SYNOPSIS
43 .Nm
44 .Op Fl gPs
45 .Oo
46 .Sm off
47 .Fl D Ar name Op No = Ar value
48 .Sm on
49 .Oc
50 .Op Fl d Ar flags
51 .Op Fl I Ar dirname
52 .Op Fl o Ar filename
53 .Bk -words
54 .Op Fl t Ar macro
55 .Op Fl U Ns Ar name
56 .Op Ar
57 .Ek
58 .Sh DESCRIPTION
59 The
60 .Nm
61 utility is a macro processor that can be used as a front end to any
62 language (e.g., C, ratfor, fortran, lex, and yacc).
63 If no input files are given,
64 .Nm
65 reads from the standard input,
66 otherwise files specified on the command line are
67 processed in the given order.
68 Input files can be regular files, files in the m4 include paths, or a
69 single dash
70 .Pq Sq - ,
71 denoting standard input.
72 .Nm
73 writes
74 the processed text to the standard output, unless told otherwise.
75 .Pp
76 Macro calls have the form name(argument1[, argument2, ..., argumentN]).
77 .Pp
78 There cannot be any space following the macro name and the open
79 parenthesis
80 .Sq \&( .
81 If the macro name is not followed by an open
82 parenthesis it is processed with no arguments.
83 .Pp
84 Macro names consist of a leading alphabetic or underscore
85 possibly followed by alphanumeric or underscore characters, e.g.,
86 valid macro names match the pattern
87 .Dq [a-zA-Z_][a-zA-Z0-9_]* .
88 .Pp
89 In arguments to macros, leading unquoted space, tab, and newline
90 .Pq Sq \en
91 characters are ignored.
92 To quote strings, use left and right single quotes
93 .Po e.g.,\ \&
94 .Sq "\ this is a string with a leading space"
95 .Pc .
96 You can change the quote characters with the
97 .Ic changequote
98 built-in macro.
99 .Pp
100 Most built-ins do not make any sense without arguments, and hence are not
101 recognized as special when not followed by an open parenthesis.
102 .Pp
103 The options are as follows:
104 .Bl -tag -width Ds
105 .It Fl D Ns Ar name Ns Op Pf = Ns Ar value
106 Define the symbol
107 .Ar name
108 to have some value (or
109 .Dv NULL ) .
110 .It Fl d Ar "flags"
111 Set trace flags.
112 .Ar flags
113 may hold the following:
114 .Bl -tag -width Ds
115 .It Ar a
116 print macro arguments.
117 .It Ar c
118 print macro expansion over several lines.
119 .It Ar e
120 print result of macro expansion.
121 .It Ar f
122 print filename location.
123 .It Ar l
124 print line number.
125 .It Ar q
126 quote arguments and expansion with the current quotes.
127 .It Ar t
128 start with all macros traced.
129 .It Ar x
130 number macro expansions.
131 .It Ar V
132 turn on all options.
133 .El
134 .Pp
135 By default, trace is set to
136 .Qq eq .
137 .It Fl g
138 Activate GNU-m4 compatibility mode.
139 In this mode, translit handles simple character
140 ranges (e.g., a-z), regular expressions mimic emacs behavior,
141 multiple m4wrap calls are handled as a stack,
142 the number of diversions is unlimited,
143 empty names for macro definitions are allowed,
144 and eval understands
145 .Sq 0rbase:value
146 numbers.
147 .It Fl I Ar "dirname"
148 Add directory
149 .Ar dirname
150 to the include path.
151 .It Fl o Ar filename
152 Send trace output to
153 .Ar filename .
154 .It Fl P
155 Prefix all built-in macros with
156 .Sq m4_ .
157 For example, instead of writing
158 .Ic define ,
159 use
160 .Ic m4_define .
161 .It Fl s
162 Output line synchronization directives, suitable for
163 .Xr cpp 1 .
164 .It Fl t Ar macro
165 Turn tracing on for
166 .Ar macro .
167 .It Fl "U" Ns Ar "name"
168 Undefine the symbol
169 .Ar name .
170 .El
171 .Sh SYNTAX
172 .Nm
173 provides the following built-in macros.
174 They may be redefined, losing their original meaning.
175 Return values are null unless otherwise stated.
176 .Bl -tag -width changequote
177 .It Fn builtin name
178 Calls a built-in by its
179 .Fa name ,
180 overriding possible redefinitions.
181 .It Fn changecom startcomment endcomment
182 Changes the start comment and end comment sequences.
183 Comment sequences may be up to five characters long.
184 The default values are the hash sign
185 and the newline character.
186 .Bd -literal -offset indent
187 # This is a comment
188 .Ed
189 .Pp
190 With no arguments, comments are turned off.
191 With one single argument, the end comment sequence is set
192 to the newline character.
193 .It Fn changequote beginquote endquote
194 Defines the open quote and close quote sequences.
195 Quote sequences may be up to five characters long.
196 The default values are the backquote character and the quote
197 character.
198 .Bd -literal -offset indent
199 `Here is a quoted string'
200 .Ed
201 .Pp
202 With no arguments, the default quotes are restored.
203 With one single argument, the close quote sequence is set
204 to the newline character.
205 .It Fn decr arg
206 Decrements the argument
207 .Fa arg
208 by 1.
209 The argument
210 .Fa arg
211 must be a valid numeric string.
212 .It Fn define name value
213 Define a new macro named by the first argument
214 .Fa name
215 to have the
216 value of the second argument
217 .Fa value .
218 Each occurrence of
219 .Sq $n
220 (where
221 .Ar n
222 is 0 through 9) is replaced by the
223 .Ar n Ns 'th
224 argument.
225 .Sq $0
226 is the name of the calling macro.
227 Undefined arguments are replaced by a null string.
228 .Sq $#
229 is replaced by the number of arguments;
230 .Sq $*
231 is replaced by all arguments comma separated;
232 .Sq $@
233 is the same as
234 .Sq $*
235 but all arguments are quoted against further expansion.
236 .It Fn defn name ...
237 Returns the quoted definition for each argument.
238 This can be used to rename
239 macro definitions (even for built-in macros).
240 .It Fn divert num
241 There are 10 output queues (numbered 0-9).
242 At the end of processing
243 .Nm
244 concatenates all the queues in numerical order to produce the
245 final output.
246 Initially the output queue is 0.
247 The divert
248 macro allows you to select a new output queue (an invalid argument
249 passed to divert causes output to be discarded).
250 .It Ic divnum
251 Returns the current output queue number.
252 .It Ic dnl
253 Discard input characters up to and including the next newline.
254 .It Fn dumpdef name ...
255 Prints the names and definitions for the named items, or for everything
256 if no arguments are passed.
257 .It Fn errprint msg
258 Prints the first argument on the standard error output stream.
259 .It Fn esyscmd cmd
260 Passes its first argument to a shell and returns the shell's standard output.
261 Note that the shell shares its standard input and standard error with
262 .Nm .
263 .It Fn eval expr
264 Computes the first argument as an arithmetic expression using 32-bit
265 arithmetic.
266 Operators are the standard C ternary, arithmetic, logical,
267 shift, relational, bitwise, and parentheses operators.
268 You can specify
269 octal, decimal, and hexadecimal numbers as in C.
270 The second argument (if any)
271 specifies the radix for the result and the third argument (if any)
272 specifies the minimum number of digits in the result.
273 .It Fn expr expr
274 This is an alias for
275 .Ic eval .
276 .It Fn format formatstring arg1 ...
277 Returns
278 .Fa formatstring
279 with escape sequences substituted with
280 .Fa arg1
281 and following arguments, in a way similar to
282 .Xr printf 3 .
283 This built-in is only available in GNU-m4 compatibility mode, and the only
284 parameters implemented are there for autoconf compatibility:
285 left-padding flag, an optional field width, a maximum field width,
286 *-specified field widths, and the %s and %c data type.
287 .It Fn ifdef name yes no
288 If the macro named by the first argument is defined then return the second
289 argument, otherwise the third.
290 If there is no third argument, the value is
291 .Dv NULL .
292 The word
293 .Qq unix
294 is predefined.
295 .It Fn ifelse a b yes ...
296 If the first argument
297 .Fa a
298 matches the second argument
299 .Fa b
300 then
301 .Fn ifelse
302 returns
303 the third argument
304 .Fa yes .
305 If the match fails the three arguments are
306 discarded and the next three arguments are used until there is
307 zero or one arguments left, either this last argument or
308 .Dv NULL
309 is returned if no other matches were found.
310 .It Fn include name
311 Returns the contents of the file specified in the first argument.
312 If the file is not found as is, look through the include path:
313 first the directories specified with
314 .Fl I
315 on the command line, then the environment variable
316 .Ev M4PATH ,
317 as a colon-separated list of directories.
318 Include aborts with an error message if the file cannot be included.
319 .It Fn incr arg
320 Increments the argument by 1.
321 The argument must be a valid numeric string.
322 .It Fn index string substring
323 Returns the index of the second argument in the first argument (e.g.,
324 .Ic index(the quick brown fox jumped, fox)
325 returns 16).
326 If the second
327 argument is not found index returns \-1.
328 .It Fn indir macro arg1 ...
329 Indirectly calls the macro whose name is passed as the first argument,
330 with the remaining arguments passed as first, ... arguments.
331 .It Fn len arg
332 Returns the number of characters in the first argument.
333 Extra arguments
334 are ignored.
335 .It Fn m4exit code
336 Immediately exits with the return value specified by the first argument,
337 0 if none.
338 .It Fn m4wrap todo
339 Allows you to define what happens at the final
340 .Dv EOF ,
341 usually for cleanup purposes (e.g.,
342 .Ic m4wrap("cleanup(tempfile)")
343 causes the macro cleanup to be
344 invoked after all other processing is done).
345 .Pp
346 Multiple calls to
347 .Fn m4wrap
348 get inserted in sequence at the final
349 .Dv EOF .
350 .It Fn maketemp template
351 Invokes
352 .Xr mkstemp 3
353 on the first argument, and returns the modified string.
354 This can be used to create unique
355 temporary file names.
356 .It Fn paste file
357 Includes the contents of the file specified by the first argument without
358 any macro processing.
359 Aborts with an error message if the file cannot be
360 included.
361 .It Fn patsubst string regexp replacement
362 Substitutes a regular expression in a string with a replacement string.
363 Usual substitution patterns apply: an ampersand
364 .Pq Sq \&&
365 is replaced by the string matching the regular expression.
366 The string
367 .Sq \e# ,
368 where
369 .Sq #
370 is a digit, is replaced by the corresponding back-reference.
371 .It Fn popdef arg ...
372 Restores the
373 .Ic pushdef Ns ed
374 definition for each argument.
375 .It Fn pushdef macro def
376 Takes the same arguments as
377 .Ic define ,
378 but it saves the definition on a
379 stack for later retrieval by
380 .Fn popdef .
381 .It Fn regexp string regexp replacement
382 Finds a regular expression in a string.
383 If no further arguments are given,
384 it returns the first match position or \-1 if no match.
385 If a third argument
386 is provided, it returns the replacement string, with sub-patterns replaced.
387 .It Fn shift arg1 ...
388 Returns all but the first argument, the remaining arguments are
389 quoted and pushed back with commas in between.
390 The quoting
391 nullifies the effect of the extra scan that will subsequently be
392 performed.
393 .It Fn sinclude file
394 Similar to
395 .Ic include ,
396 except it ignores any errors.
397 .It Fn spaste file
398 Similar to
399 .Fn paste ,
400 except it ignores any errors.
401 .It Fn substr string offset length
402 Returns a substring of the first argument starting at the offset specified
403 by the second argument and the length specified by the third argument.
404 If no third argument is present it returns the rest of the string.
405 .It Fn syscmd cmd
406 Passes the first argument to the shell.
407 Nothing is returned.
408 .It Ic sysval
409 Returns the return value from the last
410 .Ic syscmd .
411 .It Fn traceon arg ...
412 Enables tracing of macro expansions for the given arguments, or for all
413 macros if no argument is given.
414 .It Fn traceoff arg ...
415 Disables tracing of macro expansions for the given arguments, or for all
416 macros if no argument is given.
417 .It Fn translit string mapfrom mapto
418 Transliterate the characters in the first argument from the set
419 given by the second argument to the set given by the third.
420 You cannot use
421 .Xr tr 1
422 style abbreviations.
423 .It Fn undefine name1 ...
424 Removes the definition for the macros specified by its arguments.
425 .It Fn undivert arg ...
426 Flushes the named output queues (or all queues if no arguments).
427 .It Ic unix
428 A pre-defined macro for testing the OS platform.
429 .It Ic __line__
430 Returns the current file's line number.
431 .It Ic __file__
432 Returns the current file's name.
433 .El
434 .Sh STANDARDS
435 The
436 .Nm
437 utility is compliant with the
438 .St -p1003.1-2008
439 specification.
440 .Pp
441 The flags
442 .Op Fl dgIot
443 and the macros
444 .Ic builtin ,
445 .Ic esyscmd ,
446 .Ic expr ,
447 .Ic format ,
448 .Ic indir ,
449 .Ic paste ,
450 .Ic patsubst ,
451 .Ic regexp ,
452 .Ic spaste ,
453 .Ic unix ,
454 .Ic __line__ ,
455 and
456 .Ic __file__
457 are extensions to that specification.
458 .Pp
459 The output format of tracing and of
460 .Ic dumpdef
461 are not specified in any standard,
462 are likely to change and should not be relied upon.
463 The current format of tracing is closely modelled on
464 .Nm gnu-m4 ,
465 to allow
466 .Nm autoconf
467 to work.
468 .Pp
469 The built-ins
470 .Ic pushdef
471 and
472 .Ic popdef
473 handle macro definitions as a stack.
474 However,
475 .Ic define
476 interacts with the stack in an undefined way.
477 In this implementation,
478 .Ic define
479 replaces the top-most definition only.
480 Other implementations may erase all definitions on the stack instead.
481 .Pp
482 All built-ins do expand without arguments in many other
483 .Nm .
484 .Pp
485 Many other
486 .Nm
487 have dire size limitations with respect to buffer sizes.
488 .Sh AUTHORS
489 .An -nosplit
490 .An Ozan Yigit Aq Mt oz@sis.yorku.ca
491 and
492 .An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU .
493 .Pp
494 GNU-m4 compatibility extensions by
495 .An Marc Espie Aq Mt espie@cvs.openbsd.org .