| blob | d22b432140c2f0759ff018141f1161c08efe07b7 |
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.27 2005/01/17 07:44:22 ru Exp $
3 .\" $DragonFly: src/usr.bin/m4/m4.1,v 1.5 2007/07/30 22:11:33 swildner Exp $
4 .\"
5 .Dd July 3, 2004
6 .Dt M4 1
7 .Os
8 .Sh NAME
9 .Nm m4
10 .Nd macro language processor
11 .Sh SYNOPSIS
12 .Nm
13 .Op Fl d Ar flags
14 .Op Fl t Ar name
15 .Op Fl Pgs
16 .Op Fl D Ar name Ns Op = Ns Ar value
17 .Op Fl U Ar name
18 .Op Fl I Ar dirname
19 .Op Ar
20 .Sh DESCRIPTION
21 The
22 .Nm
23 utility is a macro processor that can be used as a front end to any
24 language (e.g., C, ratfor, fortran, lex, and yacc).
25 The
26 .Nm
27 utility reads from the standard input and writes
28 the processed text to the standard output.
29 .Pp
30 Macro calls have the form
31 .Ic name Ns Pq Ar argument1 Ns Op , Ar argument2 , ... , argumentN .
32 .Pp
33 There cannot be any space following the macro name and the open
34 parenthesis
35 .Pq Ql \&( .
36 If the macro name is not followed by an open
37 parenthesis it is processed with no arguments.
38 .Pp
39 Macro names consist of a leading alphabetic or underscore
40 possibly followed by alphanumeric or underscore characters, e.g.,
41 valid macro names match the pattern
42 .Dq Li [a-zA-Z_][a-zA-Z0-9_]* .
43 .Pp
44 In arguments to macros, leading unquoted space, tab, and newline
45 .Pq Ql \en
46 characters are ignored.
47 To quote strings, use left and right single
48 quotes (e.g.,
49 .Sq "\ this is a string with a leading space" ) .
50 You can change the quote characters with the
51 .Ic changequote
52 built-in macro.
53 .Pp
54 Most built-ins do not make any sense without arguments, and hence are not
55 recognized as special when not followed by an open parenthesis.
56 .Pp
57 The options are as follows:
58 .Bl -tag -width indent
59 .It Fl s
60 Emit
61 .Ic #line
62 directives for
63 .Xr cpp 1 .
64 .It Fl D Ar name Ns Op = Ns Ar value
65 Define the symbol
66 .Ar name
67 to have some value (or
68 .Dv NULL ) .
69 .It Fl U Ar name
70 Undefine the symbol
71 .Ar name .
72 .It Fl P
73 Prefixes all
74 .Nm
75 builtin macros with the string
76 .Li m4_ .
77 This changes the macro names
78 .Li dnl
79 to
80 .Li m4_dnl ,
81 .Li index
82 to
83 .Li m4_index ,
84 and so forth.
85 .It Fl I Ar dirname
86 Add directory
87 .Ar dirname
88 to the include path.
89 .It Fl d Ar flags
90 Set trace flags.
91 The
92 .Ar flags
93 argument may hold the following:
94 .Pp
95 .Bl -tag -width indent -compact
96 .It Cm a
97 print macro arguments
98 .It Cm c
99 print macro expansion over several lines
100 .It Cm e
101 print result of macro expansion
102 .It Cm f
103 print filename location
104 .It Cm l
105 print line number
106 .It Cm q
107 quote arguments and expansion with the current quotes
108 .It Cm t
109 start with all macros traced
110 .It Cm x
111 number macro expansions
112 .It Cm V
113 turn on all options
114 .El
115 .Pp
116 By default, trace is set to
117 .Cm eq .
118 .It Fl t Ar macro
119 Turn tracing on for
120 .Ar macro .
121 .It Fl g
122 Activate GNU-m4 compatibility mode.
123 In this mode,
124 .Ic changequote
125 with two empty parameters deactivates quotes,
126 .Ic translit
127 handles simple character ranges (e.g.,
128 .Li a-z ) ,
129 regular expressions mimic
130 .Xr emacs 1
131 behavior,
132 and the number of diversions is unlimited.
133 .El
134 .Sh SYNTAX
135 The
136 .Nm
137 utility provides the following built-in macros.
138 They may be redefined, losing their original meaning.
139 Return values are null unless otherwise stated.
140 .Bl -tag -width ".Ic changequote"
141 .It Ic builtin
142 Calls a built-in by its name, overriding possible redefinitions.
143 .It Ic changecom
144 Changes the start and end comment sequences.
145 The default is the pound sign
146 .Pq Ql #
147 and the newline character.
148 With no arguments, the comment sequence is reset to the default,
149 in GNU
150 .Nm
151 mode, comments are turned off.
152 The maximum length for a comment marker is five characters.
153 .It Ic changequote
154 Defines the quote symbols to be the first and second arguments.
155 The symbols may be up to five characters long.
156 If no arguments are
157 given it restores the default open and close single quotes.
158 .It Ic decr
159 Decrements the argument by 1.
160 The argument must be a valid numeric string.
161 .It Ic define
162 Define a new macro named by the first argument to have the
163 value of the second argument.
164 Each occurrence of
165 .Sq Li $ Ns Ar n
166 (where
167 .Ar n
168 is 0 through 9) is replaced by the
169 .Ar n Ns 'th
170 argument.
171 .Ql $0
172 is the name of the calling macro.
173 Undefined arguments are replaced by a null string.
174 .Ql $#
175 is replaced by the number of arguments;
176 .Ql $*
177 is replaced by all arguments comma separated;
178 .Ql $@
179 is the same as
180 .Ql $*
181 but all arguments are quoted against further expansion.
182 .It Ic defn
183 Returns the quoted definition for each argument.
184 This can be used to rename
185 macro definitions (even for built-in macros).
186 .It Ic divert
187 There are 10 output queues (numbered 0-9).
188 At the end of processing
189 .Nm
190 concatenates all the queues in numerical order to produce the
191 final output.
192 Initially the output queue is 0.
193 The
194 .Ic divert
195 macro allows you to select a new output queue (an invalid argument
196 passed to
197 .Ic divert
198 causes output to be discarded).
199 .It Ic divnum
200 Returns the current output queue number.
201 .It Ic dnl
202 Discards input characters up to and including the next newline.
203 .It Ic dumpdef
204 Prints the names and definitions for the named items, or for everything
205 if no arguments are passed.
206 .It Ic errprint
207 Prints the first argument on the standard error output stream.
208 .It Ic esyscmd
209 Passes its first argument to a shell and returns the shell's standard output.
210 Note that the shell shares its standard input and standard error with
211 .Nm .
212 .It Ic eval
213 Computes the first argument as an arithmetic expression using 32-bit
214 arithmetic.
215 Operators are the standard C ternary, arithmetic, logical,
216 shift, relational, bitwise, and parentheses operators.
217 You can specify
218 octal, decimal, and hexadecimal numbers as in C.
219 The second argument (if any)
220 specifies the radix for the result, and the third argument (if any)
221 specifies the minimum number of digits in the result.
222 .It Ic expr
223 This is an alias for
224 .Ic eval .
225 .It Ic ifdef
226 If the macro named by the first argument is defined then return the second
227 argument, otherwise the third.
228 If there is no third argument, the value is
229 .Dv NULL .
230 The word
231 .Ic unix
232 is predefined.
233 .It Ic ifelse
234 If the first argument matches the second argument then
235 .Ic ifelse
236 returns
237 the third argument.
238 If the match fails, the three arguments are
239 discarded and the next three arguments are used until there is
240 zero or one arguments left, either this last argument or
241 .Dv NULL
242 is returned if no other matches were found.
243 .It Ic include
244 Returns the contents of the file specified in the first argument.
245 If the file is not found as is, look through the include path:
246 first the directories specified with
247 .Fl I
248 on the command line, then the environment variable
249 .Ev M4PATH ,
250 as a colon-separated list of directories.
251 Aborts with an error message if the file cannot be included.
252 .It Ic incr
253 Increments the argument by 1.
254 The argument must be a valid numeric string.
255 .It Ic index
256 Returns the index of the second argument in the first argument (e.g.,
257 .Fn index "the quick brown fox jumped" fox
258 returns 16).
259 If the second
260 argument is not found,
261 .Ic index
262 returns \-1.
263 .It Ic indir
264 Indirectly calls the macro whose name is passed as the first arguments,
265 with the remaining arguments passed as first, etc.\& arguments.
266 .It Ic len
267 Returns the number of characters in the first argument.
268 Extra arguments
269 are ignored.
270 .It Ic m4exit
271 Immediately exits with the return value specified by the first argument,
272 0 if none.
273 .It Ic m4wrap
274 Allows you to define what happens at the final
275 .Dv EOF ,
276 usually for cleanup purposes (e.g.,
277 .Fn m4wrap cleanup(tempfile)
278 causes the macro
279 .Ic cleanup
280 to be
281 invoked after all other processing is done).
282 .It Ic maketemp
283 Translates the string
284 .Dq Li XXXXX
285 in the first argument with the current process
286 ID leaving other characters alone.
287 This can be used to create unique
288 temporary file names.
289 .It Ic paste
290 Includes the contents of the file specified by the first argument without
291 any macro processing.
292 Aborts with an error message if the file cannot be
293 included.
294 .It Ic patsubst
295 Substitutes a regular expression in a string with a replacement string.
296 Usual substitution patterns apply: an ampersand
297 .Pq Ql &
298 is replaced by the string matching the regular expression.
299 The string
300 .Sq \e Ns Ar # ,
301 where
302 .Ar #
303 is a digit, is replaced by the corresponding back-reference.
304 .It Ic popdef
305 Restores the
306 .Ic pushdef Ns ed
307 definition for each argument.
308 .It Ic pushdef
309 Takes the same arguments as
310 .Ic define ,
311 but it saves the definition on a
312 stack for later retrieval by
313 .Ic popdef .
314 .It Ic regexp
315 Finds a regular expression in a string.
316 If no further arguments are given,
317 it returns the first match position or \-1 if no match.
318 If a third argument
319 is provided, it returns the replacement string, with sub-patterns replaced.
320 .It Ic shift
321 Returns all but the first argument, the remaining arguments are
322 quoted and pushed back with commas in between.
323 The quoting
324 nullifies the effect of the extra scan that will subsequently be
325 performed.
326 .It Ic sinclude
327 Similar to
328 .Ic include ,
329 except it ignores any errors.
330 .It Ic spaste
331 Similar to
332 .Ic paste ,
333 except it ignores any errors.
334 .It Ic substr
335 Returns a substring of the first argument starting at the offset specified
336 by the second argument and the length specified by the third argument.
337 If no third argument is present it returns the rest of the string.
338 .It Ic syscmd
339 Passes the first argument to the shell.
340 Nothing is returned.
341 .It Ic sysval
342 Returns the return value from the last
343 .Ic syscmd .
344 .It Ic traceon
345 Enables tracing of macro expansions for the given arguments, or for all
346 macros if no argument is given.
347 .It Ic traceoff
348 Disables tracing of macro expansions for the given arguments, or for all
349 macros if no argument is given.
350 .It Ic translit
351 Transliterate the characters in the first argument from the set
352 given by the second argument to the set given by the third.
353 You cannot use
354 .Xr tr 1
355 style abbreviations.
356 .It Ic undefine
357 Removes the definition for the macros specified by its arguments.
358 .It Ic undivert
359 Flushes the named output queues (or all queues if no arguments).
360 .It Ic unix
361 A pre-defined macro for testing the OS platform.
362 .It Ic __line__
363 Returns the current file's line number.
364 .It Ic __file__
365 Returns the current file's name.
366 .El
367 .Sh EXIT STATUS
368 .Ex -std
369 .Pp
370 The
371 .Ic m4exit
372 macro may be used to change the exit status from the input file.
373 .Sh COMPATIBILITY
374 The
375 .Nm
376 utility follows the
377 .St -susv2 ,
378 along with a few extensions taken from GNU-m4.
379 Flags
380 .Fl I , d ,
381 and
382 .Fl t
383 are non-standard.
384 .Pp
385 The output format of tracing and of
386 .Ic dumpdef
387 are not specified in any standard,
388 are likely to change and should not be relied upon.
389 The current format of tracing is closely modeled on GNU-m4,
390 to allow
391 .Nm autoconf
392 to work.
393 .Pp
394 For portability, one should not use the macros
395 .Ic builtin ,
396 .Ic esyscmd ,
397 .Ic expr ,
398 .Ic indir ,
399 .Ic paste ,
400 .Ic patsubst ,
401 .Ic regexp ,
402 .Ic spaste ,
403 .Ic unix ,
404 .Ic __line__ ,
405 and
406 .Ic __file__ .
407 .Pp
408 All built-ins do expand without arguments in many other
409 .Nm
410 implementations.
411 .Pp
412 Many other
413 .Nm
414 implementations have dire size limitations with respect to buffer sizes.
415 .Sh STANDARDS
416 The
417 .Nm
418 utility
419 conforms to
420 .St -p1003.1-2001 .
421 .Sh HISTORY
422 An
423 .Nm
424 command appeared in PWB
425 .Ux .
426 .Sh AUTHORS
427 .An -nosplit
428 .An Ozan Yigit Aq oz@sis.yorku.ca
429 and
430 .An Richard A. O'Keefe Aq ok@goanna.cs.rmit.OZ.AU .
431 GNU-m4 compatibility extensions by
432 .An Marc Espie Aq espie@cvs.openbsd.org .
433 .Sh BUGS
434 The
435 .Nm
436 utility does not recognize multibyte characters.