1 .\" Copyright (C) Caldera International Inc. 2001-2002. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions are
7 .\" Redistributions of source code and documentation must retain the above
8 .\" copyright notice, this list of conditions and the following
11 .\" Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
18 .\" This product includes software developed or owned by Caldera
19 .\" International, Inc. Neither the name of Caldera International, Inc.
20 .\" nor the names of other contributors may be used to endorse or promote
21 .\" products derived from this software without specific prior written
24 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
25 .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
27 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
28 .\" DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
32 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
33 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
34 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
35 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 .\" @(#)m4.ms 6.3 (Berkeley) 6/5/93
41 Bell Laboratories, Murray Hill, NJ 07974.
43 .EH 'PSD:17-%''The M4 Macro Processor'
44 .OH 'The M4 Macro Processor''PSD:17-%'
49 \&\\$3\s-1\\$1\\s0\&\\$2
53 \&\\$3\f2\\$1\fP\&\\$2
57 \&\\$3\f3\\$1\fP\&\\$2
63 .if n .ta 5 10 15 20 25 30 35 40 45 50 55 60
64 .if t .ta .4i .8i 1.2i 1.6i 2i 2.4i 2.8i 3.2i 3.6i 4i 4.4i 4.8i 5.2i 5.6i
65 .if t .tr -\(mi|\(bv'\(fm^\(no*\(**
86 . \"2=not last lines; 4= no -xx; 8=no xx-
87 . \"special chars in programs
91 .\" .....TM 77-1273-6 39199 39199-11
94 The M4 Macro Processor
103 M4 is a macro processor available on
107 Its primary use has been as a
108 front end for Ratfor for those
109 cases where parameterless macros
110 are not adequately powerful.
111 It has also been used for languages as disparate as C and Cobol.
112 M4 is particularly suited for functional languages like Fortran, PL/I and C
113 since macros are specified in a functional notation.
115 M4 provides features seldom found even in much larger
123 arithmetic capabilities
125 string and substring functions
130 This paper is a user's manual for M4.
137 A macro processor is a useful way to enhance a programming language,
138 to make it more palatable
140 or to tailor it to a particular application.
147 are examples of the basic facility provided by
148 any macro processor _
149 replacement of text by other text.
151 The M4 macro processor is an extension of a macro processor called M3
152 which was written by D. M. Ritchie
153 for the AP-3 minicomputer;
154 M3 was in turn based on a macro processor implemented for [1].
155 Readers unfamiliar with the basic ideas of macro processing
156 may wish to read some of the discussion there.
158 M4 is a suitable front end for Ratfor and C,
159 and has also been used successfully with Cobol.
160 Besides the straightforward replacement of one string of text by another,
162 macros with arguments,
163 conditional macro expansion,
166 and some specialized string processing functions.
168 The basic operation of M4
169 is to copy its input to its output.
170 As the input is read, however, each alphanumeric ``token''
171 (that is, string of letters and digits) is checked.
172 If it is the name of a macro,
173 then the name of the macro is replaced by its defining text,
174 and the resulting string is pushed back onto the
175 input to be rescanned.
176 Macros may be called with arguments, in which case the arguments are collected
177 and substituted into the right places in the defining text
178 before it is rescanned.
180 M4 provides a collection of about twenty built-in
182 which perform various useful operations;
183 in addition, the user can define new macros.
184 Built-ins and user-defined macros work exactly the same way, except that
185 some of the built-in macros have side effects
186 on the state of the process.
196 Each argument file is processed in order;
197 if there are no arguments, or if an argument
199 the standard input is read at that point.
200 The processed text is written on the standard output,
201 which may be captured for subsequent processing with
203 m4 [files] >outputfile
207 usage is identical, but the program is called
212 The primary built-in function of M4
215 which is used to define new macros.
224 All subsequent occurrences of
229 must be alphanumeric and must begin with a letter
230 (the underscore \(ul counts as a letter).
232 is any text that contains balanced parentheses;
233 it may stretch over multiple lines.
235 Thus, as a typical example,
243 to be 100, and uses this ``symbolic constant'' in a later
247 The left parenthesis must immediately follow the word
252 If a macro or built-in name is not followed immediately by `(',
253 it is assumed to have no arguments.
254 This is the situation for
257 it is actually a macro with no arguments,
258 and thus when it is used there need be no (...) following it.
260 You should also notice that a macro name is only recognized as such
261 if it appears surrounded by non-alphanumerics.
270 is absolutely unrelated to the defined macro
272 even though it contains a lot of
275 Things may be defined in terms of other things.
281 defines both M and N to be 100.
286 Or, to say it another way, is
296 subsequently changes,
300 This behavior arises because
301 M4 expands macro names into their defining text as soon as it possibly can.
302 Here, that means that when the string
304 is seen as the arguments of
306 are being collected, it is immediately replaced by 100;
307 it's just as if you had said
313 If this isn't what you really want, there are two ways out of it.
314 The first, which is specific to this situation,
315 is to interchange the order of the definitions:
322 is defined to be the string
326 later, you'll always get the value of
333 which will be replaced by 100).
337 The more general solution is to delay the expansion of
344 Any text surrounded by the single quotes \(ga and \(aa
345 is not expanded immediately, but has the quotes stripped off.
351 the quotes around the
353 are stripped off as the argument is being collected,
354 but they have served their purpose, and
360 The general rule is that M4 always strips off
361 one level of single quotes whenever it evaluates
363 This is true even outside of
367 to appear in the output,
368 you have to quote it in the input,
374 As another instance of the same thing, which is a bit more surprising,
382 Perhaps regrettably, the
384 in the second definition is
385 evaluated as soon as it's seen;
388 100, so it's as if you had written
392 This statement is ignored by M4, since you can only define things that look
393 like names, but it obviously doesn't have the effect you wanted.
396 you must delay the evaluation by quoting:
403 it is often wise to quote the first argument of a macro.
405 If \` and \' are not convenient for some reason,
406 the quote characters can be changed with the built-in
411 makes the new quote characters the left and right brackets.
412 You can restore the original characters with just
417 There are two additional built-ins related to
420 removes the definition of some macro or built-in:
424 removes the definition of
426 (Why are the quotes absolutely necessary?)
427 Built-ins can be removed with
433 but once you remove one, you can never get it back.
437 provides a way to determine if a macro is currently defined.
438 In particular, M4 has pre-defined the names
442 on the corresponding systems, so you can
443 tell which one you're using:
445 ifdef(`unix', `define(wordsize,16)' )
446 ifdef(`gcos', `define(wordsize,36)' )
448 makes a definition appropriate for the particular machine.
449 Don't forget the quotes!
452 actually permits three arguments;
453 if the name is undefined, the value of
455 is then the third argument, as in
457 ifdef(`unix', on UNIX, not on UNIX)
462 So far we have discussed the simplest form of macro processing _
463 replacing one string by another (fixed) string.
464 User-defined macros may also have arguments, so different invocations
465 can have different results.
466 Within the replacement text for a macro
467 (the second argument of its
471 will be replaced by the
473 argument when the macro
479 define(bump, $1 = $1 + 1)
481 generates code to increment its argument by 1:
490 A macro can have as many arguments as you want,
491 but only the first nine are accessible,
496 (The macro name itself is
498 although that is less commonly used.)
499 Arguments that are not supplied are replaced by null strings,
501 we can define a macro
503 which simply concatenates its arguments, like this:
505 define(cat, $1$2$3$4$5$6$7$8$9)
518 are null, since no corresponding arguments were provided.
521 Leading unquoted blanks, tabs, or newlines that occur during argument collection
523 All other white space is retained.
533 Arguments are separated by commas, but parentheses are counted properly,
534 so a comma ``protected'' by parentheses does not terminate an argument.
539 there are only two arguments;
540 the second is literally
542 And of course a bare comma or parenthesis can be inserted by quoting it.
546 M4 provides two built-in functions for doing arithmetic
550 which increments its numeric argument by 1.
551 Thus to handle the common programming situation
552 where you want a variable to be defined as ``one more than N'',
556 define(N1, `incr(N)')
560 is defined as one more than the current value of
563 The more general mechanism for arithmetic is a built-in
566 which is capable of arbitrary arithmetic on integers.
567 It provides the operators
568 (in decreasing order of precedence)
571 ** or ^ (exponentiation)
576 & or && (logical and)
577 \(or or \(or\(or (logical or)
579 Parentheses may be used to group operations where needed.
581 an expression given to
583 must ultimately be numeric.
584 The numeric value of a true relation
586 is 1, and false is 0.
595 As a simple example, suppose we want
602 define(M, `eval(2**N+1)')
604 As a matter of principle, it is advisable
605 to quote the defining text for a macro
606 unless it is very simple indeed
608 it usually gives the result you want,
609 and is a good habit to get into.
613 You can include a new file in the input at any time by
614 the built-in function
619 inserts the contents of
624 The contents of the file is often a set of definitions.
628 (that is, its replacement text)
629 is the contents of the file;
630 this can be captured in definitions, etc.
632 It is a fatal error if the file named in
635 To get some control over this situation, the alternate form
640 says nothing and continues if it can't access the file.
642 It is also possible to divert the output of M4 to temporary files during processing,
643 and output the collected material upon command.
644 M4 maintains nine of these diversions, numbered 1 through 9.
649 all subsequent output is put onto the end of a temporary file
652 Diverting to this file is stopped by another
659 resumes the normal output process.
661 Diverted text is normally output all at once
662 at the end of processing,
663 with the diversions output in numeric order.
664 It is possible, however, to bring back diversions
666 that is, to append them to the current diversion.
670 brings back all diversions in numeric order, and
672 with arguments brings back the selected diversions
674 The act of undiverting discards the diverted stuff,
675 as does diverting into a diversion
676 whose number is not between 0 and 9 inclusive.
684 Furthermore, the diverted material is
687 rescanned for macros.
691 returns the number of the currently active diversion.
692 This is zero during normal processing.
696 You can run any program in the local operating system
711 would be used to create a file
715 To facilitate making unique file names, the built-in
717 is provided, with specifications identical to the system function
720 a string of XXXXX in the argument is replaced
721 by the process id of the current process.
725 There is a built-in called
727 which enables you to perform arbitrary conditional testing.
728 In the simplest form,
732 compares the two strings
736 If these are identical,
743 Thus we might define a macro called
745 which compares two strings and returns ``yes'' or ``no''
746 if they are the same or different.
748 define(compare, `ifelse($1, $2, yes, no)')
751 which prevent too-early evaluation of
754 If the fourth argument is missing, it is treated as empty.
757 can actually have any number of arguments,
758 and thus provides a limited form of multi-way decision capability.
761 ifelse(a, b, c, d, e, f, g)
775 Otherwise the result is
777 If the final argument
778 is omitted, the result is null,
795 returns the length of the string that makes up its argument.
806 can be used to produce substrings of strings.
807 .UL substr(s,\ i,\ n)
808 returns the substring of
819 is omitted, the rest of the string is returned,
822 substr(`now is the time', 1)
832 are out of range, various sensible things happen.
835 returns the index (position) in
843 the origin for strings is 0.
847 performs character transliteration.
853 by replacing any character found in
855 by the corresponding character of
859 translit(s, aeiou, 12345)
861 replaces the vowels by the corresponding digits.
866 characters which don't have an entry in
868 are deleted; as a limiting case,
871 is not present at all,
883 There is also a built-in called
885 which deletes all characters that follow it up to
886 and including the next newline;
887 it is useful mainly for throwing away
888 empty lines that otherwise tend to clutter up M4 output.
889 For example, if you say
895 the newline at the end of each line is not part of the definition,
896 so it is copied into the output, where it may not be wanted.
899 to each of these lines, the newlines will disappear.
901 Another way to achieve this, due to J. E. Weythman,
914 writes its arguments out on the standard error file.
917 errprint(`fatal error')
921 is a debugging aid which
922 dumps the current definitions of defined terms.
923 If there are no arguments, you get everything;
924 otherwise you get the ones you name as arguments.
925 Don't forget to quote the names!
929 Each entry is preceded by the
930 page number where it is described.
935 1 define(name, replacement)
939 5 dumpdef(`name', `name', ...)
940 5 errprint(s, s, ...)
941 4 eval(numeric expression)
942 3 ifdef(`name', this if true, this if false)
948 4 maketemp(...XXXXX...)
950 5 substr(string, position, number)
952 5 translit(str, from, to)
954 4 undivert(number,number,...)
959 We are indebted to Rick Becker, John Chambers,
961 and especially Jim Weythman,
962 whose pioneering use of M4 has led to several valuable improvements.
963 We are also deeply grateful to Weythman for several substantial contributions
970 B. W. Kernighan and P. J. Plauger,
973 Addison-Wesley, Inc., 1976.
projects / FreeBSD / releng / 10.0.git / blob