1 This is m4.info, produced by makeinfo version 5.1 from m4.texi.
3 This manual (22 September 2013) is for GNU M4 (version 1.4.17), a
4 package containing an implementation of the m4 macro language.
6 Copyright (C) 1989-1994, 2004-2013 Free Software Foundation, Inc.
8 Permission is granted to copy, distribute and/or modify this
9 document under the terms of the GNU Free Documentation License,
10 Version 1.3 or any later version published by the Free Software
11 Foundation; with no Invariant Sections, no Front-Cover Texts, and
12 no Back-Cover Texts. A copy of the license is included in the
13 section entitled "GNU Free Documentation License."
14 INFO-DIR-SECTION Text creation and manipulation
16 * M4: (m4). A powerful macro processor.
20 File: m4.info, Node: Top, Next: Preliminaries, Up: (dir)
25 This manual (22 September 2013) is for GNU M4 (version 1.4.17), a
26 package containing an implementation of the m4 macro language.
28 Copyright (C) 1989-1994, 2004-2013 Free Software Foundation, Inc.
30 Permission is granted to copy, distribute and/or modify this
31 document under the terms of the GNU Free Documentation License,
32 Version 1.3 or any later version published by the Free Software
33 Foundation; with no Invariant Sections, no Front-Cover Texts, and
34 no Back-Cover Texts. A copy of the license is included in the
35 section entitled "GNU Free Documentation License."
37 GNU 'm4' is an implementation of the traditional UNIX macro
38 processor. It is mostly SVR4 compatible, although it has some
39 extensions (for example, handling more than 9 positional parameters to
40 macros). 'm4' also has builtin functions for including files, running
41 shell commands, doing arithmetic, etc. Autoconf needs GNU 'm4' for
42 generating 'configure' scripts, but not for running them.
44 GNU 'm4' was originally written by Rene' Seindal, with subsequent
45 changes by Franc,ois Pinard and other volunteers on the Internet. All
46 names and email addresses can be found in the files 'm4-1.4.17/AUTHORS'
47 and 'm4-1.4.17/THANKS' from the GNU M4 distribution.
49 This is release 1.4.17. It is now considered stable: future releases
50 in the 1.4.x series are only meant to fix bugs, increase speed, or
51 improve documentation. However...
53 An experimental feature, which would improve 'm4' usefulness, allows
54 for changing the syntax for what is a "word" in 'm4'. You should use:
55 ./configure --enable-changeword
56 if you want this feature compiled in. The current implementation slows
57 down 'm4' considerably and is hardly acceptable. In the future, 'm4'
58 2.0 will come with a different set of new features that provide similar
59 capabilities, but without the inefficiencies, so changeword will go away
60 and _you should not count on it_.
64 * Preliminaries:: Introduction and preliminaries
65 * Invoking m4:: Invoking 'm4'
66 * Syntax:: Lexical and syntactic conventions
68 * Macros:: How to invoke macros
69 * Definitions:: How to define new macros
70 * Conditionals:: Conditionals, loops, and recursion
72 * Debugging:: How to debug macros and input
74 * Input Control:: Input control
75 * File Inclusion:: File inclusion
76 * Diversions:: Diverting and undiverting output
78 * Text handling:: Macros for text handling
79 * Arithmetic:: Macros for doing arithmetic
80 * Shell commands:: Macros for running shell commands
81 * Miscellaneous:: Miscellaneous builtin macros
82 * Frozen files:: Fast loading of frozen state
84 * Compatibility:: Compatibility with other versions of 'm4'
85 * Answers:: Correct version of some examples
87 * Copying This Package:: How to make copies of the overall M4 package
88 * Copying This Manual:: How to make copies of this manual
89 * Indices:: Indices of concepts and macros
91 -- The Detailed Node Listing --
93 Introduction and preliminaries
95 * Intro:: Introduction to 'm4'
96 * History:: Historical references
97 * Bugs:: Problems and bugs
98 * Manual:: Using this manual
102 * Operation modes:: Command line options for operation modes
103 * Preprocessor features:: Command line options for preprocessor features
104 * Limits control:: Command line options for limits control
105 * Frozen state:: Command line options for frozen state
106 * Debugging options:: Command line options for debugging
107 * Command line files:: Specifying input files on the command line
109 Lexical and syntactic conventions
111 * Names:: Macro names
112 * Quoted strings:: Quoting input to 'm4'
113 * Comments:: Comments in 'm4' input
114 * Other tokens:: Other kinds of input tokens
115 * Input processing:: How 'm4' copies input to output
119 * Invocation:: Macro invocation
120 * Inhibiting Invocation:: Preventing macro invocation
121 * Macro Arguments:: Macro arguments
122 * Quoting Arguments:: On Quoting Arguments to macros
123 * Macro expansion:: Expanding macros
125 How to define new macros
127 * Define:: Defining a new macro
128 * Arguments:: Arguments to macros
129 * Pseudo Arguments:: Special arguments to macros
130 * Undefine:: Deleting a macro
131 * Defn:: Renaming macros
132 * Pushdef:: Temporarily redefining macros
134 * Indir:: Indirect call of macros
135 * Builtin:: Indirect call of builtins
137 Conditionals, loops, and recursion
139 * Ifdef:: Testing if a macro is defined
140 * Ifelse:: If-else construct, or multibranch
141 * Shift:: Recursion in 'm4'
142 * Forloop:: Iteration by counting
143 * Foreach:: Iteration by list contents
144 * Stacks:: Working with definition stacks
145 * Composition:: Building macros with macros
147 How to debug macros and input
149 * Dumpdef:: Displaying macro definitions
150 * Trace:: Tracing macro calls
151 * Debug Levels:: Controlling debugging output
152 * Debug Output:: Saving debugging output
156 * Dnl:: Deleting whitespace in input
157 * Changequote:: Changing the quote characters
158 * Changecom:: Changing the comment delimiters
159 * Changeword:: Changing the lexical structure of words
160 * M4wrap:: Saving text until end of input
164 * Include:: Including named files
165 * Search Path:: Searching for include files
167 Diverting and undiverting output
169 * Divert:: Diverting output
170 * Undivert:: Undiverting output
171 * Divnum:: Diversion numbers
172 * Cleardivert:: Discarding diverted text
174 Macros for text handling
176 * Len:: Calculating length of strings
177 * Index macro:: Searching for substrings
178 * Regexp:: Searching for regular expressions
179 * Substr:: Extracting substrings
180 * Translit:: Translating characters
181 * Patsubst:: Substituting text by regular expression
182 * Format:: Formatting strings (printf-like)
184 Macros for doing arithmetic
186 * Incr:: Decrement and increment operators
187 * Eval:: Evaluating integer expressions
189 Macros for running shell commands
191 * Platform macros:: Determining the platform
192 * Syscmd:: Executing simple commands
193 * Esyscmd:: Reading the output of commands
194 * Sysval:: Exit status
195 * Mkstemp:: Making temporary files
197 Miscellaneous builtin macros
199 * Errprint:: Printing error messages
200 * Location:: Printing current location
201 * M4exit:: Exiting from 'm4'
203 Fast loading of frozen state
205 * Using frozen files:: Using frozen files
206 * Frozen file format:: Frozen file format
208 Compatibility with other versions of 'm4'
210 * Extensions:: Extensions in GNU M4
211 * Incompatibilities:: Facilities in System V m4 not in GNU M4
212 * Other Incompatibilities:: Other incompatibilities
214 Correct version of some examples
216 * Improved exch:: Solution for 'exch'
217 * Improved forloop:: Solution for 'forloop'
218 * Improved foreach:: Solution for 'foreach'
219 * Improved copy:: Solution for 'copy'
220 * Improved m4wrap:: Solution for 'm4wrap'
221 * Improved cleardivert:: Solution for 'cleardivert'
222 * Improved capitalize:: Solution for 'capitalize'
223 * Improved fatal_error:: Solution for 'fatal_error'
225 How to make copies of the overall M4 package
227 * GNU General Public License:: License for copying the M4 package
229 How to make copies of this manual
231 * GNU Free Documentation License:: License for copying this manual
233 Indices of concepts and macros
235 * Macro index:: Index for all 'm4' macros
236 * Concept index:: Index for many concepts
240 File: m4.info, Node: Preliminaries, Next: Invoking m4, Prev: Top, Up: Top
242 1 Introduction and preliminaries
243 ********************************
245 This first chapter explains what GNU 'm4' is, where 'm4' comes from, how
246 to read and use this documentation, how to call the 'm4' program, and
247 how to report bugs about it. It concludes by giving tips for reading
248 the remainder of the manual.
250 The following chapters then detail all the features of the 'm4'
255 * Intro:: Introduction to 'm4'
256 * History:: Historical references
257 * Bugs:: Problems and bugs
258 * Manual:: Using this manual
261 File: m4.info, Node: Intro, Next: History, Up: Preliminaries
263 1.1 Introduction to 'm4'
264 ========================
266 'm4' is a macro processor, in the sense that it copies its input to the
267 output, expanding macros as it goes. Macros are either builtin or
268 user-defined, and can take any number of arguments. Besides just doing
269 macro expansion, 'm4' has builtin functions for including named files,
270 running shell commands, doing integer arithmetic, manipulating text in
271 various ways, performing recursion, etc.... 'm4' can be used either as a
272 front-end to a compiler, or as a macro processor in its own right.
274 The 'm4' macro processor is widely available on all UNIXes, and has
275 been standardized by POSIX. Usually, only a small percentage of users
276 are aware of its existence. However, those who find it often become
277 committed users. The popularity of GNU Autoconf, which requires GNU
278 'm4' for _generating_ 'configure' scripts, is an incentive for many to
279 install it, while these people will not themselves program in 'm4'. GNU
280 'm4' is mostly compatible with the System V, Release 4 version, except
281 for some minor differences. *Note Compatibility::, for more details.
283 Some people find 'm4' to be fairly addictive. They first use 'm4'
284 for simple problems, then take bigger and bigger challenges, learning
285 how to write complex sets of 'm4' macros along the way. Once really
286 addicted, users pursue writing of sophisticated 'm4' applications even
287 to solve simple problems, devoting more time debugging their 'm4'
288 scripts than doing real work. Beware that 'm4' may be dangerous for the
289 health of compulsive programmers.
292 File: m4.info, Node: History, Next: Bugs, Prev: Intro, Up: Preliminaries
294 1.2 Historical references
295 =========================
297 Macro languages were invented early in the history of computing. In the
298 1950s Alan Perlis suggested that the macro language be independent of
299 the language being processed. Techniques such as conditional and
300 recursive macros, and using macros to define other macros, were
301 described by Doug McIlroy of Bell Labs in "Macro Instruction Extensions
302 of Compiler Languages", _Communications of the ACM_ 3, 4 (1960), 214-20,
303 <http://dx.doi.org/10.1145/367177.367223>.
305 An important precursor of 'm4' was GPM; see C. Strachey, "A general
306 purpose macrogenerator", _Computer Journal_ 8, 3 (1965), 225-41,
307 <http://dx.doi.org/10.1093/comjnl/8.3.225>. GPM is also succinctly
308 described in David Gries's book _Compiler Construction for Digital
309 Computers_, Wiley (1971). Strachey was a brilliant programmer: GPM fit
310 into 250 machine instructions!
312 Inspired by GPM while visiting Strachey's Lab in 1968, McIlroy wrote
313 a model preprocessor in that fit into a page of Snobol 3 code, and
314 McIlroy and Robert Morris developed a series of further models at Bell
315 Labs. Andrew D. Hall followed up with M6, a general purpose macro
316 processor used to port the Fortran source code of the Altran computer
317 algebra system; see Hall's "The M6 Macro Processor", Computing Science
318 Technical Report #2, Bell Labs (1972),
319 <http://cm.bell-labs.com/cm/cs/cstr/2.pdf>. M6's source code consisted
320 of about 600 Fortran statements. Its name was the first of the 'm4'
323 The Brian Kernighan and P.J. Plauger book _Software Tools_,
324 Addison-Wesley (1976), describes and implements a Unix macro-processor
325 language, which inspired Dennis Ritchie to write 'm3', a macro processor
326 for the AP-3 minicomputer.
328 Kernighan and Ritchie then joined forces to develop the original
329 'm4', described in "The M4 Macro Processor", Bell Laboratories (1977),
330 <http://wolfram.schneider.org/bsd/7thEdManVol2/m4/m4.pdf>. It had only
333 While 'GPM' was more _pure_, 'm4' is meant to deal with the true
334 intricacies of real life: macros can be recognized without being
335 pre-announced, skipping whitespace or end-of-lines is easier, more
336 constructs are builtin instead of derived, etc.
338 Originally, the Kernighan and Plauger macro-processor, and then 'm3',
339 formed the engine for the Rational FORTRAN preprocessor, that is, the
340 'Ratfor' equivalent of 'cpp'. Later, 'm4' was used as a front-end for
341 'Ratfor', 'C' and 'Cobol'.
343 Rene' Seindal released his implementation of 'm4', GNU 'm4', in 1990,
344 with the aim of removing the artificial limitations in many of the
345 traditional 'm4' implementations, such as maximum line length, macro
346 size, or number of macros.
348 The late Professor A. Dain Samples described and implemented a
349 further evolution in the form of 'M5': "User's Guide to the M5 Macro
350 Language: 2nd edition", Electronic Announcement on comp.compilers
353 Franc,ois Pinard took over maintenance of GNU 'm4' in 1992, until
354 1994 when he released GNU 'm4' 1.4, which was the stable release for 10
355 years. It was at this time that GNU Autoconf decided to require GNU
356 'm4' as its underlying engine, since all other implementations of 'm4'
357 had too many limitations.
359 More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which
360 addressed some long standing bugs in the venerable 1.4 release. Then in
361 2005, Gary V. Vaughan collected together the many patches to GNU 'm4'
362 1.4 that were floating around the net and released 1.4.3 and 1.4.4. And
363 in 2006, Eric Blake joined the team and prepared patches for the release
364 of 1.4.5, 1.4.6, 1.4.7, and 1.4.8. More bug fixes were incorporated in
365 2007, with releases 1.4.9 and 1.4.10. Eric continued with some
366 portability fixes for 1.4.11 and 1.4.12 in 2008, 1.4.13 in 2009, 1.4.14
367 and 1.4.15 in 2010, and 1.4.16 in 2011.
369 Meanwhile, development has continued on new features for 'm4', such
370 as dynamic module loading and additional builtins. When complete, GNU
371 'm4' 2.0 will start a new series of releases.
374 File: m4.info, Node: Bugs, Next: Manual, Prev: History, Up: Preliminaries
376 1.3 Problems and bugs
377 =====================
379 If you have problems with GNU M4 or think you've found a bug, please
380 report it. Before reporting a bug, make sure you've actually found a
381 real bug. Carefully reread the documentation and see if it really says
382 you can do what you're trying to do. If it's not clear whether you
383 should be able to do something or not, report that too; it's a bug in
386 Before reporting a bug or trying to fix it yourself, try to isolate
387 it to the smallest possible input file that reproduces the problem.
388 Then send us the input file and the exact results 'm4' gave you. Also
389 say what you expected to occur; this will help us decide whether the
390 problem was really in the documentation.
392 Once you've got a precise problem, send e-mail to <bug-m4@gnu.org>.
393 Please include the version number of 'm4' you are using. You can get
394 this information with the command 'm4 --version'. Also provide details
395 about the platform you are executing on.
397 Non-bug suggestions are always welcome as well. If you have
398 questions about things that are unclear in the documentation or are just
399 obscure features, please report them too.
402 File: m4.info, Node: Manual, Prev: Bugs, Up: Preliminaries
404 1.4 Using this manual
405 =====================
407 This manual contains a number of examples of 'm4' input and output, and
408 a simple notation is used to distinguish input, output and error
409 messages from 'm4'. Examples are set out from the normal text, and
410 shown in a fixed width font, like this
412 This is an example of an example!
414 To distinguish input from output, all output from 'm4' is prefixed by
415 the string '=>', and all error messages by the string 'error->'. When
416 showing how command line options affect matters, the command line is
417 shown with a prompt '$ 'like this'', otherwise, you can assume that a
418 simple 'm4' invocation will work. Thus:
420 $ command line to invoke m4
421 Example of input line
422 =>Output line from m4
423 error->and an error message
425 The sequence '^D' in an example indicates the end of the input file.
426 The sequence '<NL>' refers to the newline character. The majority of
427 these examples are self-contained, and you can run them with similar
428 results by invoking 'm4 -d'. In fact, the testsuite that is bundled in
429 the GNU M4 package consists of the examples in this document! Some of
430 the examples assume that your current directory is located where you
431 unpacked the installation, so if you plan on following along, you may
432 find it helpful to do this now:
436 As each of the predefined macros in 'm4' is described, a prototype
437 call of the macro will be shown, giving descriptive names to the
440 -- Composite: example (STRING, [COUNT = '1']
441 [ARGUMENT]This is a sample prototype. There is not really a macro
442 named 'example', but this documents that if there were, it would be
443 a Composite macro, rather than a Builtin. It requires at least one
444 argument, STRING. Remember that in 'm4', there must not be a space
445 between the macro name and the opening parenthesis, unless it was
446 intended to call the macro without any arguments. The brackets
447 around COUNT and ARGUMENT show that these arguments are optional.
448 If COUNT is omitted, the macro behaves as if count were '1',
449 whereas if ARGUMENT is omitted, the macro behaves as if it were the
450 empty string. A blank argument is not the same as an omitted
451 argument. For example, 'example(`a')', 'example(`a',`1')', and
452 'example(`a',`1',)' would behave identically with COUNT set to '1';
453 while 'example(`a',)' and 'example(`a',`')' would explicitly pass
454 the empty string for COUNT. The ellipses ('...') show that the
455 macro processes additional arguments after ARGUMENT, rather than
458 All macro arguments in 'm4' are strings, but some are given special
459 interpretation, e.g., as numbers, file names, regular expressions, etc.
460 The documentation for each macro will state how the parameters are
461 interpreted, and what happens if the argument cannot be parsed according
462 to the desired interpretation. Unless specified otherwise, a parameter
463 specified to be a number is parsed as a decimal, even if the argument
464 has leading zeros; and parsing the empty string as a number results in 0
465 rather than an error, although a warning will be issued.
467 This document consistently writes and uses "builtin", without a
468 hyphen, as if it were an English word. This is how the 'builtin'
469 primitive is spelled within 'm4'.
472 File: m4.info, Node: Invoking m4, Next: Syntax, Prev: Preliminaries, Up: Top
477 The format of the 'm4' command is:
479 m4 [OPTION...] [FILE...]
481 All options begin with '-', or if long option names are used, with
482 '--'. A long option name need not be written completely, any
483 unambiguous prefix is sufficient. POSIX requires 'm4' to recognize
484 arguments intermixed with files, even when 'POSIXLY_CORRECT' is set in
485 the environment. Most options take effect at startup regardless of
486 their position, but some are documented below as taking effect after any
487 files that occurred earlier in the command line. The argument '--' is a
488 marker to denote the end of options.
490 With short options, options that do not take arguments may be
491 combined into a single command line argument with subsequent options,
492 options with mandatory arguments may be provided either as a single
493 command line argument or as two arguments, and options with optional
494 arguments must be provided as a single argument. In other words, 'm4
495 -QPDfoo -d a -df' is equivalent to 'm4 -Q -P -D foo -d -df -- ./a',
496 although the latter form is considered canonical.
498 With long options, options with mandatory arguments may be provided
499 with an equal sign ('=') in a single argument, or as two arguments, and
500 options with optional arguments must be provided as a single argument.
501 In other words, 'm4 --def foo --debug a' is equivalent to 'm4
502 --define=foo --debug= -- ./a', although the latter form is considered
503 canonical (not to mention more robust, in case a future version of 'm4'
504 introduces an option named '--default').
506 'm4' understands the following options, grouped by functionality.
510 * Operation modes:: Command line options for operation modes
511 * Preprocessor features:: Command line options for preprocessor features
512 * Limits control:: Command line options for limits control
513 * Frozen state:: Command line options for frozen state
514 * Debugging options:: Command line options for debugging
515 * Command line files:: Specifying input files on the command line
518 File: m4.info, Node: Operation modes, Next: Preprocessor features, Up: Invoking m4
520 2.1 Command line options for operation modes
521 ============================================
523 Several options control the overall operation of 'm4':
526 Print a help summary on standard output, then immediately exit 'm4'
527 without reading any input files or performing any other actions.
530 Print the version number of the program on standard output, then
531 immediately exit 'm4' without reading any input files or performing
536 Controls the effect of warnings. If unspecified, then execution
537 continues and exit status is unaffected when a warning is printed.
538 If specified exactly once, warnings become fatal; when one is
539 issued, execution continues, but the exit status will be non-zero.
540 If specified multiple times, then execution halts with non-zero
541 status the first time a warning is issued. The introduction of
542 behavior levels is new to M4 1.4.9; for behavior consistent with
543 earlier versions, you should specify '-E' twice.
548 Makes this invocation of 'm4' interactive. This means that all
549 output will be unbuffered, and interrupts will be ignored. The
550 spelling '-e' exists for compatibility with other 'm4'
551 implementations, and issues a warning because it may be withdrawn
552 in a future version of GNU M4.
556 Internally modify _all_ builtin macro names so they all start with
557 the prefix 'm4_'. For example, using this option, one should write
558 'm4_define' instead of 'define', and 'm4___file__' instead of
559 '__file__'. This option has no effect if '-R' is also specified.
564 Suppress warnings, such as missing or superfluous arguments in
565 macro calls, or treating the empty string as zero.
567 '--warn-macro-sequence[=REGEXP]'
568 Issue a warning if the regular expression REGEXP has a non-empty
569 match in any macro definition (either by 'define' or 'pushdef').
570 Empty matches are ignored; therefore, supplying the empty string as
571 REGEXP disables any warning. If the optional REGEXP is not
572 supplied, then the default regular expression is
573 '\$\({[^}]*}\|[0-9][0-9]+\)' (a literal '$' followed by multiple
574 digits or by an open brace), since these sequences will change
575 semantics in the default operation of GNU M4 2.0 (due to a change
576 in how more than 9 arguments in a macro definition will be handled,
577 *note Arguments::). Providing an alternate regular expression can
578 provide a useful reverse lookup feature of finding where a macro is
579 defined to have a given definition.
582 '--word-regexp=REGEXP'
583 Use REGEXP as an alternative syntax for macro names. This
584 experimental option will not be present in all GNU 'm4'
585 implementations (*note Changeword::).
588 File: m4.info, Node: Preprocessor features, Next: Limits control, Prev: Operation modes, Up: Invoking m4
590 2.2 Command line options for preprocessor features
591 ==================================================
593 Several options allow 'm4' to behave more like a preprocessor. Macro
594 definitions and deletions can be made on the command line, the search
595 path can be altered, and the output file can track where the input came
596 from. These features occur with the following options:
599 '--define=NAME[=VALUE]'
600 This enters NAME into the symbol table. If '=VALUE' is missing,
601 the value is taken to be the empty string. The VALUE can be any
602 string, and the macro can be defined to take arguments, just as if
603 it was defined from within the input. This option may be given
604 more than once; order with respect to file names is significant,
605 and redefining the same NAME loses the previous value.
608 '--include=DIRECTORY'
609 Make 'm4' search DIRECTORY for included files that are not found in
610 the current working directory. *Note Search Path::, for more
611 details. This option may be given more than once.
615 Generate synchronization lines, for use by the C preprocessor or
616 other similar tools. Order is significant with respect to file
617 names. This option is useful, for example, when 'm4' is used as a
618 front end to a compiler. Source file name and line number
619 information is conveyed by directives of the form '#line LINENUM
620 "FILE"', which are inserted as needed into the middle of the
621 output. Such directives mean that the following line originated or
622 was expanded from the contents of input file FILE at line LINENUM.
623 The '"FILE"' part is often omitted when the file name did not
624 change from the previous directive.
626 Synchronization directives are always given on complete lines by
627 themselves. When a synchronization discrepancy occurs in the
628 middle of an output line, the associated synchronization directive
629 is delayed until the next newline that does not occur in the middle
630 of a quoted string or comment.
636 changecom(`/*', `*/')
638 define(`comment', `/*1
665 This deletes any predefined meaning NAME might have. Obviously,
666 only predefined macros can be deleted in this way. This option may
667 be given more than once; undefining a NAME that does not have a
668 definition is silently ignored. Order is significant with respect
672 File: m4.info, Node: Limits control, Next: Frozen state, Prev: Preprocessor features, Up: Invoking m4
674 2.3 Command line options for limits control
675 ===========================================
677 There are some limits within 'm4' that can be tuned. For compatibility,
678 'm4' also accepts some options that control limits in other
679 implementations, but which are automatically unbounded (limited only by
680 your hardware and operating system constraints) in GNU 'm4'.
684 Enable all the extensions in this implementation. In this release
685 of M4, this option is always on by default; it is currently only
686 useful when overriding a prior use of '--traditional'. However,
687 having GNU behavior as default makes it impossible to write a
688 strictly POSIX-compliant client that avoids all incompatible GNU M4
689 extensions, since such a client would have to use the non-POSIX
690 command-line option to force full POSIX behavior. Thus, a future
691 version of M4 will be changed to implicitly use the option
692 '--traditional' if the environment variable 'POSIXLY_CORRECT' is
693 set. Projects that intentionally use GNU extensions should
694 consider using '--gnu' to state their intentions, so that the
695 project will not mysteriously break if the user upgrades to a newer
696 M4 and has 'POSIXLY_CORRECT' set in their environment.
700 Suppress all the extensions made in this implementation, compared
701 to the System V version. *Note Compatibility::, for a list of
706 Make the internal hash table for symbol lookup be NUM entries big.
707 For better performance, the number should be prime, but this is not
708 checked. The default is 509 entries. It should not be necessary
709 to increase this value, unless you define an excessive number of
713 '--nesting-limit=NUM'
714 Artificially limit the nesting of macro calls to NUM levels,
715 stopping program execution if this limit is ever exceeded. When
716 not specified, nesting defaults to unlimited on platforms that can
717 detect stack overflow, and to 1024 levels otherwise. A value of
718 zero means unlimited; but then heavily nested code could
719 potentially cause a stack overflow.
721 The precise effect of this option is more correctly associated with
722 textual nesting than dynamic recursion. It has been useful when
723 some complex 'm4' input was generated by mechanical means, and also
724 in diagnosing recursive algorithms that do not scale well. Most
725 users never need to change this option from its default.
727 This option does _not_ have the ability to break endless rescanning
728 loops, since these do not necessarily consume much memory or stack
729 space. Through clever usage of rescanning loops, one can request
730 complex, time-consuming computations from 'm4' with useful results.
731 Putting limitations in this area would break 'm4' power. There are
732 many pathological cases: 'define(`a', `a')a' is only the simplest
733 example (but *note Compatibility::). Expecting GNU 'm4' to detect
734 these would be a little like expecting a compiler system to detect
735 and diagnose endless loops: it is a quite _hard_ problem in
736 general, if not undecidable!
741 These options are present for compatibility with System V 'm4', but
742 do nothing in this implementation. They may disappear in future
743 releases, and issue a warning to that effect.
747 These options are present only for compatibility with previous
748 versions of GNU 'm4', and were controlling the number of possible
749 diversions which could be used at the same time. They do nothing,
750 because there is no fixed limit anymore. They may disappear in
751 future releases, and issue a warning to that effect.
754 File: m4.info, Node: Frozen state, Next: Debugging options, Prev: Limits control, Up: Invoking m4
756 2.4 Command line options for frozen state
757 =========================================
759 GNU 'm4' comes with a feature of freezing internal state (*note Frozen
760 files::). This can be used to speed up 'm4' execution when reusing a
761 common initialization script.
764 '--freeze-state=FILE'
765 Once execution is finished, write out the frozen state on the
766 specified FILE. It is conventional, but not required, for FILE to
770 '--reload-state=FILE'
771 Before execution starts, recover the internal state from the
772 specified frozen FILE. The options '-D', '-U', and '-t' take
773 effect after state is reloaded, but before the input files are
777 File: m4.info, Node: Debugging options, Next: Command line files, Prev: Frozen state, Up: Invoking m4
779 2.5 Command line options for debugging
780 ======================================
782 Finally, there are several options for aiding in debugging 'm4' scripts.
786 Set the debug-level according to the flags FLAGS. The debug-level
787 controls the format and amount of information presented by the
788 debugging functions. *Note Debug Levels::, for more details on the
789 format and meaning of FLAGS. If omitted, FLAGS defaults to 'aeq'.
793 '--error-output=FILE'
794 Redirect 'dumpdef' output, debug messages, and trace output to the
795 named FILE. Warnings, error messages, and 'errprint' output are
796 still printed to standard error. If these options are not used, or
797 if FILE is unspecified (only possible for '--debugfile'), debug
798 output goes to standard error; if FILE is the empty string, debug
799 output is discarded. *Note Debug Output::, for more details. The
800 option '--debugfile' may be given more than once, and order is
801 significant with respect to file names. The spellings '-o' and
802 '--error-output' are misleading and inconsistent with other GNU
803 tools; for now they are silently accepted as synonyms of
804 '--debugfile' and only recognized once, but in a future version of
805 M4, using them will cause a warning to be issued.
809 Restrict the size of the output generated by macro tracing to NUM
810 characters per trace line. If unspecified or zero, output is
811 unlimited. *Note Debug Levels::, for more details.
815 This enables tracing for the macro NAME, at any point where it is
816 defined. NAME need not be defined when this option is given. This
817 option may be given more than once, and order is significant with
818 respect to file names. *Note Trace::, for more details.
821 File: m4.info, Node: Command line files, Prev: Debugging options, Up: Invoking m4
823 2.6 Specifying input files on the command line
824 ==============================================
826 The remaining arguments on the command line are taken to be input file
827 names. If no names are present, standard input is read. A file name of
828 '-' is taken to mean standard input. It is conventional, but not
829 required, for input files to end in '.m4'.
831 The input files are read in the sequence given. Standard input can
832 be read more than once, so the file name '-' may appear multiple times
833 on the command line; this makes a difference when input is from a
834 terminal or other special file type. It is an error if an input file
835 ends in the middle of argument collection, a comment, or a quoted
838 The options '--define' ('-D'), '--undefine' ('-U'), '--synclines'
839 ('-s'), and '--trace' ('-t') only take effect after processing input
840 from any file names that occur earlier on the command line. For
841 example, assume the file 'foo' contains:
846 The text 'bar' can then be redefined over multiple uses of 'foo':
848 $ m4 -Dbar=hello foo -Dbar=world foo
852 If none of the input files invoked 'm4exit' (*note M4exit::), the
853 exit status of 'm4' will be 0 for success, 1 for general failure (such
854 as problems with reading an input file), and 63 for version mismatch
855 (*note Using frozen files::).
857 If you need to read a file whose name starts with a '-', you can
858 specify it as './-file', or use '--' to mark the end of options.
861 File: m4.info, Node: Syntax, Next: Macros, Prev: Invoking m4, Up: Top
863 3 Lexical and syntactic conventions
864 ***********************************
866 As 'm4' reads its input, it separates it into "tokens". A token is
867 either a name, a quoted string, or any single character, that is not a
868 part of either a name or a string. Input to 'm4' can also contain
869 comments. GNU 'm4' does not yet understand multibyte locales; all
870 operations are byte-oriented rather than character-oriented (although if
871 your locale uses a single byte encoding, such as ISO-8859-1, you will
872 not notice a difference). However, 'm4' is eight-bit clean, so you can
873 use non-ASCII characters in quoted strings (*note Changequote::),
874 comments (*note Changecom::), and macro names (*note Indir::), with the
875 exception of the NUL character (the zero byte ''\0'').
879 * Names:: Macro names
880 * Quoted strings:: Quoting input to 'm4'
881 * Comments:: Comments in 'm4' input
882 * Other tokens:: Other kinds of input tokens
883 * Input processing:: How 'm4' copies input to output
886 File: m4.info, Node: Names, Next: Quoted strings, Up: Syntax
891 A name is any sequence of letters, digits, and the character '_'
892 (underscore), where the first character is not a digit. 'm4' will use
893 the longest such sequence found in the input. If a name has a macro
894 definition, it will be subject to macro expansion (*note Macros::).
895 Names are case-sensitive.
897 Examples of legal names are: 'foo', '_tmp', and 'name01'.
900 File: m4.info, Node: Quoted strings, Next: Comments, Prev: Names, Up: Syntax
902 3.2 Quoting input to 'm4'
903 =========================
905 A quoted string is a sequence of characters surrounded by quote strings,
906 defaulting to '`' and ''', where the nested begin and end quotes within
907 the string are balanced. The value of a string token is the text, with
908 one level of quotes stripped off. Thus
913 is the empty string, and double-quoting turns into single-quoting.
918 The quote characters can be changed at any time, using the builtin
919 macro 'changequote'. *Note Changequote::, for more information.
922 File: m4.info, Node: Comments, Next: Other tokens, Prev: Quoted strings, Up: Syntax
924 3.3 Comments in 'm4' input
925 ==========================
927 Comments in 'm4' are normally delimited by the characters '#' and
928 newline. All characters between the comment delimiters are ignored, but
929 the entire comment (including the delimiters) is passed through to the
930 output--comments are _not_ discarded by 'm4'.
932 Comments cannot be nested, so the first newline after a '#' ends the
933 comment. The commenting effect of the begin-comment string can be
934 inhibited by quoting it.
937 `quoted text' # `commented text'
938 =>quoted text # `commented text'
939 `quoting inhibits' `#' `comments'
940 =>quoting inhibits # comments
942 The comment delimiters can be changed to any string at any time,
943 using the builtin macro 'changecom'. *Note Changecom::, for more
947 File: m4.info, Node: Other tokens, Next: Input processing, Prev: Comments, Up: Syntax
949 3.4 Other kinds of input tokens
950 ===============================
952 Any character, that is neither a part of a name, nor of a quoted string,
953 nor a comment, is a token by itself. When not in the context of macro
954 expansion, all of these tokens are just copied to output. However,
955 during macro expansion, whitespace characters (space, tab, newline,
956 formfeed, carriage return, vertical tab), parentheses ('(' and ')'),
957 comma (','), and dollar ('$') have additional roles, explained later.
960 File: m4.info, Node: Input processing, Prev: Other tokens, Up: Syntax
962 3.5 How 'm4' copies input to output
963 ===================================
965 As 'm4' reads the input token by token, it will copy each token directly
966 to the output immediately.
968 The exception is when it finds a word with a macro definition. In
969 that case 'm4' will calculate the macro's expansion, possibly reading
970 more input to get the arguments. It then inserts the expansion in front
971 of the remaining input. In other words, the resulting text from a macro
972 call will be read and parsed into tokens again.
974 'm4' expands a macro as soon as possible. If it finds a macro call
975 when collecting the arguments to another, it will expand the second call
976 first. This process continues until there are no more macro calls to
977 expand and all the input has been consumed.
979 For a running example, examine how 'm4' handles this input:
981 format(`Result is %d', eval(`2**15'))
983 First, 'm4' sees that the token 'format' is a macro name, so it collects
984 the tokens '(', '`Result is %d'', ',', and ' ', before encountering
985 another potential macro. Sure enough, 'eval' is a macro name, so the
986 nested argument collection picks up '(', '`2**15'', and ')', invoking
987 the eval macro with the lone argument of '2**15'. The expansion of
988 'eval(2**15)' is '32768', which is then rescanned as the five tokens
989 '3', '2', '7', '6', and '8'; and combined with the next ')', the format
990 macro now has all its arguments, as if the user had typed:
992 format(`Result is %d', 32768)
994 The format macro expands to 'Result is 32768', and we have another round
995 of scanning for the tokens 'Result', ' ', 'is', ' ', '3', '2', '7', '6',
996 and '8'. None of these are macros, so the final output is
1000 As a more complicated example, we will contrast an actual code
1001 example from the Gnulib project(1), showing both a buggy approach and
1002 the desired results. The user desires to output a shell assignment
1003 statement that takes its argument and turns it into a shell variable by
1004 converting it to uppercase and prepending a prefix. The original
1005 attempt looks like this:
1008 define([gl_STRING_MODULE_INDICATOR],
1011 GNULIB_]translit([$1],[a-z],[A-Z])[=1
1013 gl_STRING_MODULE_INDICATOR([strcase])
1018 Oops - the argument did not get capitalized. And although the manual
1019 is not able to easily show it, both lines that appear empty actually
1020 contain two trailing spaces. By stepping through the parse, it is easy
1021 to see what happened. First, 'm4' sees the token 'changequote', which
1022 it recognizes as a macro, followed by '(', '[', ',', ']', and ')' to
1023 form the argument list. The macro expands to the empty string, but
1024 changes the quoting characters to something more useful for generating
1025 shell code (unbalanced '`' and ''' appear all the time in shell scripts,
1026 but unbalanced '[]' tend to be rare). Also in the first line, 'm4' sees
1027 the token 'dnl', which it recognizes as a builtin macro that consumes
1028 the rest of the line, resulting in no output for that line.
1030 The second line starts a macro definition. 'm4' sees the token
1031 'define', which it recognizes as a macro, followed by a '(',
1032 '[gl_STRING_MODULE_INDICATOR]', and ','. Because an unquoted comma was
1033 encountered, the first argument is known to be the expansion of the
1034 single-quoted string token, or 'gl_STRING_MODULE_INDICATOR'. Next, 'm4'
1035 sees '<NL>', ' ', and ' ', but this whitespace is discarded as part of
1036 argument collection. Then comes a rather lengthy single-quoted string
1037 token, '[<NL> dnl comment<NL> GNULIB_]'. This is followed by the
1038 token 'translit', which 'm4' recognizes as a macro name, so a nested
1039 macro expansion has started.
1041 The arguments to the 'translit' are found by the tokens '(', '[$1]',
1042 ',', '[a-z]', ',', '[A-Z]', and finally ')'. All three string arguments
1043 are expanded (or in other words, the quotes are stripped), and since
1044 neither '$' nor '1' need capitalization, the result of the macro is
1045 '$1'. This expansion is rescanned, resulting in the two literal
1046 characters '$' and '1'.
1048 Scanning of the outer macro resumes, and picks up with '[=1<NL> ]',
1049 and finally ')'. The collected pieces of expanded text are
1050 concatenated, with the end result that the macro
1051 'gl_STRING_MODULE_INDICATOR' is now defined to be the sequence
1052 '<NL> dnl comment<NL> GNULIB_$1=1<NL> '. Once again, 'dnl' is
1053 recognized and avoids a newline in the output.
1055 The final line is then parsed, beginning with ' ' and ' ' that are
1056 output literally. Then 'gl_STRING_MODULE_INDICATOR' is recognized as a
1057 macro name, with an argument list of '(', '[strcase]', and ')'. Since
1058 the definition of the macro contains the sequence '$1', that sequence is
1059 replaced with the argument 'strcase' prior to starting the rescan. The
1060 rescan sees '<NL>' and four spaces, which are output literally, then
1061 'dnl', which discards the text ' comment<NL>'. Next comes four more
1062 spaces, also output literally, and the token 'GNULIB_strcase', which
1063 resulted from the earlier parameter substitution. Since that is not a
1064 macro name, it is output literally, followed by the literal tokens '=',
1065 '1', '<NL>', and two more spaces. Finally, the original '<NL>' seen
1066 after the macro invocation is scanned and output literally.
1068 Now for a corrected approach. This rearranges the use of newlines
1069 and whitespace so that less whitespace is output (which, although
1070 harmless to shell scripts, can be visually unappealing), and fixes the
1071 quoting issues so that the capitalization occurs when the macro
1072 'gl_STRING_MODULE_INDICATOR' is invoked, rather then when it is defined.
1073 It also adds another layer of quoting to the first argument of
1074 'translit', to ensure that the output will be rescanned as a string
1075 rather than a potential uppercase macro name needing further expansion.
1078 define([gl_STRING_MODULE_INDICATOR],
1080 GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl
1082 gl_STRING_MODULE_INDICATOR([strcase])
1085 The parsing of the first line is unchanged. The second line sees the
1086 name of the macro to define, then sees the discarded '<NL>' and two
1087 spaces, as before. But this time, the next token is '[dnl
1088 comment<NL> GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl<NL>]', which
1089 includes nested quotes, followed by ')' to end the macro definition and
1090 'dnl' to skip the newline. No early expansion of 'translit' occurs, so
1091 the entire string becomes the definition of the macro.
1093 The final line is then parsed, beginning with two spaces that are
1094 output literally, and an invocation of 'gl_STRING_MODULE_INDICATOR' with
1095 the argument 'strcase'. Again, the '$1' in the macro definition is
1096 substituted prior to rescanning. Rescanning first encounters 'dnl', and
1097 discards ' comment<NL>'. Then two spaces are output literally. Next
1098 comes the token 'GNULIB_', but that is not a macro, so it is output
1099 literally. The token '[]' is an empty string, so it does not affect
1100 output. Then the token 'translit' is encountered.
1102 This time, the arguments to 'translit' are parsed as '(',
1103 '[[strcase]]', ',', ' ', '[a-z]', ',', ' ', '[A-Z]', and ')'. The two
1104 spaces are discarded, and the translit results in the desired result
1105 '[STRCASE]'. This is rescanned, but since it is a string, the quotes
1106 are stripped and the only output is a literal 'STRCASE'. Then the
1107 scanner sees '=' and '1', which are output literally, followed by 'dnl'
1108 which discards the rest of the definition of
1109 'gl_STRING_MODULE_INDICATOR'. The newline at the end of output is the
1110 literal '<NL>' that appeared after the invocation of the macro.
1112 The order in which 'm4' expands the macros can be further explored
1113 using the trace facilities of GNU 'm4' (*note Trace::).
1115 ---------- Footnotes ----------
1117 (1) Derived from a patch in
1118 <http://lists.gnu.org/archive/html/bug-gnulib/2007-01/msg00389.html>,
1119 and a followup patch in
1120 <http://lists.gnu.org/archive/html/bug-gnulib/2007-02/msg00000.html>
1123 File: m4.info, Node: Macros, Next: Definitions, Prev: Syntax, Up: Top
1125 4 How to invoke macros
1126 **********************
1128 This chapter covers macro invocation, macro arguments and how macro
1129 expansion is treated.
1133 * Invocation:: Macro invocation
1134 * Inhibiting Invocation:: Preventing macro invocation
1135 * Macro Arguments:: Macro arguments
1136 * Quoting Arguments:: On Quoting Arguments to macros
1137 * Macro expansion:: Expanding macros
1140 File: m4.info, Node: Invocation, Next: Inhibiting Invocation, Up: Macros
1142 4.1 Macro invocation
1143 ====================
1145 Macro invocations has one of the forms
1149 which is a macro invocation without any arguments, or
1151 name(arg1, arg2, ..., argN)
1153 which is a macro invocation with N arguments. Macros can have any
1154 number of arguments. All arguments are strings, but different macros
1155 might interpret the arguments in different ways.
1157 The opening parenthesis _must_ follow the NAME directly, with no
1158 spaces in between. If it does not, the macro is called with no
1161 For a macro call to have no arguments, the parentheses _must_ be left
1166 is a macro call with one argument, which is the empty string, not a call
1170 File: m4.info, Node: Inhibiting Invocation, Next: Macro Arguments, Prev: Invocation, Up: Macros
1172 4.2 Preventing macro invocation
1173 ===============================
1175 An innovation of the 'm4' language, compared to some of its predecessors
1176 (like Strachey's 'GPM', for example), is the ability to recognize macro
1177 calls without resorting to any special, prefixed invocation character.
1178 While generally useful, this feature might sometimes be the source of
1179 spurious, unwanted macro calls. So, GNU 'm4' offers several mechanisms
1180 or techniques for inhibiting the recognition of names as macro calls.
1182 First of all, many builtin macros cannot meaningfully be called
1183 without arguments. As a GNU extension, for any of these macros,
1184 whenever an opening parenthesis does not immediately follow their name,
1185 the builtin macro call is not triggered. This solves the most usual
1186 cases, like for 'include' or 'eval'. Later in this document, the
1187 sentence "This macro is recognized only with parameters" refers to this
1188 specific provision of GNU M4, also known as a blind builtin macro. For
1189 the builtins defined by POSIX that bear this disclaimer, POSIX
1190 specifically states that invoking those builtins without arguments is
1191 unspecified, because many other implementations simply invoke the
1192 builtin as though it were given one empty argument instead.
1200 There is also a command line option ('--prefix-builtins', or '-P',
1201 *note Invoking m4: Operation modes.) that renames all builtin macros
1202 with a prefix of 'm4_' at startup. The option has no effect whatsoever
1203 on user defined macros. For example, with this option, one has to write
1204 'm4_dnl' and even 'm4_m4exit'. It also has no effect on whether a macro
1205 requires parameters.
1217 Another alternative is to redefine problematic macros to a name less
1218 likely to cause conflicts, using *note Definitions::.
1220 If your version of GNU 'm4' has the 'changeword' feature compiled in,
1221 it offers far more flexibility in specifying the syntax of macro names,
1222 both builtin or user-defined. *Note Changeword::, for more information
1223 on this experimental feature.
1225 Of course, the simplest way to prevent a name from being interpreted
1226 as a call to an existing macro is to quote it. The remainder of this
1227 section studies a little more deeply how quoting affects macro
1228 invocation, and how quoting can be used to inhibit macro invocation.
1230 Even if quoting is usually done over the whole macro name, it can
1231 also be done over only a few characters of this name (provided, of
1232 course, that the unquoted portions are not also a macro). It is also
1233 possible to quote the empty string, but this works only _inside_ the
1245 all yield the string 'divert'. While in both:
1252 the 'divert' builtin macro will be called, which expands to the empty
1255 The output of macro evaluations is always rescanned. In the
1256 following example, the input 'x`'y' yields the string 'bCD', exactly as
1257 if 'm4' has been given 'substr(ab`'cde, `1', `3')' as input:
1259 define(`cde', `CDE')
1261 define(`x', `substr(ab')
1263 define(`y', `cde, `1', `3')')
1268 Unquoted strings on either side of a quoted string are subject to
1269 being recognized as macro names. In the following example, quoting the
1270 empty string allows for the second 'macro' to be recognized as such:
1272 define(`macro', `m')
1279 Quoting may prevent recognizing as a macro name the concatenation of
1280 a macro expansion with the surrounding characters. In this example:
1282 define(`macro', `di$1')
1289 the input will produce the string 'divert'. When the quotes were
1290 removed, the 'divert' builtin was called instead.
1293 File: m4.info, Node: Macro Arguments, Next: Quoting Arguments, Prev: Inhibiting Invocation, Up: Macros
1298 When a name is seen, and it has a macro definition, it will be expanded
1301 If the name is followed by an opening parenthesis, the arguments will
1302 be collected before the macro is called. If too few arguments are
1303 supplied, the missing arguments are taken to be the empty string.
1304 However, some builtins are documented to behave differently for a
1305 missing optional argument than for an explicit empty string. If there
1306 are too many arguments, the excess arguments are ignored. Unquoted
1307 leading whitespace is stripped off all arguments, but whitespace
1308 generated by a macro expansion or occurring after a macro that expanded
1309 to an empty string remains intact. Whitespace includes space, tab,
1310 newline, carriage return, vertical tab, and formfeed.
1312 define(`macro', `$1')
1314 macro( unquoted leading space lost)
1315 =>unquoted leading space lost
1316 macro(` quoted leading space kept')
1317 => quoted leading space kept
1319 divert `unquoted space kept after expansion')
1320 => unquoted space kept after expansion
1322 ')`whitespace from expansion kept')
1324 =>whitespace from expansion kept
1325 macro(`unquoted trailing whitespace kept'
1327 =>unquoted trailing whitespace kept
1330 Normally 'm4' will issue warnings if a builtin macro is called with
1331 an inappropriate number of arguments, but it can be suppressed with the
1332 '--quiet' command line option (or '--silent', or '-Q', *note Invoking
1333 m4: Operation modes.). For user defined macros, there is no check of
1334 the number of arguments given.
1338 error->m4:stdin:1: Warning: too few arguments to builtin `index'
1342 index(`abc', `b', `ignored')
1343 error->m4:stdin:3: Warning: excess arguments to builtin `index' ignored
1351 index(`abc', `b', `ignored')
1354 Macros are expanded normally during argument collection, and whatever
1355 commas, quotes and parentheses that might show up in the resulting
1356 expanded text will serve to define the arguments as well. Thus, if FOO
1357 expands to ', b, c', the macro call
1361 is a macro call with four arguments, which are 'a ', 'b', 'c' and 'd'.
1362 To understand why the first argument contains whitespace, remember that
1363 unquoted leading whitespace is never part of an argument, but trailing
1364 whitespace always is.
1366 It is possible for a macro's definition to change during argument
1367 collection, in which case the expansion uses the definition that was in
1368 effect at the time the opening '(' was seen.
1377 It is an error if the end of file occurs while collecting arguments.
1383 error->m4:stdin:2: ERROR: end of file in argument list
1386 File: m4.info, Node: Quoting Arguments, Next: Macro expansion, Prev: Macro Arguments, Up: Macros
1388 4.4 On Quoting Arguments to macros
1389 ==================================
1391 Each argument has unquoted leading whitespace removed. Within each
1392 argument, all unquoted parentheses must match. For example, if FOO is a
1397 is a macro call, with one argument, whose value is '() (() ('. Commas
1398 separate arguments, except when they occur inside quotes, comments, or
1399 unquoted parentheses. *Note Pseudo Arguments::, for examples.
1401 It is common practice to quote all arguments to macros, unless you
1402 are sure you want the arguments expanded. Thus, in the above example
1403 with the parentheses, the 'right' way to do it is like this:
1407 It is, however, in certain cases necessary (because nested expansion
1408 must occur to create the arguments for the outer macro) or convenient
1409 (because it uses fewer characters) to leave out quotes for some
1410 arguments, and there is nothing wrong in doing it. It just makes life a
1411 bit harder, if you are not careful to follow a consistent quoting style.
1412 For consistency, this manual follows the rule of thumb that each layer
1413 of parentheses introduces another layer of single quoting, except when
1414 showing the consequences of quoting rules. This is done even when the
1415 quoted string cannot be a macro, such as with integers when you have not
1416 changed the syntax via 'changeword' (*note Changeword::).
1418 The quoting rule of thumb of one level of quoting per parentheses has
1419 a nice property: when a macro name appears inside parentheses, you can
1420 determine when it will be expanded. If it is not quoted, it will be
1421 expanded prior to the outer macro, so that its expansion becomes the
1422 argument. If it is single-quoted, it will be expanded after the outer
1423 macro. And if it is double-quoted, it will be used as literal text
1424 instead of a macro name.
1426 define(`active', `ACT, IVE')
1428 define(`show', `$1 $1')
1438 File: m4.info, Node: Macro expansion, Prev: Quoting Arguments, Up: Macros
1443 When the arguments, if any, to a macro call have been collected, the
1444 macro is expanded, and the expansion text is pushed back onto the input
1445 (unquoted), and reread. The expansion text from one macro call might
1446 therefore result in more macros being called, if the calls are included,
1447 completely or partially, in the first macro calls' expansion.
1449 Taking a very simple example, if FOO expands to 'bar', and BAR
1450 expands to 'Hello', the input
1452 $ m4 -Dbar=Hello -Dfoo=bar
1456 will expand first to 'bar', and when this is reread and expanded, into
1460 File: m4.info, Node: Definitions, Next: Conditionals, Prev: Macros, Up: Top
1462 5 How to define new macros
1463 **************************
1465 Macros can be defined, redefined and deleted in several different ways.
1466 Also, it is possible to redefine a macro without losing a previous
1467 value, and bring back the original value at a later time.
1471 * Define:: Defining a new macro
1472 * Arguments:: Arguments to macros
1473 * Pseudo Arguments:: Special arguments to macros
1474 * Undefine:: Deleting a macro
1475 * Defn:: Renaming macros
1476 * Pushdef:: Temporarily redefining macros
1478 * Indir:: Indirect call of macros
1479 * Builtin:: Indirect call of builtins
1482 File: m4.info, Node: Define, Next: Arguments, Up: Definitions
1484 5.1 Defining a macro
1485 ====================
1487 The normal way to define or redefine macros is to use the builtin
1490 -- Builtin: define (NAME, [EXPANSION]
1491 Defines NAME to expand to EXPANSION. If EXPANSION is not given, it
1492 is taken to be empty.
1494 The expansion of 'define' is void. The macro 'define' is
1495 recognized only with parameters.
1497 The following example defines the macro FOO to expand to the text
1500 define(`foo', `Hello world.')
1505 The empty line in the output is there because the newline is not a
1506 part of the macro definition, and it is consequently copied to the
1507 output. This can be avoided by use of the macro 'dnl'. *Note Dnl::,
1510 The first argument to 'define' should be quoted; otherwise, if the
1511 macro is already defined, you will be defining a different macro. This
1512 example shows the problems with underquoting, since we did not want to
1522 GNU 'm4' normally replaces only the _topmost_ definition of a macro
1523 if it has several definitions from 'pushdef' (*note Pushdef::). Some
1524 other implementations of 'm4' replace all definitions of a macro with
1525 'define'. *Note Incompatibilities::, for more details.
1527 As a GNU extension, the first argument to 'define' does not have to
1528 be a simple word. It can be any text string, even the empty string. A
1529 macro with a non-standard name cannot be invoked in the normal way, as
1530 the name is not recognized. It can only be referenced by the builtins
1531 'indir' (*note Indir::) and 'defn' (*note Defn::).
1533 Arrays and associative arrays can be simulated by using non-standard
1536 -- Composite: array (INDEX)
1537 -- Composite: array_set (INDEX, [VALUE]
1538 Provide access to entries within an array. 'array' reads the entry
1539 at location INDEX, and 'array_set' assigns VALUE to location INDEX.
1541 define(`array', `defn(format(``array[%d]'', `$1'))')
1543 define(`array_set', `define(format(``array[%d]'', `$1'), `$2')')
1545 array_set(`4', `array element no. 4')
1547 array_set(`17', `array element no. 17')
1550 =>array element no. 4
1551 array(eval(`10 + 7'))
1552 =>array element no. 17
1554 Change the '%d' to '%s' and it is an associative array.
1557 File: m4.info, Node: Arguments, Next: Pseudo Arguments, Prev: Define, Up: Definitions
1559 5.2 Arguments to macros
1560 =======================
1562 Macros can have arguments. The Nth argument is denoted by '$n' in the
1563 expansion text, and is replaced by the Nth actual argument, when the
1564 macro is expanded. Replacement of arguments happens before rescanning,
1565 regardless of how many nesting levels of quoting appear in the
1566 expansion. Here is an example of a macro with two arguments.
1568 -- Composite: exch (ARG1, ARG2)
1569 Expands to ARG2 followed by ARG1, effectively exchanging their
1572 define(`exch', `$2, $1')
1574 exch(`arg1', `arg2')
1577 This can be used, for example, if you like the arguments to 'define'
1580 define(`exch', `$2, $1')
1582 define(exch(``expansion text'', ``macro''))
1587 *Note Quoting Arguments::, for an explanation of the double quotes.
1588 (You should try and improve this example so that clients of 'exch' do
1589 not have to double quote; or *note Answers: Improved exch.).
1591 As a special case, the zeroth argument, '$0', is always the name of
1592 the macro being expanded.
1594 define(`test', ``Macro name: $0'')
1599 If you want quoted text to appear as part of the expansion text,
1600 remember that quotes can be nested in quoted strings. Thus, in
1602 define(`foo', `This is macro `foo'.')
1605 =>This is macro foo.
1607 The 'foo' in the expansion text is _not_ expanded, since it is a quoted
1608 string, and not a name.
1610 GNU 'm4' allows the number following the '$' to consist of one or
1611 more digits, allowing macros to have any number of arguments. The
1612 extension of accepting multiple digits is incompatible with POSIX, and
1613 is different than traditional implementations of 'm4', which only
1614 recognize one digit. Therefore, future versions of GNU M4 will phase
1615 out this feature. To portably access beyond the ninth argument, you can
1616 use the 'argn' macro documented later (*note Shift::).
1618 POSIX also states that '$' followed immediately by '{' in a macro
1619 definition is implementation-defined. This version of M4 passes the
1620 literal characters '${' through unchanged, but M4 2.0 will implement an
1621 optional feature similar to 'sh', where '${11}' expands to the eleventh
1622 argument, to replace the current recognition of '$11'. Meanwhile, if
1623 you want to guarantee that you will get a literal '${' in output when
1624 expanding a macro, even when you upgrade to M4 2.0, you can use nested
1625 quoting to your advantage:
1627 define(`foo', `single quoted $`'{1} output')
1629 define(`bar', ``double quoted $'`{2} output'')
1632 =>single quoted ${1} output
1634 =>double quoted ${2} output
1636 To help you detect places in your M4 input files that might change in
1637 behavior due to the changed behavior of M4 2.0, you can use the
1638 '--warn-macro-sequence' command-line option (*note Invoking m4:
1639 Operation modes.) with the default regular expression. This will add a
1640 warning any time a macro definition includes '$' followed by multiple
1641 digits, or by '{'. The warning is not enabled by default, because it
1642 triggers a number of warnings in Autoconf 2.61 (and Autoconf uses '-E'
1643 to treat warnings as errors), and because it will still be possible to
1644 restore older behavior in M4 2.0.
1646 $ m4 --warn-macro-sequence
1647 define(`foo', `$001 ${1} $1')
1648 error->m4:stdin:1: Warning: definition of `foo' contains sequence `$001'
1649 error->m4:stdin:1: Warning: definition of `foo' contains sequence `${1}'
1655 File: m4.info, Node: Pseudo Arguments, Next: Undefine, Prev: Arguments, Up: Definitions
1657 5.3 Special arguments to macros
1658 ===============================
1660 There is a special notation for the number of actual arguments supplied,
1661 and for all the actual arguments.
1663 The number of actual arguments in a macro call is denoted by '$#' in
1666 -- Composite: nargs (...)
1667 Expands to a count of the number of arguments supplied.
1669 define(`nargs', `$#')
1675 nargs(`arg1', `arg2', `arg3')
1677 nargs(`commas can be quoted, like this')
1679 nargs(arg1#inside comments, commas do not separate arguments
1682 nargs((unquoted parentheses, like this, group arguments))
1685 Remember that '#' defaults to the comment character; if you forget
1686 quotes to inhibit the comment behavior, your macro definition may not
1687 end where you expected.
1689 dnl Attempt to define a macro to just `$#'
1690 define(underquoted, $#)
1697 The notation '$*' can be used in the expansion text to denote all the
1698 actual arguments, unquoted, with commas in between. For example
1700 define(`echo', `$*')
1702 echo(arg1, arg2, arg3 , arg4)
1703 =>arg1,arg2,arg3 ,arg4
1705 Often each argument should be quoted, and the notation '$@' handles
1706 that. It is just like '$*', except that it quotes each argument. A
1707 simple example of that is:
1709 define(`echo', `$@')
1711 echo(arg1, arg2, arg3 , arg4)
1712 =>arg1,arg2,arg3 ,arg4
1714 Where did the quotes go? Of course, they were eaten, when the
1715 expanded text were reread by 'm4'. To show the difference, try
1717 define(`echo1', `$*')
1719 define(`echo2', `$@')
1721 define(`foo', `This is macro `foo'.')
1724 =>This is macro This is macro foo..
1726 =>This is macro foo.
1728 =>This is macro foo.
1732 *Note Trace::, if you do not understand this. As another example of the
1733 difference, remember that comments encountered in arguments are passed
1734 untouched to the macro, and that quoting disables comments.
1736 define(`echo1', `$*')
1738 define(`echo2', `$@')
1740 define(`foo', `bar')
1751 A '$' sign in the expansion text, that is not followed by anything
1752 'm4' understands, is simply copied to the macro expansion, as any other
1755 define(`foo', `$$$ hello $$$')
1760 If you want a macro to expand to something like '$12', the judicious
1761 use of nested quoting can put a safe character between the '$' and the
1762 next character, relying on the rescanning to remove the nested quote.
1763 This will prevent 'm4' from interpreting the '$' sign as a reference to
1766 define(`foo', `no nested quote: $1')
1769 =>no nested quote: arg
1770 define(`foo', `nested quote around $: `$'1')
1773 =>nested quote around $: $1
1774 define(`foo', `nested empty quote after $: $`'1')
1777 =>nested empty quote after $: $1
1778 define(`foo', `nested quote around next character: $`1'')
1781 =>nested quote around next character: $1
1782 define(`foo', `nested quote around both: `$1'')
1785 =>nested quote around both: arg
1788 File: m4.info, Node: Undefine, Next: Defn, Prev: Pseudo Arguments, Up: Definitions
1790 5.4 Deleting a macro
1791 ====================
1793 A macro definition can be removed with 'undefine':
1795 -- Builtin: undefine (NAME...)
1796 For each argument, remove the macro NAME. The macro names must
1797 necessarily be quoted, since they will be expanded otherwise.
1799 The expansion of 'undefine' is void. The macro 'undefine' is
1800 recognized only with parameters.
1804 define(`foo', `some')define(`bar', `other')define(`blah', `text')
1812 undefine(`bar', `blah')
1817 Undefining a macro inside that macro's expansion is safe; the macro
1818 still expands to the definition that was in effect at the '('.
1820 define(`f', ``$0':$1')
1822 f(f(f(undefine(`f')`hello world')))
1827 It is not an error for NAME to have no macro definition. In that
1828 case, 'undefine' does nothing.
1831 File: m4.info, Node: Defn, Next: Pushdef, Prev: Undefine, Up: Definitions
1836 It is possible to rename an already defined macro. To do this, you need
1839 -- Builtin: defn (NAME...)
1840 Expands to the _quoted definition_ of each NAME. If an argument is
1841 not a defined macro, the expansion for that argument is empty.
1843 If NAME is a user-defined macro, the quoted definition is simply
1844 the quoted expansion text. If, instead, there is only one NAME and
1845 it is a builtin, the expansion is a special token, which points to
1846 the builtin's internal definition. This token is only meaningful
1847 as the second argument to 'define' (and 'pushdef'), and is silently
1848 converted to an empty string in most other contexts. Combining a
1849 builtin with anything else is not supported; a warning is issued
1850 and the builtin is omitted from the final expansion.
1852 The macro 'defn' is recognized only with parameters.
1854 Its normal use is best understood through an example, which shows how
1855 to rename 'undefine' to 'zap':
1857 define(`zap', defn(`undefine'))
1864 In this way, 'defn' can be used to copy macro definitions, and also
1865 definitions of builtin macros. Even if the original macro is removed,
1866 the other name can still be used to access the definition.
1868 The fact that macro definitions can be transferred also explains why
1869 you should use '$0', rather than retyping a macro's name in its
1872 define(`foo', `This is `$0'')
1874 define(`bar', defn(`foo'))
1879 Macros used as string variables should be referred through 'defn', to
1880 avoid unwanted expansion of the text:
1882 define(`string', `The macro dnl is very useful
1888 =>The macro dnl is very useful
1891 However, it is important to remember that 'm4' rescanning is purely
1892 textual. If an unbalanced end-quote string occurs in a macro
1893 definition, the rescan will see that embedded quote as the termination
1894 of the quoted string, and the remainder of the macro's definition will
1895 be rescanned unquoted. Thus it is a good idea to avoid unbalanced
1896 end-quotes in macro definitions or arguments to macros.
1902 define(`echo', `$@')
1911 On the other hand, it is possible to exploit the fact that 'defn' can
1912 concatenate multiple macros prior to the rescanning phase, in order to
1913 join the definitions of macros that, in isolation, have unbalanced
1914 quotes. This is particularly useful when one has used several macros to
1915 accumulate text that M4 should rescan as a whole. In the example below,
1916 note how the use of 'defn' on 'l' in isolation opens a string, which is
1917 not closed until the next line; but used on 'l' and 'r' together results
1920 define(`l', `<[>')define(`r', `<]>')
1922 changequote(`[', `]')
1931 Using 'defn' to generate special tokens for builtin macros outside of
1932 expected contexts can sometimes trigger warnings. But most of the time,
1933 such tokens are silently converted to the empty string.
1938 define(defn(`divnum'), `cannot redefine a builtin token')
1939 error->m4:stdin:2: Warning: define: invalid macro name ignored
1946 Also note that 'defn' with multiple arguments can only join text
1947 macros, not builtins, although a future version of GNU M4 may lift this
1951 define(`a', `A')define(`AA', `b')
1953 traceon(`defn', `define')
1955 defn(`a', `divnum', `a')
1956 error->m4:stdin:3: Warning: cannot concatenate builtin `divnum'
1957 error->m4trace: -1- defn(`a', `divnum', `a') -> ``A'`A''
1959 define(`mydivnum', defn(`divnum', `divnum'))mydivnum
1960 error->m4:stdin:4: Warning: cannot concatenate builtin `divnum'
1961 error->m4:stdin:4: Warning: cannot concatenate builtin `divnum'
1962 error->m4trace: -2- defn(`divnum', `divnum')
1963 error->m4trace: -1- define(`mydivnum', `')
1965 traceoff(`defn', `define')
1969 File: m4.info, Node: Pushdef, Next: Indir, Prev: Defn, Up: Definitions
1971 5.6 Temporarily redefining macros
1972 =================================
1974 It is possible to redefine a macro temporarily, reverting to the
1975 previous definition at a later time. This is done with the builtins
1976 'pushdef' and 'popdef':
1978 -- Builtin: pushdef (NAME, [EXPANSION]
1979 -- Builtin: popdef (NAME...)
1980 Analogous to 'define' and 'undefine'.
1982 These macros work in a stack-like fashion. A macro is temporarily
1983 redefined with 'pushdef', which replaces an existing definition of
1984 NAME, while saving the previous definition, before the new one is
1985 installed. If there is no previous definition, 'pushdef' behaves
1986 exactly like 'define'.
1988 If a macro has several definitions (of which only one is
1989 accessible), the topmost definition can be removed with 'popdef'.
1990 If there is no previous definition, 'popdef' behaves like
1993 The expansion of both 'pushdef' and 'popdef' is void. The macros
1994 'pushdef' and 'popdef' are recognized only with parameters.
1996 define(`foo', `Expansion one.')
2000 pushdef(`foo', `Expansion two.')
2004 pushdef(`foo', `Expansion three.')
2006 pushdef(`foo', `Expansion four.')
2012 popdef(`foo', `foo')
2021 If a macro with several definitions is redefined with 'define', the
2022 topmost definition is _replaced_ with the new definition. If it is
2023 removed with 'undefine', _all_ the definitions are removed, and not only
2024 the topmost one. However, POSIX allows other implementations that treat
2025 'define' as replacing an entire stack of definitions with a single new
2026 definition, so to be portable to other implementations, it may be worth
2027 explicitly using 'popdef' and 'pushdef' rather than relying on the GNU
2028 behavior of 'define'.
2030 define(`foo', `Expansion one.')
2034 pushdef(`foo', `Expansion two.')
2038 define(`foo', `Second expansion two.')
2041 =>Second expansion two.
2047 Local variables within macros are made with 'pushdef' and 'popdef'.
2048 At the start of the macro a new definition is pushed, within the macro
2049 it is manipulated and at the end it is popped, revealing the former
2052 It is possible to temporarily redefine a builtin with 'pushdef' and
2056 File: m4.info, Node: Indir, Next: Builtin, Prev: Pushdef, Up: Definitions
2058 5.7 Indirect call of macros
2059 ===========================
2061 Any macro can be called indirectly with 'indir':
2063 -- Builtin: indir (NAME, [ARGS...]
2064 Results in a call to the macro NAME, which is passed the rest of
2065 the arguments ARGS. If NAME is not defined, an error message is
2066 printed, and the expansion is void.
2068 The macro 'indir' is recognized only with parameters.
2070 This can be used to call macros with computed or "invalid" names
2071 ('define' allows such names to be defined):
2073 define(`$$internal$macro', `Internal macro (name `$0')')
2077 indir(`$$internal$macro')
2078 =>Internal macro (name $$internal$macro)
2080 The point is, here, that larger macro packages can have private
2081 macros defined, that will not be called by accident. They can _only_ be
2082 called through the builtin 'indir'.
2084 One other point to observe is that argument collection occurs before
2085 'indir' invokes NAME, so if argument collection changes the value of
2086 NAME, that will be reflected in the final expansion. This is different
2087 than the behavior when invoking macros directly, where the definition
2088 that was in effect before argument collection is used.
2095 indir(`f', define(`f', `3'))
2097 indir(`f', undefine(`f'))
2098 error->m4:stdin:4: undefined macro `f'
2101 When handed the result of 'defn' (*note Defn::) as one of its
2102 arguments, 'indir' defers to the invoked NAME for whether a token
2103 representing a builtin is recognized or flattened to the empty string.
2106 indir(defn(`defn'), `divnum')
2107 error->m4:stdin:1: Warning: indir: invalid macro name ignored
2109 indir(`define', defn(`defn'), `divnum')
2110 error->m4:stdin:2: Warning: define: invalid macro name ignored
2112 indir(`define', `foo', defn(`divnum'))
2116 indir(`divert', defn(`foo'))
2117 error->m4:stdin:5: empty string treated as 0 in builtin `divert'
2121 File: m4.info, Node: Builtin, Prev: Indir, Up: Definitions
2123 5.8 Indirect call of builtins
2124 =============================
2126 Builtin macros can be called indirectly with 'builtin':
2128 -- Builtin: builtin (NAME, [ARGS...]
2129 Results in a call to the builtin NAME, which is passed the rest of
2130 the arguments ARGS. If NAME does not name a builtin, an error
2131 message is printed, and the expansion is void.
2133 The macro 'builtin' is recognized only with parameters.
2135 This can be used even if NAME has been given another definition that
2136 has covered the original, or been undefined so that no macro maps to the
2139 pushdef(`define', `hidden')
2141 undefine(`undefine')
2143 define(`foo', `bar')
2147 builtin(`define', `foo', defn(`divnum'))
2151 builtin(`define', `foo', `BAR')
2159 builtin(`undefine', `foo')
2164 The NAME argument only matches the original name of the builtin, even
2165 when the '--prefix-builtins' option (or '-P', *note Invoking m4:
2166 Operation modes.) is in effect. This is different from 'indir', which
2167 only tracks current macro names.
2170 m4_builtin(`divnum')
2172 m4_builtin(`m4_divnum')
2173 error->m4:stdin:2: undefined builtin `m4_divnum'
2176 error->m4:stdin:3: undefined macro `divnum'
2178 m4_indir(`m4_divnum')
2181 Note that 'indir' and 'builtin' can be used to invoke builtins
2182 without arguments, even when they normally require parameters to be
2183 recognized; but it will provoke a warning, and result in a void
2189 error->m4:stdin:2: undefined builtin `'
2192 error->m4:stdin:3: Warning: too few arguments to builtin `builtin'
2195 error->m4:stdin:4: undefined builtin `'
2197 builtin(`builtin', ``'
2199 error->m4:stdin:5: undefined builtin ``'
2203 error->m4:stdin:7: Warning: too few arguments to builtin `index'
2207 File: m4.info, Node: Conditionals, Next: Debugging, Prev: Definitions, Up: Top
2209 6 Conditionals, loops, and recursion
2210 ************************************
2212 Macros, expanding to plain text, perhaps with arguments, are not quite
2213 enough. We would like to have macros expand to different things, based
2214 on decisions taken at run-time. For that, we need some kind of
2215 conditionals. Also, we would like to have some kind of loop construct,
2216 so we could do something a number of times, or while some condition is
2221 * Ifdef:: Testing if a macro is defined
2222 * Ifelse:: If-else construct, or multibranch
2223 * Shift:: Recursion in 'm4'
2224 * Forloop:: Iteration by counting
2225 * Foreach:: Iteration by list contents
2226 * Stacks:: Working with definition stacks
2227 * Composition:: Building macros with macros
2230 File: m4.info, Node: Ifdef, Next: Ifelse, Up: Conditionals
2232 6.1 Testing if a macro is defined
2233 =================================
2235 There are two different builtin conditionals in 'm4'. The first is
2238 -- Builtin: ifdef (NAME, STRING-1, [STRING-2]
2239 If NAME is defined as a macro, 'ifdef' expands to STRING-1,
2240 otherwise to STRING-2. If STRING-2 is omitted, it is taken to be
2241 the empty string (according to the normal rules).
2243 The macro 'ifdef' is recognized only with parameters.
2245 ifdef(`foo', ``foo' is defined', ``foo' is not defined')
2246 =>foo is not defined
2249 ifdef(`foo', ``foo' is defined', ``foo' is not defined')
2251 ifdef(`no_such_macro', `yes', `no', `extra argument')
2252 error->m4:stdin:4: Warning: excess arguments to builtin `ifdef' ignored
2256 File: m4.info, Node: Ifelse, Next: Shift, Prev: Ifdef, Up: Conditionals
2258 6.2 If-else construct, or multibranch
2259 =====================================
2261 The other conditional, 'ifelse', is much more powerful. It can be used
2262 as a way to introduce a long comment, as an if-else construct, or as a
2263 multibranch, depending on the number of arguments supplied:
2265 -- Builtin: ifelse (COMMENT)
2266 -- Builtin: ifelse (STRING-1, STRING-2, EQUAL, [NOT-EQUAL]
2267 -- Builtin: ifelse (STRING-1, STRING-2, EQUAL-1, STRING-3, STRING-4,
2268 EQUAL-2, ..., [NOT-EQUAL]
2269 Used with only one argument, the 'ifelse' simply discards it and
2272 If called with three or four arguments, 'ifelse' expands into
2273 EQUAL, if STRING-1 and STRING-2 are equal (character for
2274 character), otherwise it expands to NOT-EQUAL. A final fifth
2275 argument is ignored, after triggering a warning.
2277 If called with six or more arguments, and STRING-1 and STRING-2 are
2278 equal, 'ifelse' expands into EQUAL-1, otherwise the first three
2279 arguments are discarded and the processing starts again.
2281 The macro 'ifelse' is recognized only with parameters.
2283 Using only one argument is a common 'm4' idiom for introducing a
2284 block comment, as an alternative to repeatedly using 'dnl'. This
2285 special usage is recognized by GNU 'm4', so that in this case, the
2286 warning about missing arguments is never triggered.
2288 ifelse(`some comments')
2290 ifelse(`foo', `bar')
2291 error->m4:stdin:2: Warning: too few arguments to builtin `ifelse'
2294 Using three or four arguments provides decision points.
2296 ifelse(`foo', `bar', `true')
2298 ifelse(`foo', `foo', `true')
2300 define(`foo', `bar')
2302 ifelse(foo, `bar', `true', `false')
2304 ifelse(foo, `foo', `true', `false')
2307 Notice how the first argument was used unquoted; it is common to
2308 compare the expansion of a macro with a string. With this macro, you
2309 can now reproduce the behavior of blind builtins, where the macro is
2310 recognized only with arguments.
2312 define(`foo', `ifelse(`$#', `0', ``$0'', `arguments:$#')')
2321 For an example of a way to make defining blind macros easier, see
2322 *note Composition::.
2324 The macro 'ifelse' can take more than four arguments. If given more
2325 than four arguments, 'ifelse' works like a 'case' or 'switch' statement
2326 in traditional programming languages. If STRING-1 and STRING-2 are
2327 equal, 'ifelse' expands into EQUAL-1, otherwise the procedure is
2328 repeated with the first three arguments discarded. This calls for an
2331 ifelse(`foo', `bar', `third', `gnu', `gnats')
2332 error->m4:stdin:1: Warning: excess arguments to builtin `ifelse' ignored
2334 ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth')
2336 ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth', `seventh')
2338 ifelse(`foo', `bar', `3', `gnu', `gnats', `6', `7', `8')
2339 error->m4:stdin:4: Warning: excess arguments to builtin `ifelse' ignored
2342 Naturally, the normal case will be slightly more advanced than these
2343 examples. A common use of 'ifelse' is in macros implementing loops of
2347 File: m4.info, Node: Shift, Next: Forloop, Prev: Ifelse, Up: Conditionals
2349 6.3 Recursion in 'm4'
2350 =====================
2352 There is no direct support for loops in 'm4', but macros can be
2353 recursive. There is no limit on the number of recursion levels, other
2354 than those enforced by your hardware and operating system.
2356 Loops can be programmed using recursion and the conditionals
2357 described previously.
2359 There is a builtin macro, 'shift', which can, among other things, be
2360 used for iterating through the actual arguments to a macro:
2362 -- Builtin: shift (ARG1, ...)
2363 Takes any number of arguments, and expands to all its arguments
2364 except ARG1, separated by commas, with each argument quoted.
2366 The macro 'shift' is recognized only with parameters.
2372 shift(`foo', `bar', `baz')
2375 An example of the use of 'shift' is this macro:
2377 -- Composite: reverse (...)
2378 Takes any number of arguments, and reverses their order.
2380 It is implemented as:
2382 define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
2383 `reverse(shift($@)), `$1'')')
2389 reverse(`foo', `bar', `gnats', `and gnus')
2390 =>and gnus, gnats, bar, foo
2392 While not a very interesting macro, it does show how simple loops can
2393 be made with 'shift', 'ifelse' and recursion. It also shows that
2394 'shift' is usually used with '$@'. Another example of this is an
2395 implementation of a short-circuiting conditional operator.
2397 -- Composite: cond (TEST-1, STRING-1, EQUAL-1, [TEST-2]
2398 Similar to 'ifelse', where an equal comparison between the first
2399 two strings results in the third, otherwise the first three
2400 arguments are discarded and the process repeats. The difference is
2401 that each TEST-<N> is expanded only when it is encountered. This
2402 means that every third argument to 'cond' is normally given one
2403 more level of quoting than the corresponding argument to 'ifelse'.
2405 Here is the implementation of 'cond', along with a demonstration of
2406 how it can short-circuit the side effects in 'side'. Notice how all the
2407 unquoted side effects happen regardless of how many comparisons are made
2408 with 'ifelse', compared with only the relevant effects with 'cond'.
2411 `ifelse(`$#', `1', `$1',
2412 `ifelse($1, `$2', `$3',
2413 `$0(shift(shift(shift($@))))')')')dnl
2414 define(`side', `define(`counter', incr(counter))$1')dnl
2416 `define(`counter', `0')dnl
2417 ifelse(side(`$1'), `yes', `one comparison: ',
2418 side(`$1'), `no', `two comparisons: ',
2419 side(`$1'), `maybe', `three comparisons: ',
2420 `side(`default answer: ')')counter')dnl
2422 `define(`counter', `0')dnl
2423 cond(`side(`$1')', `yes', `one comparison: ',
2424 `side(`$1')', `no', `two comparisons: ',
2425 `side(`$1')', `maybe', `three comparisons: ',
2426 `side(`default answer: ')')counter')dnl
2430 =>two comparisons: 3
2432 =>three comparisons: 3
2433 example1(`feeling rather indecisive today')
2438 =>two comparisons: 2
2440 =>three comparisons: 3
2441 example2(`feeling rather indecisive today')
2444 Another common task that requires iteration is joining a list of
2445 arguments into a single string.
2447 -- Composite: join ([SEPARATOR]
2448 -- Composite: joinall ([SEPARATOR]
2449 Generate a single-quoted string, consisting of each ARG separated
2450 by SEPARATOR. While 'joinall' always outputs a SEPARATOR between
2451 arguments, 'join' avoids the SEPARATOR for an empty ARG.
2453 Here are some examples of its usage, based on the implementation
2454 'm4-1.4.17/examples/join.m4' distributed in this package:
2459 join,join(`-'),join(`-', `'),join(`-', `', `')
2461 joinall,joinall(`-'),joinall(`-', `'),joinall(`-', `', `')
2465 join(`-', `1', `2', `3')
2467 join(`', `1', `2', `3')
2469 join(`-', `', `1', `', `', `2', `')
2471 joinall(`-', `', `1', `', `', `2', `')
2473 join(`,', `1', `2', `3')
2475 define(`nargs', `$#')dnl
2476 nargs(join(`,', `1', `2', `3'))
2479 Examining the implementation shows some interesting points about
2480 several m4 programming idioms.
2483 undivert(`join.m4')dnl
2485 =># join(sep, args) - join each non-empty ARG into a single
2486 =># string, with each element separated by SEP
2488 =>`ifelse(`$#', `2', ``$2'',
2489 => `ifelse(`$2', `', `', ``$2'_')$0(`$1', shift(shift($@)))')')
2491 =>`ifelse(`$#$2', `2', `',
2492 => `ifelse(`$2', `', `', ``$1$2'')$0(`$1', shift(shift($@)))')')
2493 =># joinall(sep, args) - join each ARG, including empty ones,
2494 =># into a single string, with each element separated by SEP
2495 =>define(`joinall', ``$2'_$0(`$1', shift($@))')
2496 =>define(`_joinall',
2497 =>`ifelse(`$#', `2', `', ``$1$3'$0(`$1', shift(shift($@)))')')
2500 First, notice that this implementation creates helper macros '_join'
2501 and '_joinall'. This division of labor makes it easier to output the
2502 correct number of SEPARATOR instances: 'join' and 'joinall' are
2503 responsible for the first argument, without a separator, while '_join'
2504 and '_joinall' are responsible for all remaining arguments, always
2505 outputting a separator when outputting an argument.
2507 Next, observe how 'join' decides to iterate to itself, because the
2508 first ARG was empty, or to output the argument and swap over to '_join'.
2509 If the argument is non-empty, then the nested 'ifelse' results in an
2510 unquoted '_', which is concatenated with the '$0' to form the next macro
2511 name to invoke. The 'joinall' implementation is simpler since it does
2512 not have to suppress empty ARG; it always executes once then defers to
2515 Another important idiom is the idea that SEPARATOR is reused for each
2516 iteration. Each iteration has one less argument, but rather than
2517 discarding '$1' by iterating with '$0(shift($@))', the macro discards
2518 '$2' by using '$0(`$1', shift(shift($@)))'.
2520 Next, notice that it is possible to compare more than one condition
2521 in a single 'ifelse' test. The test of '$#$2' against '2' allows
2522 '_join' to iterate for two separate reasons--either there are still more
2523 than two arguments, or there are exactly two arguments but the last
2524 argument is not empty.
2526 Finally, notice that these macros require exactly two arguments to
2527 terminate recursion, but that they still correctly result in empty
2528 output when given no ARGS (i.e., zero or one macro argument). On the
2529 first pass when there are too few arguments, the 'shift' results in no
2530 output, but leaves an empty string to serve as the required second
2531 argument for the second pass. Put another way, '`$1', shift($@)' is not
2532 the same as '$@', since only the former guarantees at least two
2535 Sometimes, a recursive algorithm requires adding quotes to each
2536 element, or treating multiple arguments as a single element:
2538 -- Composite: quote (...)
2539 -- Composite: dquote (...)
2540 -- Composite: dquote_elt (...)
2541 Takes any number of arguments, and adds quoting. With 'quote',
2542 only one level of quoting is added, effectively removing whitespace
2543 after commas and turning multiple arguments into a single string.
2544 With 'dquote', two levels of quoting are added, one around each
2545 element, and one around the list. And with 'dquote_elt', two
2546 levels of quoting are added around each element.
2548 An actual implementation of these three macros is distributed as
2549 'm4-1.4.17/examples/quote.m4' in this package. First, let's examine
2555 -quote-dquote-dquote_elt-
2557 -quote()-dquote()-dquote_elt()-
2559 -quote(`1')-dquote(`1')-dquote_elt(`1')-
2561 -quote(`1', `2')-dquote(`1', `2')-dquote_elt(`1', `2')-
2562 =>-1,2-`1',`2'-`1',`2'-
2563 define(`n', `$#')dnl
2564 -n(quote(`1', `2'))-n(dquote(`1', `2'))-n(dquote_elt(`1', `2'))-
2566 dquote(dquote_elt(`1', `2'))
2568 dquote_elt(dquote(`1', `2'))
2571 The last two lines show that when given two arguments, 'dquote'
2572 results in one string, while 'dquote_elt' results in two. Now, examine
2573 the implementation. Note that 'quote' and 'dquote_elt' make decisions
2574 based on their number of arguments, so that when called without
2575 arguments, they result in nothing instead of a quoted empty string; this
2576 is so that it is possible to distinguish between no arguments and an
2577 empty first argument. 'dquote', on the other hand, results in a string
2578 no matter what, since it is still possible to tell whether it was
2579 invoked without arguments based on the resulting string.
2582 undivert(`quote.m4')dnl
2584 =># quote(args) - convert args to single-quoted string
2585 =>define(`quote', `ifelse(`$#', `0', `', ``$*'')')
2586 =># dquote(args) - convert args to quoted list of quoted strings
2587 =>define(`dquote', ``$@'')
2588 =># dquote_elt(args) - convert args to list of double-quoted strings
2589 =>define(`dquote_elt', `ifelse(`$#', `0', `', `$#', `1', ```$1''',
2590 => ```$1'',$0(shift($@))')')
2593 It is worth pointing out that 'quote(ARGS)' is more efficient than
2594 'joinall(`,', ARGS)' for producing the same output.
2596 One more useful macro based on 'shift' allows portably selecting an
2597 arbitrary argument (usually greater than the ninth argument), without
2598 relying on the GNU extension of multi-digit arguments (*note
2601 -- Composite: argn (N, ...)
2602 Expands to argument N out of the remaining arguments. N must be a
2603 positive number. Usually invoked as 'argn(`N',$@)'.
2605 It is implemented as:
2607 define(`argn', `ifelse(`$1', 1, ``$2'',
2608 `argn(decr(`$1'), shift(shift($@)))')')
2612 define(`foo', `argn(`11', $@)')
2614 foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l')
2618 File: m4.info, Node: Forloop, Next: Foreach, Prev: Shift, Up: Conditionals
2620 6.4 Iteration by counting
2621 =========================
2623 Here is an example of a loop macro that implements a simple for loop.
2625 -- Composite: forloop (ITERATOR, START, END, TEXT)
2626 Takes the name in ITERATOR, which must be a valid macro name, and
2627 successively assign it each integer value from START to END,
2628 inclusive. For each assignment to ITERATOR, append TEXT to the
2629 expansion of the 'forloop'. TEXT may refer to ITERATOR. Any
2630 definition of ITERATOR prior to this invocation is restored.
2632 It can, for example, be used for simple counting:
2635 include(`forloop.m4')
2637 forloop(`i', `1', `8', `i ')
2640 For-loops can be nested, like:
2643 include(`forloop.m4')
2645 forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)')
2647 => (1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8)
2648 => (2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8)
2649 => (3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8)
2650 => (4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8)
2653 The implementation of the 'forloop' macro is fairly straightforward.
2654 The 'forloop' macro itself is simply a wrapper, which saves the previous
2655 definition of the first argument, calls the internal macro '_forloop',
2656 and re-establishes the saved definition of the first argument.
2658 The macro '_forloop' expands the fourth argument once, and tests to
2659 see if the iterator has reached the final value. If it has not
2660 finished, it increments the iterator (using the predefined macro 'incr',
2661 *note Incr::), and recurses.
2663 Here is an actual implementation of 'forloop', distributed as
2664 'm4-1.4.17/examples/forloop.m4' in this package:
2667 undivert(`forloop.m4')dnl
2669 =># forloop(var, from, to, stmt) - simple version
2670 =>define(`forloop', `pushdef(`$1', `$2')_forloop($@)popdef(`$1')')
2671 =>define(`_forloop',
2672 => `$4`'ifelse($1, `$3', `', `define(`$1', incr($1))$0($@)')')
2675 Notice the careful use of quotes. Certain macro arguments are left
2676 unquoted, each for its own reason. Try to find out _why_ these
2677 arguments are left unquoted, and see what happens if they are quoted.
2678 (As presented, these two macros are useful but not very robust for
2679 general use. They lack even basic error handling for cases like START
2680 less than END, END not numeric, or ITERATOR not being a macro name. See
2681 if you can improve these macros; or *note Answers: Improved forloop.).
2684 File: m4.info, Node: Foreach, Next: Stacks, Prev: Forloop, Up: Conditionals
2686 6.5 Iteration by list contents
2687 ==============================
2689 Here is an example of a loop macro that implements list iteration.
2691 -- Composite: foreach (ITERATOR, PAREN-LIST, TEXT)
2692 -- Composite: foreachq (ITERATOR, QUOTE-LIST, TEXT)
2693 Takes the name in ITERATOR, which must be a valid macro name, and
2694 successively assign it each value from PAREN-LIST or QUOTE-LIST.
2695 In 'foreach', PAREN-LIST is a comma-separated list of elements
2696 contained in parentheses. In 'foreachq', QUOTE-LIST is a
2697 comma-separated list of elements contained in a quoted string. For
2698 each assignment to ITERATOR, append TEXT to the overall expansion.
2699 TEXT may refer to ITERATOR. Any definition of ITERATOR prior to
2700 this invocation is restored.
2702 As an example, this displays each word in a list inside of a
2703 sentence, using an implementation of 'foreach' distributed as
2704 'm4-1.4.17/examples/foreach.m4', and 'foreachq' in
2705 'm4-1.4.17/examples/foreachq.m4'.
2708 include(`foreach.m4')
2710 foreach(`x', (foo, bar, foobar), `Word was: x
2715 include(`foreachq.m4')
2717 foreachq(`x', `foo, bar, foobar', `Word was: x
2723 It is possible to be more complex; each element of the PAREN-LIST or
2724 QUOTE-LIST can itself be a list, to pass as further arguments to a
2725 helper macro. This example generates a shell case statement:
2728 include(`foreach.m4')
2730 define(`_case', ` $1)
2733 define(`_cat', `$1$2')dnl
2736 foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')',
2737 `_cat(`_case', x)')dnl
2747 The implementation of the 'foreach' macro is a bit more involved; it
2748 is a wrapper around two helper macros. First, '_arg1' is needed to grab
2749 the first element of a list. Second, '_foreach' implements the
2750 recursion, successively walking through the original list. Here is a
2751 simple implementation of 'foreach':
2754 undivert(`foreach.m4')dnl
2756 =># foreach(x, (item_1, item_2, ..., item_n), stmt)
2757 =># parenthesized list, simple version
2758 =>define(`foreach', `pushdef(`$1')_foreach($@)popdef(`$1')')
2759 =>define(`_arg1', `$1')
2760 =>define(`_foreach', `ifelse(`$2', `()', `',
2761 => `define(`$1', _arg1$2)$3`'$0(`$1', (shift$2), `$3')')')
2764 Unfortunately, that implementation is not robust to macro names as
2765 list elements. Each iteration of '_foreach' is stripping another layer
2766 of quotes, leading to erratic results if list elements are not already
2767 fully expanded. The first cut at implementing 'foreachq' takes this
2768 into account. Also, when using quoted elements in a PAREN-LIST, the
2769 overall list must be quoted. A QUOTE-LIST has the nice property of
2770 requiring fewer characters to create a list containing the same quoted
2771 elements. To see the difference between the two macros, we attempt to
2772 pass double-quoted macro names in a list, expecting the macro name on
2773 output after one layer of quotes is removed during list iteration and
2774 the final layer removed during the final rescan:
2777 define(`a', `1')define(`b', `2')define(`c', `3')
2779 include(`foreach.m4')
2781 include(`foreachq.m4')
2783 foreach(`x', `(``a'', ``(b'', ``c)'')', `x
2790 foreachq(`x', ```a'', ``(b'', ``c)''', `x
2796 Obviously, 'foreachq' did a better job; here is its implementation:
2799 undivert(`foreachq.m4')dnl
2800 =>include(`quote.m4')dnl
2802 =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
2803 =># quoted list, simple version
2804 =>define(`foreachq', `pushdef(`$1')_foreachq($@)popdef(`$1')')
2805 =>define(`_arg1', `$1')
2806 =>define(`_foreachq', `ifelse(quote($2), `', `',
2807 => `define(`$1', `_arg1($2)')$3`'$0(`$1', `shift($2)', `$3')')')
2810 Notice that '_foreachq' had to use the helper macro 'quote' defined
2811 earlier (*note Shift::), to ensure that the embedded 'ifelse' call does
2812 not go haywire if a list element contains a comma. Unfortunately, this
2813 implementation of 'foreachq' has its own severe flaw. Whereas the
2814 'foreach' implementation was linear, this macro is quadratic in the
2815 number of list elements, and is much more likely to trip up the limit
2816 set by the command line option '--nesting-limit' (or '-L', *note
2817 Invoking m4: Limits control.). Additionally, this implementation does
2818 not expand 'defn(`ITERATOR')' very well, when compared with 'foreach'.
2821 include(`foreach.m4')include(`foreachq.m4')
2823 foreach(`name', `(`a', `b')', ` defn(`name')')
2825 foreachq(`name', ``a', `b'', ` defn(`name')')
2826 => _arg1(`a', `b') _arg1(shift(`a', `b'))
2828 It is possible to have robust iteration with linear behavior and sane
2829 ITERATOR contents for either list style. See if you can learn from the
2830 best elements of both of these implementations to create robust macros
2831 (or *note Answers: Improved foreach.).
2834 File: m4.info, Node: Stacks, Next: Composition, Prev: Foreach, Up: Conditionals
2836 6.6 Working with definition stacks
2837 ==================================
2839 Thanks to 'pushdef', manipulation of a stack is an intrinsic operation
2840 in 'm4'. Normally, only the topmost definition in a stack is important,
2841 but sometimes, it is desirable to manipulate the entire definition
2844 -- Composite: stack_foreach (MACRO, ACTION)
2845 -- Composite: stack_foreach_lifo (MACRO, ACTION)
2846 For each of the 'pushdef' definitions associated with MACRO, invoke
2847 the macro ACTION with a single argument of that definition.
2848 'stack_foreach' visits the oldest definition first, while
2849 'stack_foreach_lifo' visits the current definition first. ACTION
2850 should not modify or dereference MACRO. There are a few special
2851 macros, such as 'defn', which cannot be used as the MACRO
2854 A sample implementation of these macros is distributed in the file
2855 'm4-1.4.17/examples/stack.m4'.
2860 pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
2862 define(`show', ``$1'
2865 stack_foreach(`a', `show')dnl
2869 stack_foreach_lifo(`a', `show')dnl
2874 Now for the implementation. Note the definition of a helper macro,
2875 '_stack_reverse', which destructively swaps the contents of one stack of
2876 definitions into the reverse order in the temporary macro 'tmp-$1'. By
2877 calling the helper twice, the original order is restored back into the
2878 macro '$1'; since the operation is destructive, this explains why '$1'
2879 must not be modified or dereferenced during the traversal. The caller
2880 can then inject additional code to pass the definition currently being
2881 visited to '$2'. The choice of helper names is intentional; since '-'
2882 is not valid as part of a macro name, there is no risk of conflict with
2883 a valid macro name, and the code is guaranteed to use 'defn' where
2884 necessary. Finally, note that any macro used in the traversal of a
2885 'pushdef' stack, such as 'pushdef' or 'defn', cannot be handled by
2886 'stack_foreach', since the macro would temporarily be undefined during
2890 undivert(`stack.m4')dnl
2892 =># stack_foreach(macro, action)
2893 =># Invoke ACTION with a single argument of each definition
2894 =># from the definition stack of MACRO, starting with the oldest.
2895 =>define(`stack_foreach',
2896 =>`_stack_reverse(`$1', `tmp-$1')'dnl
2897 =>`_stack_reverse(`tmp-$1', `$1', `$2(defn(`$1'))')')
2898 =># stack_foreach_lifo(macro, action)
2899 =># Invoke ACTION with a single argument of each definition
2900 =># from the definition stack of MACRO, starting with the newest.
2901 =>define(`stack_foreach_lifo',
2902 =>`_stack_reverse(`$1', `tmp-$1', `$2(defn(`$1'))')'dnl
2903 =>`_stack_reverse(`tmp-$1', `$1')')
2904 =>define(`_stack_reverse',
2905 =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0($@)')')
2909 File: m4.info, Node: Composition, Prev: Stacks, Up: Conditionals
2911 6.7 Building macros with macros
2912 ===============================
2914 Since m4 is a macro language, it is possible to write macros that can
2915 build other macros. First on the list is a way to automate the creation
2918 -- Composite: define_blind (NAME, [VALUE]
2919 Defines NAME as a blind macro, such that NAME will expand to VALUE
2920 only when given explicit arguments. VALUE should not be the result
2921 of 'defn' (*note Defn::). This macro is only recognized with
2922 parameters, and results in an empty string.
2924 Defining a macro to define another macro can be a bit tricky. We
2925 want to use a literal '$#' in the argument to the nested 'define'.
2926 However, if '$' and '#' are adjacent in the definition of
2927 'define_blind', then it would be expanded as the number of arguments to
2928 'define_blind' rather than the intended number of arguments to NAME.
2929 The solution is to pass the difficult characters through extra arguments
2930 to a helper macro '_define_blind'. When composing macros, it is a
2931 common idiom to need a helper macro to concatenate text that forms
2932 parameters in the composed macro, rather than interpreting the text as a
2933 parameter of the composing macro.
2935 As for the limitation against using 'defn', there are two reasons.
2936 If a macro was previously defined with 'define_blind', then it can
2937 safely be renamed to a new blind macro using plain 'define'; using
2938 'define_blind' to rename it just adds another layer of 'ifelse',
2939 occupying memory and slowing down execution. And if a macro is a
2940 builtin, then it would result in an attempt to define a macro consisting
2941 of both text and a builtin token; this is not supported, and the builtin
2942 token is flattened to an empty string.
2944 With that explanation, here's the definition, and some sample usage.
2945 Notice that 'define_blind' is itself a blind macro.
2948 define(`define_blind', `ifelse(`$#', `0', ``$0'',
2949 `_$0(`$1', `$2', `$'`#', `$'`0')')')
2951 define(`_define_blind', `define(`$1',
2952 `ifelse(`$3', `0', ``$4'', `$2')')')
2956 define_blind(`foo', `arguments were $*')
2961 =>arguments were bar
2962 define(`blah', defn(`foo'))
2967 =>arguments were a,b
2969 =>ifelse(`$#', `0', ``$0'', `arguments were $*')
2971 Another interesting composition tactic is argument "currying", or
2972 factoring a macro that takes multiple arguments for use in a context
2973 that provides exactly one argument.
2975 -- Composite: curry (MACRO, ...)
2976 Expand to a macro call that takes exactly one argument, then
2977 appends that argument to the original arguments and invokes MACRO
2978 with the resulting list of arguments.
2980 A demonstration of currying makes the intent of this macro a little
2981 more obvious. The macro 'stack_foreach' mentioned earlier is an example
2982 of a context that provides exactly one argument to a macro name. But
2983 coupled with currying, we can invoke 'reverse' with two arguments for
2984 each definition of a macro stack. This example uses the file
2985 'm4-1.4.17/examples/curry.m4' included in the distribution.
2988 include(`curry.m4')include(`stack.m4')
2990 define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
2991 `reverse(shift($@)), `$1'')')
2993 pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
2995 stack_foreach(`a', `:curry(`reverse', `4')')
2997 curry(`curry', `reverse', `1')(`2')(`3')
3000 Now for the implementation. Notice how 'curry' leaves off with a
3001 macro name but no open parenthesis, while still in the middle of
3002 collecting arguments for '$1'. The macro '_curry' is the helper macro
3003 that takes one argument, then adds it to the list and finally supplies
3004 the closing parenthesis. The use of a comma inside the 'shift' call
3005 allows currying to also work for a macro that takes one argument,
3006 although it often makes more sense to invoke that macro directly rather
3007 than going through 'curry'.
3010 undivert(`curry.m4')dnl
3012 =># curry(macro, args)
3013 =># Expand to a macro call that takes one argument, then invoke
3014 =># macro(args, extra).
3015 =>define(`curry', `$1(shift($@,)_$0')
3016 =>define(`_curry', ``$1')')
3019 Unfortunately, with M4 1.4.x, 'curry' is unable to handle builtin
3020 tokens, which are silently flattened to the empty string when passed
3021 through another text macro. This limitation will be lifted in a future
3024 Putting the last few concepts together, it is possible to copy or
3025 rename an entire stack of macro definitions.
3027 -- Composite: copy (SOURCE, DEST)
3028 -- Composite: rename (SOURCE, DEST)
3029 Ensure that DEST is undefined, then define it to the same stack of
3030 definitions currently in SOURCE. 'copy' leaves SOURCE unchanged,
3031 while 'rename' undefines SOURCE. There are only a few macros, such
3032 as 'copy' or 'defn', which cannot be copied via this macro.
3034 The implementation is relatively straightforward (although since it
3035 uses 'curry', it is unable to copy builtin macros, such as the second
3036 definition of 'a' as a synonym for 'divnum'. See if you can design a
3037 version that works around this limitation, or *note Answers: Improved
3041 include(`curry.m4')include(`stack.m4')
3043 define(`rename', `copy($@)undefine(`$1')')dnl
3044 define(`copy', `ifdef(`$2', `errprint(`$2 already defined
3046 `stack_foreach(`$1', `curry(`pushdef', `$2')')')')dnl
3047 pushdef(`a', `1')pushdef(`a', defn(`divnum'))pushdef(`a', `2')
3061 File: m4.info, Node: Debugging, Next: Input Control, Prev: Conditionals, Up: Top
3063 7 How to debug macros and input
3064 *******************************
3066 When writing macros for 'm4', they often do not work as intended on the
3067 first try (as is the case with most programming languages).
3068 Fortunately, there is support for macro debugging in 'm4'.
3072 * Dumpdef:: Displaying macro definitions
3073 * Trace:: Tracing macro calls
3074 * Debug Levels:: Controlling debugging output
3075 * Debug Output:: Saving debugging output
3078 File: m4.info, Node: Dumpdef, Next: Trace, Up: Debugging
3080 7.1 Displaying macro definitions
3081 ================================
3083 If you want to see what a name expands into, you can use the builtin
3086 -- Builtin: dumpdef ([NAMES...]
3087 Accepts any number of arguments. If called without any arguments,
3088 it displays the definitions of all known names, otherwise it
3089 displays the definitions of the NAMES given. The output is printed
3090 to the current debug file (usually standard error), and is sorted
3091 by name. If an unknown name is encountered, a warning is printed.
3093 The expansion of 'dumpdef' is void.
3096 define(`foo', `Hello world.')
3103 The last example shows how builtin macros definitions are displayed.
3104 The definition that is dumped corresponds to what would occur if the
3105 macro were to be called at that point, even if other definitions are
3106 still live due to redefining a macro during argument collection.
3109 pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
3111 f(popdef(`f')dumpdef(`f'))
3113 f(popdef(`f')dumpdef(`f'))
3114 error->m4:stdin:3: undefined macro `f'
3117 *Note Debug Levels::, for information on controlling the details of
3121 File: m4.info, Node: Trace, Next: Debug Levels, Prev: Dumpdef, Up: Debugging
3123 7.2 Tracing macro calls
3124 =======================
3126 It is possible to trace macro calls and expansions through the builtins
3127 'traceon' and 'traceoff':
3129 -- Builtin: traceon ([NAMES...]
3130 -- Builtin: traceoff ([NAMES...]
3131 When called without any arguments, 'traceon' and 'traceoff' will
3132 turn tracing on and off, respectively, for all currently defined
3135 When called with arguments, only the macros listed in NAMES are
3136 affected, whether or not they are currently defined.
3138 The expansion of 'traceon' and 'traceoff' is void.
3140 Whenever a traced macro is called and the arguments have been
3141 collected, the call is displayed. If the expansion of the macro call is
3142 not void, the expansion can be displayed after the call. The output is
3143 printed to the current debug file (defaulting to standard error, *note
3147 define(`foo', `Hello World.')
3149 define(`echo', `$@')
3151 traceon(`foo', `echo')
3154 error->m4trace: -1- foo -> `Hello World.'
3156 echo(`gnus', `and gnats')
3157 error->m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
3160 The number between dashes is the depth of the expansion. It is one
3161 most of the time, signifying an expansion at the outermost level, but it
3162 increases when macro arguments contain unquoted macro calls. The
3163 maximum number that will appear between dashes is controlled by the
3164 option '--nesting-limit' (or '-L', *note Invoking m4: Limits control.).
3165 Additionally, the option '--trace' (or '-t') can be used to invoke
3166 'traceon(NAME)' before parsing input.
3170 error->m4trace: -1- ifelse
3172 ifelse(ifelse(ifelse(`three levels')))
3173 error->m4trace: -3- ifelse
3174 error->m4trace: -2- ifelse
3175 error->m4trace: -1- ifelse
3177 ifelse(ifelse(ifelse(ifelse(`four levels'))))
3178 error->m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it
3180 Tracing by name is an attribute that is preserved whether the macro
3181 is defined or not. This allows the selection of macros to trace before
3182 those macros are defined.
3193 define(`foo', `bar')
3196 error->m4trace: -1- foo -> `bar'
3200 ifdef(`foo', `yes', `no')
3203 error->m4:stdin:9: undefined macro `foo'
3205 define(`foo', `blah')
3208 error->m4trace: -1- foo -> `blah'
3215 Tracing even works on builtins. However, 'defn' (*note Defn::) does
3216 not transfer tracing status.
3222 error->m4trace: -1- traceon(`traceoff')
3224 traceoff(`traceoff')
3225 error->m4trace: -1- traceoff(`traceoff')
3229 traceon(`eval', `m4_divnum')
3231 define(`m4_eval', defn(`eval'))
3233 define(`m4_divnum', defn(`divnum'))
3236 error->m4trace: -1- eval(`0') -> `0'
3239 error->m4trace: -2- m4_divnum -> `0'
3242 *Note Debug Levels::, for information on controlling the details of
3243 the display. The format of the trace output is not specified by POSIX,
3244 and varies between implementations of 'm4'.
3247 File: m4.info, Node: Debug Levels, Next: Debug Output, Prev: Trace, Up: Debugging
3249 7.3 Controlling debugging output
3250 ================================
3252 The '-d' option to 'm4' (or '--debug', *note Invoking m4: Debugging
3253 options.) controls the amount of details presented in three categories
3254 of output. Trace output is requested by 'traceon' (*note Trace::), and
3255 each line is prefixed by 'm4trace:' in relation to a macro invocation.
3256 Debug output tracks useful events not associated with a macro
3257 invocation, and each line is prefixed by 'm4debug:'. Finally, 'dumpdef'
3258 (*note Dumpdef::) output is affected, with no prefix added to the output
3261 The FLAGS following the option can be one or more of the following:
3264 In trace output, show the actual arguments that were collected
3265 before invoking the macro. This applies to all macro calls if the
3266 't' flag is used, otherwise only the macros covered by calls of
3267 'traceon'. Arguments are subject to length truncation specified by
3268 the command line option '--arglength' (or '-l').
3271 In trace output, show several trace lines for each macro call. A
3272 line is shown when the macro is seen, but before the arguments are
3273 collected; a second line when the arguments have been collected and
3274 a third line after the call has completed.
3277 In trace output, show the expansion of each macro call, if it is
3278 not void. This applies to all macro calls if the 't' flag is used,
3279 otherwise only the macros covered by calls of 'traceon'. The
3280 expansion is subject to length truncation specified by the command
3281 line option '--arglength' (or '-l').
3284 In debug and trace output, include the name of the current input
3285 file in the output line.
3288 In debug output, print a message each time the current input file
3292 In debug and trace output, include the current input line number in
3296 In debug output, print a message when a named file is found through
3297 the path search mechanism (*note Search Path::), giving the actual
3301 In trace and dumpdef output, quote actual arguments and macro
3302 expansions in the display with the current quotes. This is useful
3303 in connection with the 'a' and 'e' flags above.
3306 In trace output, trace all macro calls made in this invocation of
3307 'm4', regardless of the settings of 'traceon'.
3310 In trace output, add a unique 'macro call id' to each line of the
3311 trace output. This is useful in connection with the 'c' flag
3315 A shorthand for all of the above flags.
3317 If no flags are specified with the '-d' option, the default is 'aeq'.
3318 The examples throughout this manual assume the default flags.
3320 There is a builtin macro 'debugmode', which allows on-the-fly control
3321 of the debugging output format:
3323 -- Builtin: debugmode ([FLAGS]
3324 The argument FLAGS should be a subset of the letters listed above.
3325 As special cases, if the argument starts with a '+', the flags are
3326 added to the current debug flags, and if it starts with a '-', they
3327 are removed. If no argument is present, all debugging flags are
3328 cleared (as if no '-d' was given), and with an empty argument the
3329 flags are reset to the default of 'aeq'.
3331 The expansion of 'debugmode' is void.
3334 define(`foo', `FOO')
3341 error->m4trace: -1- foo -> `FOO'
3346 error->m4trace: -1- foo
3351 error->m4trace:8: -1- foo
3354 The following example demonstrates the behavior of length truncation,
3355 when specified on the command line. Note that each argument and the
3356 final result are individually truncated. Also, the special tokens for
3357 builtin functions are not truncated.
3360 define(`echo', `$@')debugmode(`+t')
3362 echo(`1', `long string')
3363 error->m4trace: -1- echo(`1', `long s...') -> ``1',`l...'
3365 indir(`echo', defn(`changequote'))
3366 error->m4trace: -2- defn(`change...')
3367 error->m4trace: -1- indir(`echo', <changequote>) -> ``''
3370 This example shows the effects of the debug flags that are not
3371 related to macro tracing.
3373 $ m4 -dip -I examples
3374 error->m4debug: input read from stdin
3376 error->m4debug: path search for `foo' found `examples/foo'
3377 error->m4debug: input read from examples/foo
3379 error->m4debug: input reverted to stdin, line 1
3381 error->m4debug: input exhausted
3384 File: m4.info, Node: Debug Output, Prev: Debug Levels, Up: Debugging
3386 7.4 Saving debugging output
3387 ===========================
3389 Debug and tracing output can be redirected to files using either the
3390 '--debugfile' option to 'm4' (*note Invoking m4: Debugging options.), or
3391 with the builtin macro 'debugfile':
3393 -- Builtin: debugfile ([FILE]
3394 Sends all further debug and trace output to FILE, opened in append
3395 mode. If FILE is the empty string, debug and trace output are
3396 discarded. If 'debugfile' is called without any arguments, debug
3397 and trace output are sent to standard error. This does not affect
3398 warnings, error messages, or 'errprint' output, which are always
3399 sent to standard error. If FILE cannot be opened, the current
3400 debug file is unchanged, and an error is issued.
3402 The expansion of 'debugfile' is void.
3408 error->m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored
3409 error->m4trace: -1- divnum(`extra') -> `0'
3414 error->m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored
3419 error->m4trace: -1- divnum -> `0'
3423 File: m4.info, Node: Input Control, Next: File Inclusion, Prev: Debugging, Up: Top
3428 This chapter describes various builtin macros for controlling the input
3433 * Dnl:: Deleting whitespace in input
3434 * Changequote:: Changing the quote characters
3435 * Changecom:: Changing the comment delimiters
3436 * Changeword:: Changing the lexical structure of words
3437 * M4wrap:: Saving text until end of input
3440 File: m4.info, Node: Dnl, Next: Changequote, Up: Input Control
3442 8.1 Deleting whitespace in input
3443 ================================
3445 The builtin 'dnl' stands for "Discard to Next Line":
3448 All characters, up to and including the next newline, are discarded
3449 without performing any macro expansion. A warning is issued if the
3450 end of the file is encountered without a newline.
3452 The expansion of 'dnl' is void.
3454 It is often used in connection with 'define', to remove the newline
3455 that follows the call to 'define'. Thus
3457 define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
3461 The input up to and including the next newline is discarded, as
3462 opposed to the way comments are treated (*note Comments::).
3464 Usually, 'dnl' is immediately followed by an end of line or some
3465 other whitespace. GNU 'm4' will produce a warning diagnostic if 'dnl'
3466 is followed by an open parenthesis. In this case, 'dnl' will collect
3467 and process all arguments, looking for a matching close parenthesis.
3468 All predictable side effects resulting from this collection will take
3469 place. 'dnl' will return no output. The input following the matching
3470 close parenthesis up to and including the next newline, on whatever line
3471 containing it, will still be discarded.
3473 dnl(`args are ignored, but side effects occur',
3474 define(`foo', `like this')) while this text is ignored: undefine(`foo')
3475 error->m4:stdin:1: Warning: excess arguments to builtin `dnl' ignored
3476 See how `foo' was defined, foo?
3477 =>See how foo was defined, like this?
3479 If the end of file is encountered without a newline character, a
3480 warning is issued and dnl stops consuming input.
3482 m4wrap(`m4wrap(`2 hi
3488 error->m4:stdin:1: Warning: end of file treated as newline
3492 File: m4.info, Node: Changequote, Next: Changecom, Prev: Dnl, Up: Input Control
3494 8.2 Changing the quote characters
3495 =================================
3497 The default quote delimiters can be changed with the builtin
3500 -- Builtin: changequote ([START = '`']
3501 This sets START as the new begin-quote delimiter and END as the new
3502 end-quote delimiter. If both arguments are missing, the default
3503 quotes ('`' and ''') are used. If START is void, then quoting is
3504 disabled. Otherwise, if END is missing or void, the default
3505 end-quote delimiter (''') is used. The quote delimiters can be of
3508 The expansion of 'changequote' is void.
3510 changequote(`[', `]')
3512 define([foo], [Macro [foo].])
3517 The quotation strings can safely contain eight-bit characters. If no
3518 single character is appropriate, START and END can be of any length.
3519 Other implementations cap the delimiter length to five characters, but
3520 GNU has no inherent limit.
3522 changequote(`[[[', `]]]')
3524 define([[[foo]]], [[[Macro [[[[[foo]]]]].]]])
3529 Calling 'changequote' with START as the empty string will effectively
3530 disable the quoting mechanism, leaving no way to quote text. However,
3531 using an empty string is not portable, as some other implementations of
3532 'm4' revert to the default quoting, while others preserve the prior
3533 non-empty delimiter. If START is not empty, then an empty END will use
3534 the default end-quote delimiter of ''', as otherwise, it would be
3535 impossible to end a quoted string. Again, this is not portable, as some
3536 other 'm4' implementations reuse START as the end-quote delimiter, while
3537 others preserve the previous non-empty value. Omitting both arguments
3538 restores the default begin-quote and end-quote delimiters; fortunately
3539 this behavior is portable to all implementations of 'm4'.
3541 define(`foo', `Macro `FOO'.')
3554 There is no way in 'm4' to quote a string containing an unmatched
3555 begin-quote, except using 'changequote' to change the current quotes.
3557 If the quotes should be changed from, say, '[' to '[[', temporary
3558 quote characters have to be defined. To achieve this, two calls of
3559 'changequote' must be made, one for the temporary quotes and one for the
3562 Macros are recognized in preference to the begin-quote string, so if
3563 a prefix of START can be recognized as part of a potential macro name,
3564 the quoting mechanism is effectively disabled. Unless you use
3565 'changeword' (*note Changeword::), this means that START should not
3566 begin with a letter, digit, or '_' (underscore). However, even though
3567 quoted strings are not recognized, the quote characters can still be
3568 discerned in macro expansion and in trace output.
3570 define(`echo', `$@')
3574 changequote(`q', `Q')
3582 changequote(`-', `EOF')
3588 changequote(`1', `2')
3595 Quotes are recognized in preference to argument collection. In
3596 particular, if START is a single '(', then argument collection is
3597 effectively disabled. For portability with other implementations, it is
3598 a good idea to avoid '(', ',', and ')' as the first character in START.
3600 define(`echo', `$#:$@:')
3604 changequote(`(',`)')
3610 changequote(`((', `))')
3618 changequote(`,', `)')
3623 However, if you are not worried about portability, using '(' and ')'
3624 as quoting characters has an interesting property--you can use it to
3625 compute a quoted string containing the expansion of any quoted text, as
3626 long as the expansion results in both balanced quotes and balanced
3627 parentheses. The trick is realizing 'expand' uses '$1' unquoted, to
3628 trigger its expansion using the normal quoting characters, but uses
3629 extra parentheses to group unquoted commas that occur in the expansion
3630 without consuming whitespace following those commas. Then '_expand'
3631 uses 'changequote' to convert the extra parentheses back into quoting
3632 characters. Note that it takes two more 'changequote' invocations to
3633 restore the original quotes. Contrast the behavior on whitespace when
3634 using '$*', via 'quote', to attempt the same task.
3636 changequote(`[', `]')dnl
3637 define([a], [1, (b)])dnl
3639 define([quote], [[$*]])dnl
3640 define([expand], [_$0(($1))])dnl
3642 [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl
3643 expand([a, a, [a, a], [[a, a]]])
3644 =>1, (2), 1, (2), a, a, [a, a]
3645 quote(a, a, [a, a], [[a, a]])
3646 =>1,(2),1,(2),a, a,[a, a]
3648 If END is a prefix of START, the end-quote will be recognized in
3649 preference to a nested begin-quote. In particular, changing the quotes
3650 to have the same string for START and END disables nesting of quotes.
3651 When quote nesting is disabled, it is impossible to double-quote strings
3652 across macro expansions, so using the same string is not done very
3657 changequote(`""', `"')
3669 changequote(`"', `"')
3674 It is an error if the end of file occurs within a quoted string.
3680 error->m4:stdin:2: ERROR: end of file in string
3682 ifelse(`dangling quote
3684 error->m4:stdin:1: ERROR: end of file in string
3687 File: m4.info, Node: Changecom, Next: Changeword, Prev: Changequote, Up: Input Control
3689 8.3 Changing the comment delimiters
3690 ===================================
3692 The default comment delimiters can be changed with the builtin macro
3695 -- Builtin: changecom ([START]
3696 This sets START as the new begin-comment delimiter and END as the
3697 new end-comment delimiter. If both arguments are missing, or START
3698 is void, then comments are disabled. Otherwise, if END is missing
3699 or void, the default end-comment delimiter of newline is used. The
3700 comment delimiters can be of any length.
3702 The expansion of 'changecom' is void.
3704 define(`comment', `COMMENT')
3707 =># A normal comment
3708 changecom(`/*', `*/')
3710 # Not a comment anymore
3711 =># Not a COMMENT anymore
3712 But: /* this is a comment now */ while this is not a comment
3713 =>But: /* this is a comment now */ while this is not a COMMENT
3715 Note how comments are copied to the output, much as if they were
3716 quoted strings. If you want the text inside a comment expanded, quote
3717 the begin-comment delimiter.
3719 Calling 'changecom' without any arguments, or with START as the empty
3720 string, will effectively disable the commenting mechanism. To restore
3721 the original comment start of '#', you must explicitly ask for it. If
3722 START is not empty, then an empty END will use the default end-comment
3723 delimiter of newline, as otherwise, it would be impossible to end a
3724 comment. However, this is not portable, as some other 'm4'
3725 implementations preserve the previous non-empty delimiters instead.
3727 define(`comment', `COMMENT')
3731 # Not a comment anymore
3732 =># Not a COMMENT anymore
3738 The comment strings can safely contain eight-bit characters. If no
3739 single character is appropriate, START and END can be of any length.
3740 Other implementations cap the delimiter length to five characters, but
3741 GNU has no inherent limit.
3743 Comments are recognized in preference to macros. However, this is
3744 not compatible with other implementations, where macros and even quoting
3745 takes precedence over comments, so it may change in a future release.
3746 For portability, this means that START should not begin with a letter,
3747 digit, or '_' (underscore), and that neither the start-quote nor the
3748 start-comment string should be a prefix of the other.
3752 define(`hi1hi2', `hello')
3765 Comments are recognized in preference to argument collection. In
3766 particular, if START is a single '(', then argument collection is
3767 effectively disabled. For portability with other implementations, it is
3768 a good idea to avoid '(', ',', and ')' as the first character in START.
3770 define(`echo', `$#:$*:$@:')
3780 changecom(`((', `))')
3789 =>1:HI,hi)bye:HI,hi)bye:
3793 =>3:HI,,HI,HI:HI,,`'hi,HI:
3794 echo(hi,`,`'hi',hi`'changecom(`,,', `hi'))
3795 =>3:HI,,`'hi,HI:HI,,`'hi,HI:
3797 It is an error if the end of file occurs within a comment.
3799 changecom(`/*', `*/')
3803 error->m4:stdin:2: ERROR: end of file in comment
3806 File: m4.info, Node: Changeword, Next: M4wrap, Prev: Changecom, Up: Input Control
3808 8.4 Changing the lexical structure of words
3809 ===========================================
3811 The macro 'changeword' and all associated functionality is
3812 experimental. It is only available if the '--enable-changeword'
3813 option was given to 'configure', at GNU 'm4' installation time.
3814 The functionality will go away in the future, to be replaced by
3815 other new features that are more efficient at providing the same
3816 capabilities. _Do not rely on it_. Please direct your comments
3817 about it the same way you would do for bugs.
3819 A file being processed by 'm4' is split into quoted strings, words
3820 (potential macro names) and simple tokens (any other single character).
3821 Initially a word is defined by the following regular expression:
3823 [_a-zA-Z][_a-zA-Z0-9]*
3825 Using 'changeword', you can change this regular expression:
3827 -- Optional builtin: changeword (REGEX)
3828 Changes the regular expression for recognizing macro names to be
3829 REGEX. If REGEX is empty, use '[_a-zA-Z][_a-zA-Z0-9]*'. REGEX
3830 must obey the constraint that every prefix of the desired final
3831 pattern is also accepted by the regular expression. If REGEX
3832 contains grouping parentheses, the macro invoked is the portion
3833 that matched the first group, rather than the entire matching
3836 The expansion of 'changeword' is void. The macro 'changeword' is
3837 recognized only with parameters.
3839 Relaxing the lexical rules of 'm4' might be useful (for example) if
3840 you wanted to apply translations to a file of numbers:
3842 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3844 changeword(`[_a-zA-Z0-9]+')
3849 Tightening the lexical rules is less useful, because it will
3850 generally make some of the builtins unavailable. You could use it to
3851 prevent accidental call of builtins, for example:
3853 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3855 define(`_indir', defn(`indir'))
3857 changeword(`_[_a-zA-Z0-9]*')
3861 _indir(`esyscmd', `echo hi')
3865 Because 'm4' constructs its words a character at a time, there is a
3866 restriction on the regular expressions that may be passed to
3867 'changeword'. This is that if your regular expression accepts 'foo', it
3868 must also accept 'f' and 'fo'.
3870 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3876 dnl This example wants to recognize changeword, dnl, and `foo\n'.
3877 dnl First, we check that our regexp will match.
3878 regexp(`changeword', `[cd][a-z]*\|foo[
3882 ', `[cd][a-z]*\|foo[
3885 regexp(`f', `[cd][a-z]*\|foo[
3890 changeword(`[cd][a-z]*\|foo[
3893 dnl Even though `foo\n' matches, we forgot to allow `f'.
3896 changeword(`[cd][a-z]*\|fo*[
3899 dnl Now we can call `foo\n'.
3903 'changeword' has another function. If the regular expression
3904 supplied contains any grouped subexpressions, then text outside the
3905 first of these is discarded before symbol lookup. So:
3907 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3910 `errprint(` skipping: syscmd does not have unix semantics
3912 changecom(`/*', `*/')dnl
3913 define(`foo', `bar')dnl
3914 changeword(`#\([_a-zA-Z0-9]*\)')
3916 #esyscmd(`echo foo \#foo')
3920 'm4' now requires a '#' mark at the beginning of every macro
3921 invocation, so one can use 'm4' to preprocess plain text without losing
3922 various words like 'divert'.
3924 In 'm4', macro substitution is based on text, while in TeX, it is
3925 based on tokens. 'changeword' can throw this difference into relief.
3926 For example, here is the same idea represented in TeX and 'm4'. First,
3929 \def\a{\message{Hello}}
3936 Then, the 'm4' version:
3938 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3940 define(`a', `errprint(`Hello')')dnl
3941 changeword(`@\([_a-zA-Z0-9]*\)')
3946 In the TeX example, the first line defines a macro 'a' to print the
3947 message 'Hello'. The second line defines <@> to be usable instead of
3948 <\> as an escape character. The third line defines <\> to be a normal
3949 printing character, not an escape. The fourth line invokes the macro
3950 'a'. So, when TeX is run on this file, it displays the message 'Hello'.
3952 When the 'm4' example is passed through 'm4', it outputs
3953 'errprint(Hello)'. The reason for this is that TeX does lexical
3954 analysis of macro definition when the macro is _defined_. 'm4' just
3955 stores the text, postponing the lexical analysis until the macro is
3958 You should note that using 'changeword' will slow 'm4' down by a
3959 factor of about seven, once it is changed to something other than the
3960 default regular expression. You can invoke 'changeword' with the empty
3961 string to restore the default word definition, and regain the parsing
3965 File: m4.info, Node: M4wrap, Prev: Changeword, Up: Input Control
3967 8.5 Saving text until end of input
3968 ==================================
3970 It is possible to 'save' some text until the end of the normal input has
3971 been seen. Text can be saved, to be read again by 'm4' when the normal
3972 input has been exhausted. This feature is normally used to initiate
3973 cleanup actions before normal exit, e.g., deleting temporary files.
3975 To save input text, use the builtin 'm4wrap':
3977 -- Builtin: m4wrap (STRING, ...)
3978 Stores STRING in a safe place, to be reread when end of input is
3979 reached. As a GNU extension, additional arguments are concatenated
3980 with a space to the STRING.
3982 The expansion of 'm4wrap' is void. The macro 'm4wrap' is
3983 recognized only with parameters.
3985 define(`cleanup', `This is the `cleanup' action.
3990 This is the first and last normal input line.
3991 =>This is the first and last normal input line.
3993 =>This is the cleanup action.
3995 The saved input is only reread when the end of normal input is seen,
3996 and not if 'm4exit' is used to exit 'm4'.
3998 It is safe to call 'm4wrap' from saved text, but then the order in
3999 which the saved text is reread is undefined. If 'm4wrap' is not used
4000 recursively, the saved pieces of text are reread in the opposite order
4001 in which they were saved (LIFO--last in, first out). However, this
4002 behavior is likely to change in a future release, to match POSIX, so you
4003 should not depend on this order.
4005 It is possible to emulate POSIX behavior even with older versions of
4006 GNU M4 by including the file 'm4-1.4.17/examples/wrapfifo.m4' from the
4010 undivert(`wrapfifo.m4')dnl
4011 =>dnl Redefine m4wrap to have FIFO semantics.
4012 =>define(`_m4wrap_level', `0')dnl
4014 =>`ifdef(`m4wrap'_m4wrap_level,
4015 => `define(`m4wrap'_m4wrap_level,
4016 => defn(`m4wrap'_m4wrap_level)`$1')',
4017 => `builtin(`m4wrap', `define(`_m4wrap_level',
4018 => incr(_m4wrap_level))dnl
4019 =>m4wrap'_m4wrap_level)dnl
4020 =>define(`m4wrap'_m4wrap_level, `$1')')')dnl
4021 include(`wrapfifo.m4')
4023 m4wrap(`a`'m4wrap(`c
4024 ', `d')')m4wrap(`b')
4029 It is likewise possible to emulate LIFO behavior without resorting to
4030 the GNU M4 extension of 'builtin', by including the file
4031 'm4-1.4.17/examples/wraplifo.m4' from the distribution. (Unfortunately,
4032 both examples shown here share some subtle bugs. See if you can find
4033 and correct them; or *note Answers: Improved m4wrap.).
4036 undivert(`wraplifo.m4')dnl
4037 =>dnl Redefine m4wrap to have LIFO semantics.
4038 =>define(`_m4wrap_level', `0')dnl
4039 =>define(`_m4wrap', defn(`m4wrap'))dnl
4041 =>`ifdef(`m4wrap'_m4wrap_level,
4042 => `define(`m4wrap'_m4wrap_level,
4043 => `$1'defn(`m4wrap'_m4wrap_level))',
4044 => `_m4wrap(`define(`_m4wrap_level', incr(_m4wrap_level))dnl
4045 =>m4wrap'_m4wrap_level)dnl
4046 =>define(`m4wrap'_m4wrap_level, `$1')')')dnl
4047 include(`wraplifo.m4')
4049 m4wrap(`a`'m4wrap(`c
4050 ', `d')')m4wrap(`b')
4055 Here is an example of implementing a factorial function using
4058 define(`f', `ifelse(`$1', `0', `Answer: 0!=1
4059 ', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1')
4060 ', `m4wrap(`f(decr(`$1'), `$2$1*')')')')
4065 =>Answer: 10*9*8*7*6*5*4*3*2*1=3628800
4067 Invocations of 'm4wrap' at the same recursion level are concatenated
4068 and rescanned as usual:
4073 m4wrap(`a')m4wrap(`a')
4078 however, the transition between recursion levels behaves like an end of
4079 file condition between two input files.
4081 m4wrap(`m4wrap(`)')len(abc')
4084 error->m4:stdin:1: ERROR: end of file in argument list
4087 File: m4.info, Node: File Inclusion, Next: Diversions, Prev: Input Control, Up: Top
4092 'm4' allows you to include named files at any point in the input.
4096 * Include:: Including named files
4097 * Search Path:: Searching for include files
4100 File: m4.info, Node: Include, Next: Search Path, Up: File Inclusion
4102 9.1 Including named files
4103 =========================
4105 There are two builtin macros in 'm4' for including files:
4107 -- Builtin: include (FILE)
4108 -- Builtin: sinclude (FILE)
4109 Both macros cause the file named FILE to be read by 'm4'. When the
4110 end of the file is reached, input is resumed from the previous
4113 The expansion of 'include' and 'sinclude' is therefore the contents
4116 If FILE does not exist, is a directory, or cannot otherwise be
4117 read, the expansion is void, and 'include' will fail with an error
4118 while 'sinclude' is silent. The empty string counts as a file that
4121 The macros 'include' and 'sinclude' are recognized only with
4125 error->m4:stdin:1: cannot open `none': No such file or directory
4128 error->m4:stdin:2: cannot open `': No such file or directory
4135 The rest of this section assumes that 'm4' is invoked with the '-I'
4136 option (*note Invoking m4: Preprocessor features.) pointing to the
4137 'm4-1.4.17/examples' directory shipped as part of the GNU 'm4' package.
4138 The file 'm4-1.4.17/examples/incl.m4' in the distribution contains the
4141 $ cat examples/incl.m4
4142 =>Include file start
4146 Normally file inclusion is used to insert the contents of a file into
4147 the input stream. The contents of the file will be read by 'm4' and
4148 macro calls in the file will be expanded:
4151 define(`foo', `FOO')
4154 =>Include file start
4159 The fact that 'include' and 'sinclude' expand to the contents of the
4160 file can be used to define macros that operate on entire files. Here is
4161 an example, which defines 'bar' to expand to the contents of 'incl.m4':
4164 define(`bar', include(`incl.m4'))
4166 This is `bar': >>bar<<
4167 =>This is bar: >>Include file start
4172 This use of 'include' is not trivial, though, as files can contain
4173 quotes, commas, and parentheses, which can interfere with the way the
4174 'm4' parser works. GNU 'm4' seamlessly concatenates the file contents
4175 with the next character, even if the included file ended in the middle
4176 of a comment, string, or macro call. These conditions are only treated
4177 as end of file errors if specified as input files on the command line.
4179 In GNU 'm4', an alternative method of reading files is using
4180 'undivert' (*note Undivert::) on a named file.
4183 File: m4.info, Node: Search Path, Prev: Include, Up: File Inclusion
4185 9.2 Searching for include files
4186 ===============================
4188 GNU 'm4' allows included files to be found in other directories than the
4189 current working directory.
4191 If the '--prepend-include' or '-B' command-line option was provided
4192 (*note Invoking m4: Preprocessor features.), those directories are
4193 searched first, in reverse order that those options were listed on the
4194 command line. Then 'm4' looks in the current working directory. Next
4195 comes the directories specified with the '--include' or '-I' option, in
4196 the order found on the command line. Finally, if the 'M4PATH'
4197 environment variable is set, it is expected to contain a colon-separated
4198 list of directories, which will be searched in order.
4200 If the automatic search for include-files causes trouble, the 'p'
4201 debug flag (*note Debug Levels::) can help isolate the problem.
4204 File: m4.info, Node: Diversions, Next: Text handling, Prev: File Inclusion, Up: Top
4206 10 Diverting and undiverting output
4207 ***********************************
4209 Diversions are a way of temporarily saving output. The output of 'm4'
4210 can at any time be diverted to a temporary file, and be reinserted into
4211 the output stream, "undiverted", again at a later time.
4213 Numbered diversions are counted from 0 upwards, diversion number 0
4214 being the normal output stream. GNU 'm4' tries to keep diversions in
4215 memory. However, there is a limit to the overall memory usable by all
4216 diversions taken together (512K, currently). When this maximum is about
4217 to be exceeded, a temporary file is opened to receive the contents of
4218 the biggest diversion still in memory, freeing this memory for other
4219 diversions. When creating the temporary file, 'm4' honors the value of
4220 the environment variable 'TMPDIR', and falls back to '/tmp'. Thus, the
4221 amount of available disk space provides the only real limit on the
4222 number and aggregate size of diversions.
4224 Diversions make it possible to generate output in a different order
4225 than the input was read. It is possible to implement topological
4226 sorting dependencies. For example, GNU Autoconf makes use of diversions
4227 under the hood to ensure that the expansion of a prerequisite macro
4228 appears in the output prior to the expansion of a dependent macro,
4229 regardless of which order the two macros were invoked in the user's
4234 * Divert:: Diverting output
4235 * Undivert:: Undiverting output
4236 * Divnum:: Diversion numbers
4237 * Cleardivert:: Discarding diverted text
4240 File: m4.info, Node: Divert, Next: Undivert, Up: Diversions
4242 10.1 Diverting output
4243 =====================
4245 Output is diverted using 'divert':
4247 -- Builtin: divert ([NUMBER = '0']
4248 The current diversion is changed to NUMBER. If NUMBER is left out
4249 or empty, it is assumed to be zero. If NUMBER cannot be parsed,
4250 the diversion is unchanged.
4252 The expansion of 'divert' is void.
4254 When all the 'm4' input will have been processed, all existing
4255 diversions are automatically undiverted, in numerical order.
4258 This text is diverted.
4261 This text is not diverted.
4262 =>This text is not diverted.
4265 =>This text is diverted.
4267 Several calls of 'divert' with the same argument do not overwrite the
4268 previous diverted text, but append to it. Diversions are printed after
4269 any wrapped text is expanded.
4271 define(`text', `TEXT')
4273 divert(`1')`diverted text.'
4276 m4wrap(`Wrapped text precedes ')
4279 =>Wrapped TEXT precedes diverted text.
4281 If output is diverted to a negative diversion, it is simply
4282 discarded. This can be used to suppress unwanted output. A common
4283 example of unwanted output is the trailing newlines after macro
4284 definitions. Here is a common programming idiom in 'm4' for avoiding
4288 define(`foo', `Macro `foo'.')
4289 define(`bar', `Macro `bar'.')
4293 Traditional implementations only supported ten diversions. But as a
4294 GNU extension, diversion numbers can be as large as positive integers
4295 will allow, rather than treating a multi-digit diversion number as a
4296 request to discard text.
4298 divert(eval(`1<<28'))world
4304 Note that 'divert' is an English word, but also an active macro
4305 without arguments. When processing plain text, the word might appear in
4306 normal text and be unintentionally swallowed as a macro invocation. One
4307 way to avoid this is to use the '-P' option to rename all builtins
4308 (*note Invoking m4: Operation modes.). Another is to write a wrapper
4309 that requires a parameter to be recognized.
4311 We decided to divert the stream for irrigation.
4312 =>We decided to the stream for irrigation.
4313 define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@)')')
4319 We decided to divert the stream for irrigation.
4320 =>We decided to divert the stream for irrigation.
4323 File: m4.info, Node: Undivert, Next: Divnum, Prev: Divert, Up: Diversions
4325 10.2 Undiverting output
4326 =======================
4328 Diverted text can be undiverted explicitly using the builtin 'undivert':
4330 -- Builtin: undivert ([DIVERSIONS...]
4331 Undiverts the numeric DIVERSIONS given by the arguments, in the
4332 order given. If no arguments are supplied, all diversions are
4333 undiverted, in numerical order.
4335 As a GNU extension, DIVERSIONS may contain non-numeric strings,
4336 which are treated as the names of files to copy into the output
4337 without expansion. A warning is issued if a file could not be
4340 The expansion of 'undivert' is void.
4343 This text is diverted.
4346 This text is not diverted.
4347 =>This text is not diverted.
4350 =>This text is diverted.
4353 Notice the last two blank lines. One of them comes from the newline
4354 following 'undivert', the other from the newline that followed the
4355 'divert'! A diversion often starts with a blank line like this.
4357 When diverted text is undiverted, it is _not_ reread by 'm4', but
4358 rather copied directly to the current output, and it is therefore not an
4359 error to undivert into a diversion. Undiverting the empty string is the
4360 same as specifying diversion 0; in either case nothing happens since the
4361 output has already been flushed.
4363 divert(`1')diverted text
4374 divert(`2')undivert(`1')diverted text`'divert
4382 When a diversion has been undiverted, the diverted text is discarded,
4383 and it is not possible to bring back diverted text more than once.
4386 This text is diverted first.
4387 divert(`0')undivert(`1')dnl
4389 =>This text is diverted first.
4393 This text is also diverted but not appended.
4394 divert(`0')undivert(`1')dnl
4396 =>This text is also diverted but not appended.
4398 Attempts to undivert the current diversion are silently ignored.
4399 Thus, when the current diversion is not 0, the current diversion does
4400 not get rearranged among the other diversions.
4405 divert(`2')undivert`'dnl
4406 divert`'undivert`'dnl
4411 GNU 'm4' allows named files to be undiverted. Given a non-numeric
4412 argument, the contents of the file named will be copied, uninterpreted,
4413 to the current output. This complements the builtin 'include' (*note
4414 Include::). To illustrate the difference, assume the file 'foo'
4422 define(`bar', `BAR')
4431 If the file is not found (or cannot be read), an error message is
4432 issued, and the expansion is void. It is possible to intermix files and
4435 divert(`1')diversion one
4436 divert(`2')undivert(`foo')dnl
4437 divert(`3')diversion three
4439 undivert(`1', `2', `foo', `3')dnl
4446 File: m4.info, Node: Divnum, Next: Cleardivert, Prev: Undivert, Up: Diversions
4448 10.3 Diversion numbers
4449 ======================
4451 The current diversion is tracked by the builtin 'divnum':
4454 Expands to the number of the current diversion.
4459 Diversion one: divnum
4461 Diversion two: divnum
4469 File: m4.info, Node: Cleardivert, Prev: Divnum, Up: Diversions
4471 10.4 Discarding diverted text
4472 =============================
4474 Often it is not known, when output is diverted, whether the diverted
4475 text is actually needed. Since all non-empty diversion are brought back
4476 on the main output stream when the end of input is seen, a method of
4477 discarding a diversion is needed. If all diversions should be
4478 discarded, the easiest is to end the input to 'm4' with 'divert(`-1')'
4479 followed by an explicit 'undivert':
4482 Diversion one: divnum
4484 Diversion two: divnum
4489 No output is produced at all.
4491 Clearing selected diversions can be done with the following macro:
4493 -- Composite: cleardivert ([DIVERSIONS...]
4494 Discard the contents of each of the listed numeric DIVERSIONS.
4496 define(`cleardivert',
4497 `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
4500 It is called just like 'undivert', but the effect is to clear the
4501 diversions, given by the arguments. (This macro has a nasty bug! You
4502 should try to see if you can find it and correct it; or *note Answers:
4503 Improved cleardivert.).
4506 File: m4.info, Node: Text handling, Next: Arithmetic, Prev: Diversions, Up: Top
4508 11 Macros for text handling
4509 ***************************
4511 There are a number of builtins in 'm4' for manipulating text in various
4512 ways, extracting substrings, searching, substituting, and so on.
4516 * Len:: Calculating length of strings
4517 * Index macro:: Searching for substrings
4518 * Regexp:: Searching for regular expressions
4519 * Substr:: Extracting substrings
4520 * Translit:: Translating characters
4521 * Patsubst:: Substituting text by regular expression
4522 * Format:: Formatting strings (printf-like)
4525 File: m4.info, Node: Len, Next: Index macro, Up: Text handling
4527 11.1 Calculating length of strings
4528 ==================================
4530 The length of a string can be calculated by 'len':
4532 -- Builtin: len (STRING)
4533 Expands to the length of STRING, as a decimal number.
4535 The macro 'len' is recognized only with parameters.
4543 File: m4.info, Node: Index macro, Next: Regexp, Prev: Len, Up: Text handling
4545 11.2 Searching for substrings
4546 =============================
4548 Searching for substrings is done with 'index':
4550 -- Builtin: index (STRING, SUBSTRING)
4551 Expands to the index of the first occurrence of SUBSTRING in
4552 STRING. The first character in STRING has index 0. If SUBSTRING
4553 does not occur in STRING, 'index' expands to '-1'.
4555 The macro 'index' is recognized only with parameters.
4557 index(`gnus, gnats, and armadillos', `nat')
4559 index(`gnus, gnats, and armadillos', `dag')
4562 Omitting SUBSTRING evokes a warning, but still produces output;
4563 contrast this with an empty SUBSTRING.
4566 error->m4:stdin:1: Warning: too few arguments to builtin `index'
4574 File: m4.info, Node: Regexp, Next: Substr, Prev: Index macro, Up: Text handling
4576 11.3 Searching for regular expressions
4577 ======================================
4579 Searching for regular expressions is done with the builtin 'regexp':
4581 -- Builtin: regexp (STRING, REGEXP, [REPLACEMENT]
4582 Searches for REGEXP in STRING. The syntax for regular expressions
4583 is the same as in GNU Emacs, which is similar to BRE, Basic Regular
4584 Expressions in POSIX. *Note Syntax of Regular Expressions:
4585 (emacs)Regexps. Support for ERE, Extended Regular Expressions is
4586 not available, but will be added in GNU M4 2.0.
4588 If REPLACEMENT is omitted, 'regexp' expands to the index of the
4589 first match of REGEXP in STRING. If REGEXP does not match anywhere
4590 in STRING, it expands to -1.
4592 If REPLACEMENT is supplied, and there was a match, 'regexp' changes
4593 the expansion to this argument, with '\N' substituted by the text
4594 matched by the Nth parenthesized sub-expression of REGEXP, up to
4595 nine sub-expressions. The escape '\&' is replaced by the text of
4596 the entire regular expression matched. For all other characters,
4597 '\' treats the next character literally. A warning is issued if
4598 there were fewer sub-expressions than the '\N' requested, or if
4599 there is a trailing '\'. If there was no match, 'regexp' expands
4600 to the empty string.
4602 The macro 'regexp' is recognized only with parameters.
4604 regexp(`GNUs not Unix', `\<[a-z]\w+')
4606 regexp(`GNUs not Unix', `\<Q\w*')
4608 regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
4609 =>*** Unix *** nix ***
4610 regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
4613 Here are some more examples on the handling of backslash:
4615 regexp(`abc', `\(b\)', `\\\10\a')
4617 regexp(`abc', `b', `\1\')
4618 error->m4:stdin:2: Warning: sub-expression 1 not present
4619 error->m4:stdin:2: Warning: trailing \ ignored in replacement
4621 regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6')
4622 error->m4:stdin:3: Warning: sub-expression 4 not present
4623 error->m4:stdin:3: Warning: sub-expression 5 not present
4624 error->m4:stdin:3: Warning: sub-expression 6 not present
4627 Omitting REGEXP evokes a warning, but still produces output; contrast
4628 this with an empty REGEXP argument.
4631 error->m4:stdin:1: Warning: too few arguments to builtin `regexp'
4635 regexp(`abc', `', `\\def')
4639 File: m4.info, Node: Substr, Next: Translit, Prev: Regexp, Up: Text handling
4641 11.4 Extracting substrings
4642 ==========================
4644 Substrings are extracted with 'substr':
4646 -- Builtin: substr (STRING, FROM, [LENGTH]
4647 Expands to the substring of STRING, which starts at index FROM, and
4648 extends for LENGTH characters, or to the end of STRING, if LENGTH
4649 is omitted. The starting index of a string is always 0. The
4650 expansion is empty if there is an error parsing FROM or LENGTH, if
4651 FROM is beyond the end of STRING, or if LENGTH is negative.
4653 The macro 'substr' is recognized only with parameters.
4655 substr(`gnus, gnats, and armadillos', `6')
4656 =>gnats, and armadillos
4657 substr(`gnus, gnats, and armadillos', `6', `5')
4660 Omitting FROM evokes a warning, but still produces output.
4663 error->m4:stdin:1: Warning: too few arguments to builtin `substr'
4666 error->m4:stdin:2: empty string treated as 0 in builtin `substr'
4670 File: m4.info, Node: Translit, Next: Patsubst, Prev: Substr, Up: Text handling
4672 11.5 Translating characters
4673 ===========================
4675 Character translation is done with 'translit':
4677 -- Builtin: translit (STRING, CHARS, [REPLACEMENT]
4678 Expands to STRING, with each character that occurs in CHARS
4679 translated into the character from REPLACEMENT with the same index.
4681 If REPLACEMENT is shorter than CHARS, the excess characters of
4682 CHARS are deleted from the expansion; if CHARS is shorter, the
4683 excess characters in REPLACEMENT are silently ignored. If
4684 REPLACEMENT is omitted, all characters in STRING that are present
4685 in CHARS are deleted from the expansion. If a character appears
4686 more than once in CHARS, only the first instance is used in making
4687 the translation. Only a single translation pass is made, even if
4688 characters in REPLACEMENT also appear in CHARS.
4690 As a GNU extension, both CHARS and REPLACEMENT can contain
4691 character-ranges, e.g., 'a-z' (meaning all lowercase letters) or
4692 '0-9' (meaning all digits). To include a dash '-' in CHARS or
4693 REPLACEMENT, place it first or last in the entire string, or as the
4694 last character of a range. Back-to-back ranges can share a common
4695 endpoint. It is not an error for the last character in the range
4696 to be 'larger' than the first. In that case, the range runs
4697 backwards, i.e., '9-0' means the string '9876543210'. The
4698 expansion of a range is dependent on the underlying encoding of
4699 characters, so using ranges is not always portable between
4702 The macro 'translit' is recognized only with parameters.
4704 translit(`GNUs not Unix', `A-Z')
4706 translit(`GNUs not Unix', `a-z', `A-Z')
4708 translit(`GNUs not Unix', `A-Z', `z-a')
4710 translit(`+,-12345', `+--1-5', `<;>a-c-a')
4712 translit(`abcdef', `aabdef', `bcged')
4715 In the ASCII encoding, the first example deletes all uppercase
4716 letters, the second converts lowercase to uppercase, and the third
4717 'mirrors' all uppercase letters, while converting them to lowercase.
4718 The two first cases are by far the most common, even though they are not
4719 portable to EBCDIC or other encodings. The fourth example shows a range
4720 ending in '-', as well as back-to-back ranges. The final example shows
4721 that 'a' is mapped to 'b', not 'c'; the resulting 'b' is not further
4722 remapped to 'g'; the 'd' and 'e' are swapped, and the 'f' is discarded.
4724 Omitting CHARS evokes a warning, but still produces output.
4727 error->m4:stdin:1: Warning: too few arguments to builtin `translit'
4731 File: m4.info, Node: Patsubst, Next: Format, Prev: Translit, Up: Text handling
4733 11.6 Substituting text by regular expression
4734 ============================================
4736 Global substitution in a string is done by 'patsubst':
4738 -- Builtin: patsubst (STRING, REGEXP, [REPLACEMENT]
4739 Searches STRING for matches of REGEXP, and substitutes REPLACEMENT
4740 for each match. The syntax for regular expressions is the same as
4741 in GNU Emacs (*note Regexp::).
4743 The parts of STRING that are not covered by any match of REGEXP are
4744 copied to the expansion. Whenever a match is found, the search
4745 proceeds from the end of the match, so a character from STRING will
4746 never be substituted twice. If REGEXP matches a string of zero
4747 length, the start position for the search is incremented, to avoid
4750 When a replacement is to be made, REPLACEMENT is inserted into the
4751 expansion, with '\N' substituted by the text matched by the Nth
4752 parenthesized sub-expression of PATSUBST, for up to nine
4753 sub-expressions. The escape '\&' is replaced by the text of the
4754 entire regular expression matched. For all other characters, '\'
4755 treats the next character literally. A warning is issued if there
4756 were fewer sub-expressions than the '\N' requested, or if there is
4759 The REPLACEMENT argument can be omitted, in which case the text
4760 matched by REGEXP is deleted.
4762 The macro 'patsubst' is recognized only with parameters.
4764 patsubst(`GNUs not Unix', `^', `OBS: ')
4765 =>OBS: GNUs not Unix
4766 patsubst(`GNUs not Unix', `\<', `OBS: ')
4767 =>OBS: GNUs OBS: not OBS: Unix
4768 patsubst(`GNUs not Unix', `\w*', `(\&)')
4769 =>(GNUs)() (not)() (Unix)()
4770 patsubst(`GNUs not Unix', `\w+', `(\&)')
4771 =>(GNUs) (not) (Unix)
4772 patsubst(`GNUs not Unix', `[A-Z][a-z]+')
4774 patsubst(`GNUs not Unix', `not', `NOT\')
4775 error->m4:stdin:6: Warning: trailing \ ignored in replacement
4778 Here is a slightly more realistic example, which capitalizes
4779 individual words or whole sentences, by substituting calls of the macros
4780 'upcase' and 'downcase' into the strings.
4782 -- Composite: upcase (TEXT)
4783 -- Composite: downcase (TEXT)
4784 -- Composite: capitalize (TEXT)
4785 Expand to TEXT, but with capitalization changed: 'upcase' changes
4786 all letters to upper case, 'downcase' changes all letters to lower
4787 case, and 'capitalize' changes the first character of each word to
4788 upper case and the remaining characters to lower case.
4790 First, an example of their usage, using implementations distributed
4791 in 'm4-1.4.17/examples/capitalize.m4'.
4794 include(`capitalize.m4')
4796 upcase(`GNUs not Unix')
4798 downcase(`GNUs not Unix')
4800 capitalize(`GNUs not Unix')
4803 Now for the implementation. There is a helper macro '_capitalize'
4804 which puts only its first word in mixed case. Then 'capitalize' merely
4805 parses out the words, and replaces them with an invocation of
4806 '_capitalize'. (As presented here, the 'capitalize' macro has some
4807 subtle flaws. You should try to see if you can find and correct them;
4808 or *note Answers: Improved capitalize.).
4811 undivert(`capitalize.m4')dnl
4815 =># capitalize(text)
4816 =># change case of text, simple version
4817 =>define(`upcase', `translit(`$*', `a-z', `A-Z')')
4818 =>define(`downcase', `translit(`$*', `A-Z', `a-z')')
4819 =>define(`_capitalize',
4820 => `regexp(`$1', `^\(\w\)\(\w*\)',
4821 => `upcase(`\1')`'downcase(`\2')')')
4822 =>define(`capitalize', `patsubst(`$1', `\w+', `_$0(`\&')')')
4825 While 'regexp' replaces the whole input with the replacement as soon
4826 as there is a match, 'patsubst' replaces each _occurrence_ of a match
4827 and preserves non-matching pieces:
4832 patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
4835 patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
4839 Omitting REGEXP evokes a warning, but still produces output; contrast
4840 this with an empty REGEXP argument.
4843 error->m4:stdin:1: Warning: too few arguments to builtin `patsubst'
4847 patsubst(`abc', `', `\\-')
4851 File: m4.info, Node: Format, Prev: Patsubst, Up: Text handling
4853 11.7 Formatting strings (printf-like)
4854 =====================================
4856 Formatted output can be made with 'format':
4858 -- Builtin: format (FORMAT-STRING, ...)
4859 Works much like the C function 'printf'. The first argument
4860 FORMAT-STRING can contain '%' specifications which are satisfied by
4861 additional arguments, and the expansion of 'format' is the
4864 The macro 'format' is recognized only with parameters.
4866 Its use is best described by a few examples:
4868 define(`foo', `The brown fox jumped over the lazy dog')
4870 format(`The string "%s" uses %d characters', foo, len(foo))
4871 =>The string "The brown fox jumped over the lazy dog" uses 38 characters
4872 format(`%*.*d', `-1', `-1', `1')
4874 format(`%.0f', `56789.9876')
4876 len(format(`%-*X', `5000', `1'))
4878 ifelse(format(`%010F', `infinity'), ` INF', `success',
4879 format(`%010F', `infinity'), ` INFINITY', `success',
4880 format(`%010F', `infinity'))
4882 ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success',
4883 format(`%.1A', `1.999'), `0X2.0P+0', `success',
4884 format(`%.1A', `1.999'))
4886 format(`%g', `0xa.P+1')
4889 Using the 'forloop' macro defined earlier (*note Forloop::), this
4890 example shows how 'format' can be used to produce tabular output.
4893 include(`forloop.m4')
4895 forloop(`i', `1', `10', `format(`%6d squared is %10d
4906 => 10 squared is 100
4909 The builtin 'format' is modeled after the ANSI C 'printf' function,
4910 and supports these '%' specifiers: 'c', 's', 'd', 'o', 'x', 'X', 'u',
4911 'a', 'A', 'e', 'E', 'f', 'F', 'g', 'G', and '%'; it supports field
4912 widths and precisions, and the flags '+', '-', ' ', '0', '#', and '''.
4913 For integer specifiers, the width modifiers 'hh', 'h', and 'l' are
4914 recognized, and for floating point specifiers, the width modifier 'l' is
4915 recognized. Items not yet supported include positional arguments, the
4916 'n', 'p', 'S', and 'C' specifiers, the 'z', 't', 'j', 'L' and 'll'
4917 modifiers, and any platform extensions available in the native 'printf'.
4918 For more details on the functioning of 'printf', see the C Library
4919 Manual, or the POSIX specification (for example, '%a' is supported even
4920 on platforms that haven't yet implemented C99 hexadecimal floating point
4923 Unrecognized specifiers result in a warning. It is anticipated that
4924 a future release of GNU 'm4' will support more specifiers, and give
4925 better warnings when various problems such as overflow are encountered.
4926 Likewise, escape sequences are not yet recognized.
4929 error->m4:stdin:1: Warning: unrecognized specifier in `%p'
4933 File: m4.info, Node: Arithmetic, Next: Shell commands, Prev: Text handling, Up: Top
4935 12 Macros for doing arithmetic
4936 ******************************
4938 Integer arithmetic is included in 'm4', with a C-like syntax. As
4939 convenient shorthands, there are builtins for simple increment and
4940 decrement operations.
4944 * Incr:: Decrement and increment operators
4945 * Eval:: Evaluating integer expressions
4948 File: m4.info, Node: Incr, Next: Eval, Up: Arithmetic
4950 12.1 Decrement and increment operators
4951 ======================================
4953 Increment and decrement of integers are supported using the builtins
4956 -- Builtin: incr (NUMBER)
4957 -- Builtin: decr (NUMBER)
4958 Expand to the numerical value of NUMBER, incremented or
4959 decremented, respectively, by one. Except for the empty string,
4960 the expansion is empty if NUMBER could not be parsed.
4962 The macros 'incr' and 'decr' are recognized only with parameters.
4969 error->m4:stdin:3: empty string treated as 0 in builtin `incr'
4972 error->m4:stdin:4: empty string treated as 0 in builtin `decr'
4976 File: m4.info, Node: Eval, Prev: Incr, Up: Arithmetic
4978 12.2 Evaluating integer expressions
4979 ===================================
4981 Integer expressions are evaluated with 'eval':
4983 -- Builtin: eval (EXPRESSION, [RADIX = '10']
4984 Expands to the value of EXPRESSION. The expansion is empty if a
4985 problem is encountered while parsing the arguments. If specified,
4986 RADIX and WIDTH control the format of the output.
4988 Calculations are done with 32-bit signed numbers. Overflow
4989 silently results in wraparound. A warning is issued if division by
4990 zero is attempted, or if EXPRESSION could not be parsed.
4992 Expressions can contain the following operators, listed in order of
4993 decreasing precedence.
4998 Unary plus and minus, and bitwise and logical negation
5002 Multiplication, division, and modulo
5004 Addition and subtraction
5008 Relational operators
5014 Bitwise exclusive-or
5022 The macro 'eval' is recognized only with parameters.
5024 All binary operators, except exponentiation, are left associative. C
5025 operators that perform variable assignment, such as '+=' or '--', are
5026 not implemented, since 'eval' only operates on constants, not variables.
5027 Attempting to use them results in an error. However, since traditional
5028 implementations treated '=' as an undocumented alias for '==' as opposed
5029 to an assignment operator, this usage is supported as a special case.
5030 Be aware that a future version of GNU M4 may support assignment
5031 semantics as an extension when POSIX mode is not requested, and that
5032 using '=' to check equality is not portable.
5035 error->m4:stdin:1: Warning: recommend ==, not =, for equality operator
5038 error->m4:stdin:2: invalid operator in eval: ++0
5041 error->m4:stdin:3: invalid operator in eval: 0 |= 1
5044 Note that some older 'm4' implementations use '^' as an alternate
5045 operator for the exponentiation, although POSIX requires the C behavior
5046 of bitwise exclusive-or. The precedence of the negation operators, '~'
5047 and '!', was traditionally lower than equality. The unary operators
5048 could not be used reliably more than once on the same term without
5049 intervening parentheses. The traditional precedence of the equality
5050 operators '==' and '!=' was identical instead of lower than the
5051 relational operators such as '<', even through GNU M4 1.4.8. Starting
5052 with version 1.4.9, GNU M4 correctly follows POSIX precedence rules. M4
5053 scripts designed to be portable between releases must be aware that
5054 parentheses may be required to enforce C precedence rules. Likewise,
5055 division by zero, even in the unused branch of a short-circuiting
5056 operator, is not always well-defined in other implementations.
5058 Following are some examples where the current version of M4 follows C
5059 precedence rules, but where older versions and some other
5060 implementations of 'm4' require explicit parentheses to get the correct
5065 eval(`(1 == 2) > 0')
5075 eval(`+ + - ~ ! ~ 0')
5080 error->m4:stdin:9: divide by zero in eval: 0 || 1 / 0
5085 error->m4:stdin:11: modulo by zero in eval: 2 && 1 % 0
5088 As a GNU extension, the operator '**' performs integral
5089 exponentiation. The operator is right-associative, and if evaluated,
5090 the exponent must be non-negative, and at least one of the arguments
5091 must be non-zero, or a warning is issued.
5095 eval(`(2 ** 3) ** 2')
5103 error->m4:stdin:5: divide by zero in eval: 0 ** 0
5105 error->m4:stdin:6: negative exponent in eval: 4 ** -2
5108 Within EXPRESSION, (but not RADIX or WIDTH), numbers without a
5109 special prefix are decimal. A simple '0' prefix introduces an octal
5110 number. '0x' introduces a hexadecimal number. As GNU extensions, '0b'
5111 introduces a binary number. '0r' introduces a number expressed in any
5112 radix between 1 and 36: the prefix should be immediately followed by the
5113 decimal expression of the radix, a colon, then the digits making the
5114 number. For radix 1, leading zeros are ignored, and all remaining
5115 digits must be '1'; for all other radices, the digits are '0', '1', '2',
5116 .... Beyond '9', the digits are 'a', 'b' ... up to 'z'. Lower and
5117 upper case letters can be used interchangeably in numbers prefixes and
5120 Parentheses may be used to group subexpressions whenever needed. For
5121 the relational operators, a true relation returns '1', and a false
5122 relation return '0'.
5124 Here are a few examples of use of 'eval'.
5134 eval(index(`Hello world', `llo') >= 0)
5136 eval(`0r1:0111 + 0b100 + 0r3:12')
5138 define(`square', `eval(`($1) ** 2')')
5142 square(square(`5')` + 1')
5144 define(`foo', `666')
5147 error->m4:stdin:11: bad expression in eval: foo / 6
5152 As the last two lines show, 'eval' does not handle macro names, even
5153 if they expand to a valid expression (or part of a valid expression).
5154 Therefore all macros must be expanded before they are passed to 'eval'.
5156 Some calculations are not portable to other implementations, since
5157 they have undefined semantics in C, but GNU 'm4' has well-defined
5158 behavior on overflow. When shifting, an out-of-range shift amount is
5159 implicitly brought into the range of 32-bit signed integers using an
5160 implicit bit-wise and with 0x1f).
5162 define(`max_int', eval(`0x7fffffff'))
5164 define(`min_int', incr(max_int))
5170 ifelse(eval(min_int` / -1'), min_int, `overflow occurred')
5174 eval(`0x80000000 % -1')
5181 If RADIX is specified, it specifies the radix to be used in the
5182 expansion. The default radix is 10; this is also the case if RADIX is
5183 the empty string. A warning results if the radix is outside the range
5184 of 1 through 36, inclusive. The result of 'eval' is always taken to be
5185 signed. No radix prefix is output, and for radices greater than 10, the
5186 digits are lower case. The WIDTH argument specifies the minimum output
5187 width, excluding any negative sign. The result is zero-padded to extend
5188 the expansion to the requested width. A warning results if the width is
5189 negative. If RADIX or WIDTH is out of bounds, the expansion of 'eval'
5198 eval(`666', `6', `10')
5200 eval(`-666', `6', `10')
5204 `0r1:'eval(`10', `1', `11')
5209 error->m4:stdin:9: radix 37 in builtin `eval' out of range
5212 error->m4:stdin:10: negative width to builtin `eval'
5215 error->m4:stdin:11: empty string treated as 0 in builtin `eval'
5219 File: m4.info, Node: Shell commands, Next: Miscellaneous, Prev: Arithmetic, Up: Top
5221 13 Macros for running shell commands
5222 ************************************
5224 There are a few builtin macros in 'm4' that allow you to run shell
5225 commands from within 'm4'.
5227 Note that the definition of a valid shell command is system
5228 dependent. On UNIX systems, this is the typical '/bin/sh'. But on
5229 other systems, such as native Windows, the shell has a different syntax
5230 of commands that it understands. Some examples in this chapter assume
5231 '/bin/sh', and also demonstrate how to quit early with a known exit
5232 value if this is not the case.
5236 * Platform macros:: Determining the platform
5237 * Syscmd:: Executing simple commands
5238 * Esyscmd:: Reading the output of commands
5239 * Sysval:: Exit status
5240 * Mkstemp:: Making temporary files
5243 File: m4.info, Node: Platform macros, Next: Syscmd, Up: Shell commands
5245 13.1 Determining the platform
5246 =============================
5248 Sometimes it is desirable for an input file to know which platform 'm4'
5249 is running on. GNU 'm4' provides several macros that are predefined to
5250 expand to the empty string; checking for their existence will confirm
5253 -- Optional builtin: __gnu__
5254 -- Optional builtin: __os2__
5255 -- Optional builtin: os2
5256 -- Optional builtin: __unix__
5257 -- Optional builtin: unix
5258 -- Optional builtin: __windows__
5259 -- Optional builtin: windows
5260 Each of these macros is conditionally defined as needed to describe
5261 the environment of 'm4'. If defined, each macro expands to the
5262 empty string. For now, these macros silently ignore all arguments,
5263 but in a future release of M4, they might warn if arguments are
5266 When GNU extensions are in effect (that is, when you did not use the
5267 '-G' option, *note Invoking m4: Limits control.), GNU 'm4' will define
5268 the macro '__gnu__' to expand to the empty string.
5275 Extensions are ifdef(`__gnu__', `active', `inactive')
5276 =>Extensions are active
5283 Extensions are ifdef(`__gnu__', `active', `inactive')
5284 =>Extensions are inactive
5286 On UNIX systems, GNU 'm4' will define '__unix__' by default, or
5287 'unix' when the '-G' option is specified.
5289 On native Windows systems, GNU 'm4' will define '__windows__' by
5290 default, or 'windows' when the '-G' option is specified.
5292 On OS/2 systems, GNU 'm4' will define '__os2__' by default, or 'os2'
5293 when the '-G' option is specified.
5295 If GNU 'm4' does not provide a platform macro for your system, please
5296 report that as a bug.
5298 define(`provided', `0')
5300 ifdef(`__unix__', `define(`provided', incr(provided))')
5302 ifdef(`__windows__', `define(`provided', incr(provided))')
5304 ifdef(`__os2__', `define(`provided', incr(provided))')
5310 File: m4.info, Node: Syscmd, Next: Esyscmd, Prev: Platform macros, Up: Shell commands
5312 13.2 Executing simple commands
5313 ==============================
5315 Any shell command can be executed, using 'syscmd':
5317 -- Builtin: syscmd (SHELL-COMMAND)
5318 Executes SHELL-COMMAND as a shell command.
5320 The expansion of 'syscmd' is void, _not_ the output from
5321 SHELL-COMMAND! Output or error messages from SHELL-COMMAND are not
5322 read by 'm4'. *Note Esyscmd::, if you need to process the command
5325 Prior to executing the command, 'm4' flushes its buffers. The
5326 default standard input, output and error of SHELL-COMMAND are the
5327 same as those of 'm4'.
5329 By default, the SHELL-COMMAND will be used as the argument to the
5330 '-c' option of the '/bin/sh' shell (or the version of 'sh'
5331 specified by 'command -p getconf PATH', if your system supports
5332 that). If you prefer a different shell, the 'configure' script can
5333 be given the option '--with-syscmd-shell=LOCATION' to set the
5334 location of an alternative shell at GNU 'm4' installation; the
5335 alternative shell must still support '-c'.
5337 The macro 'syscmd' is recognized only with parameters.
5339 define(`foo', `FOO')
5345 Note how the expansion of 'syscmd' keeps the trailing newline of the
5346 command, as well as using the newline that appeared after the macro.
5348 The following is an example of SHELL-COMMAND using the same standard
5351 $ echo "m4wrap(\`syscmd(\`cat')')" | m4
5354 It tells 'm4' to read all of its input before executing the wrapped
5355 text, then hand a valid (albeit emptied) pipe as standard input for the
5356 'cat' subcommand. Therefore, you should be careful when using standard
5357 input (either by specifying no files, or by passing '-' as a file name
5358 on the command line, *note Invoking m4: Command line files.), and also
5359 invoking subcommands via 'syscmd' or 'esyscmd' that consume data from
5360 standard input. When standard input is a seekable file, the subprocess
5361 will pick up with the next character not yet processed by 'm4'; when it
5362 is a pipe or other non-seekable file, there is no guarantee how much
5363 data will already be buffered by 'm4' and thus unavailable to the child.
5366 File: m4.info, Node: Esyscmd, Next: Sysval, Prev: Syscmd, Up: Shell commands
5368 13.3 Reading the output of commands
5369 ===================================
5371 If you want 'm4' to read the output of a shell command, use 'esyscmd':
5373 -- Builtin: esyscmd (SHELL-COMMAND)
5374 Expands to the standard output of the shell command SHELL-COMMAND.
5376 Prior to executing the command, 'm4' flushes its buffers. The
5377 default standard input and standard error of SHELL-COMMAND are the
5378 same as those of 'm4'. The error output of SHELL-COMMAND is not a
5379 part of the expansion: it will appear along with the error output
5382 By default, the SHELL-COMMAND will be used as the argument to the
5383 '-c' option of the '/bin/sh' shell (or the version of 'sh'
5384 specified by 'command -p getconf PATH', if your system supports
5385 that). If you prefer a different shell, the 'configure' script can
5386 be given the option '--with-syscmd-shell=LOCATION' to set the
5387 location of an alternative shell at GNU 'm4' installation; the
5388 alternative shell must still support '-c'.
5390 The macro 'esyscmd' is recognized only with parameters.
5392 define(`foo', `FOO')
5398 Note how the expansion of 'esyscmd' keeps the trailing newline of the
5399 command, as well as using the newline that appeared after the macro.
5401 Just as with 'syscmd', care must be exercised when sharing standard
5402 input between 'm4' and the child process of 'esyscmd'.
5405 File: m4.info, Node: Sysval, Next: Mkstemp, Prev: Esyscmd, Up: Shell commands
5410 To see whether a shell command succeeded, use 'sysval':
5413 Expands to the exit status of the last shell command run with
5414 'syscmd' or 'esyscmd'. Expands to 0 if no command has been run
5421 ifelse(sysval, `0', `zero', `non-zero')
5433 ifelse(sysval, `0', `zero', `non-zero')
5435 esyscmd(`echo dnl && exit 127')
5444 'sysval' results in 127 if there was a problem executing the command,
5445 for example, if the system-imposed argument length is exceeded, or if
5446 there were not enough resources to fork. It is not possible to
5447 distinguish between failed execution and successful execution that had
5448 an exit status of 127, unless there was output from the child process.
5450 On UNIX platforms, where it is possible to detect when command
5451 execution is terminated by a signal, rather than a normal exit, the
5452 result is the signal number shifted left by eight bits.
5454 dnl This test assumes kill is a shell builtin, and that signals are
5457 `errprint(` skipping: syscmd does not have unix semantics
5459 syscmd(`kill -9 $$')
5467 esyscmd(`kill -9 $$')
5473 File: m4.info, Node: Mkstemp, Prev: Sysval, Up: Shell commands
5475 13.5 Making temporary files
5476 ===========================
5478 Commands specified to 'syscmd' or 'esyscmd' might need a temporary file,
5479 for output or for some other purpose. There is a builtin macro,
5480 'mkstemp', for making a temporary file:
5482 -- Builtin: mkstemp (TEMPLATE)
5483 -- Builtin: maketemp (TEMPLATE)
5484 Expands to the quoted name of a new, empty file, made from the
5485 string TEMPLATE, which should end with the string 'XXXXXX'. The
5486 six 'X' characters are then replaced with random characters
5487 matching the regular expression '[a-zA-Z0-9._-]', in order to make
5488 the file name unique. If fewer than six 'X' characters are found
5489 at the end of 'template', the result will be longer than the
5490 template. The created file will have access permissions as if by
5491 'chmod =rw,go=', meaning that the current umask of the 'm4' process
5492 is taken into account, and at most only the current user can read
5495 The traditional behavior, standardized by POSIX, is that 'maketemp'
5496 merely replaces the trailing 'X' with the process id, without
5497 creating a file or quoting the expansion, and without ensuring that
5498 the resulting string is a unique file name. In part, this means
5499 that using the same TEMPLATE twice in the same input file will
5500 result in the same expansion. This behavior is a security hole, as
5501 it is very easy for another process to guess the name that will be
5502 generated, and thus interfere with a subsequent use of 'syscmd'
5503 trying to manipulate that file name. Hence, POSIX has recommended
5504 that all new implementations of 'm4' provide the secure 'mkstemp'
5505 builtin, and that users of 'm4' check for its existence.
5507 The expansion is void and an error issued if a temporary file could
5510 The macros 'mkstemp' and 'maketemp' are recognized only with
5513 If you try this next example, you will most likely get different
5514 output for the two file names, since the replacement characters are
5518 define(`tmp', `oops')
5520 maketemp(`/tmp/fooXXXXXX')
5522 ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))',
5523 `define(`mkstemp', defn(`maketemp'))dnl
5524 errprint(`warning: potentially insecure maketemp implementation
5530 Unless you use the '--traditional' command line option (or '-G',
5531 *note Invoking m4: Limits control.), the GNU version of 'maketemp' is
5532 secure. This means that using the same template to multiple calls will
5533 generate multiple files. However, we recommend that you use the new
5534 'mkstemp' macro, introduced in GNU M4 1.4.8, which is secure even in
5535 traditional mode. Also, as of M4 1.4.11, the secure implementation
5536 quotes the resulting file name, so that you are guaranteed to know what
5537 file was created even if the random file name happens to match an
5538 existing macro. Notice that this example is careful to use 'defn' to
5539 avoid unintended expansion of 'foo'.
5542 define(`foo', `errprint(`oops')')
5544 syscmd(`rm -f foo-??????')sysval
5546 define(`file1', maketemp(`foo-XXXXXX'))dnl
5547 ifelse(esyscmd(`echo \` foo-?????? \''), ` foo-?????? ',
5548 `no file', `created')
5550 define(`file2', maketemp(`foo-XX'))dnl
5551 define(`file3', mkstemp(`foo-XXXXXX'))dnl
5552 ifelse(len(defn(`file1')), len(defn(`file2')),
5553 `same length', `different')
5555 ifelse(defn(`file1'), defn(`file2'), `same', `different file')
5557 ifelse(defn(`file2'), defn(`file3'), `same', `different file')
5559 ifelse(defn(`file1'), defn(`file3'), `same', `different file')
5561 syscmd(`rm 'defn(`file1') defn(`file2') defn(`file3'))
5567 File: m4.info, Node: Miscellaneous, Next: Frozen files, Prev: Shell commands, Up: Top
5569 14 Miscellaneous builtin macros
5570 *******************************
5572 This chapter describes various builtins, that do not really belong in
5573 any of the previous chapters.
5577 * Errprint:: Printing error messages
5578 * Location:: Printing current location
5579 * M4exit:: Exiting from 'm4'
5582 File: m4.info, Node: Errprint, Next: Location, Up: Miscellaneous
5584 14.1 Printing error messages
5585 ============================
5587 You can print error messages using 'errprint':
5589 -- Builtin: errprint (MESSAGE, ...)
5590 Prints MESSAGE and the rest of the arguments to standard error,
5591 separated by spaces. Standard error is used, regardless of the
5592 '--debugfile' option (*note Invoking m4: Debugging options.).
5594 The expansion of 'errprint' is void. The macro 'errprint' is
5595 recognized only with parameters.
5597 errprint(`Invalid arguments to forloop
5599 error->Invalid arguments to forloop
5601 errprint(`1')errprint(`2',`3
5606 A trailing newline is _not_ printed automatically, so it should be
5607 supplied as part of the argument, as in the example. Unfortunately, the
5608 exact output of 'errprint' is not very portable to other 'm4'
5609 implementations: POSIX requires that all arguments be printed, but some
5610 implementations of 'm4' only print the first. Furthermore, some BSD
5611 implementations always append a newline for each 'errprint' call,
5612 regardless of whether the last argument already had one, and POSIX is
5613 silent on whether this is acceptable.
5616 File: m4.info, Node: Location, Next: M4exit, Prev: Errprint, Up: Miscellaneous
5618 14.2 Printing current location
5619 ==============================
5621 To make it possible to specify the location of an error, three utility
5624 -- Builtin: __file__
5625 -- Builtin: __line__
5626 -- Builtin: __program__
5627 Expand to the quoted name of the current input file, the current
5628 input line number in that file, and the quoted name of the current
5631 errprint(__program__:__file__:__line__: `input error
5633 error->m4:stdin:1: input error
5636 Line numbers start at 1 for each file. If the file was found due to
5637 the '-I' option or 'M4PATH' environment variable, that is reflected in
5638 the file name. The syncline option ('-s', *note Invoking m4:
5639 Preprocessor features.), and the 'f' and 'l' flags of 'debugmode' (*note
5640 Debug Levels::), also use this notion of current file and line.
5641 Redefining the three location macros has no effect on syncline, debug,
5642 warning, or error message output.
5644 This example reuses the file 'incl.m4' mentioned earlier (*note
5648 define(`foo', ``$0' called at __file__:__line__')
5651 =>foo called at stdin:2
5653 =>Include file start
5654 =>foo called at examples/incl.m4:2
5658 The location of macros invoked during the rescanning of macro
5659 expansion text corresponds to the location in the file where the
5660 expansion was triggered, regardless of how many newline characters the
5661 expansion text contains. As of GNU M4 1.4.8, the location of text
5662 wrapped with 'm4wrap' (*note M4wrap::) is the point at which the
5663 'm4wrap' was invoked. Previous versions, however, behaved as though
5664 wrapped text came from line 0 of the file "".
5666 define(`echo', `$@')
5668 define(`foo', `echo(__line__
5678 foo(errprint(__line__
5695 The '__program__' macro behaves like '$0' in shell terminology. If
5696 you invoke 'm4' through an absolute path or a link with a different
5697 spelling, rather than by relying on a 'PATH' search for plain 'm4', it
5698 will affect how '__program__' expands. The intent is that you can use
5699 it to produce error messages with the same formatting that 'm4' produces
5700 internally. It can also be used within 'syscmd' (*note Syscmd::) to
5701 pick the same version of 'm4' that is currently running, rather than
5702 whatever version of 'm4' happens to be first in 'PATH'. It was first
5703 introduced in GNU M4 1.4.6.
5706 File: m4.info, Node: M4exit, Prev: Location, Up: Miscellaneous
5708 14.3 Exiting from 'm4'
5709 ======================
5711 If you need to exit from 'm4' before the entire input has been read, you
5714 -- Builtin: m4exit ([CODE = '0']
5715 Causes 'm4' to exit, with exit status CODE. If CODE is left out,
5716 the exit status is zero. If CODE cannot be parsed, or is outside
5717 the range of 0 to 255, the exit status is one. No further input is
5718 read, and all wrapped and diverted text is discarded.
5720 m4wrap(`This text is lost due to `m4exit'.')
5722 divert(`1') So is this.
5725 m4exit And this is never read.
5727 A common use of this is to abort processing:
5729 -- Composite: fatal_error (MESSAGE)
5730 Abort processing with an error message and non-zero status. Prefix
5731 MESSAGE with details about where the error occurred, and print the
5732 resulting string to standard error.
5734 define(`fatal_error',
5735 `errprint(__program__:__file__:__line__`: fatal error: $*
5738 fatal_error(`this is a BAD one, buster')
5739 error->m4:stdin:4: fatal error: this is a BAD one, buster
5741 After this macro call, 'm4' will exit with exit status 1. This macro
5742 is only intended for error exits, since the normal exit procedures are
5743 not followed, i.e., diverted text is not undiverted, and saved text
5744 (*note M4wrap::) is not reread. (This macro could be made more robust
5745 to earlier versions of 'm4'. You should try to see if you can find
5746 weaknesses and correct them; or *note Answers: Improved fatal_error.).
5748 Note that it is still possible for the exit status to be different
5749 than what was requested by 'm4exit'. If 'm4' detects some other error,
5750 such as a write error on standard output, the exit status will be
5751 non-zero even if 'm4exit' requested zero.
5753 If standard input is seekable, then the file will be positioned at
5754 the next unread character. If it is a pipe or other non-seekable file,
5755 then there are no guarantees how much data 'm4' might have read into
5756 buffers, and thus discarded.
5759 File: m4.info, Node: Frozen files, Next: Compatibility, Prev: Miscellaneous, Up: Top
5761 15 Fast loading of frozen state
5762 *******************************
5764 Some bigger 'm4' applications may be built over a common base containing
5765 hundreds of definitions and other costly initializations. Usually, the
5766 common base is kept in one or more declarative files, which files are
5767 listed on each 'm4' invocation prior to the user's input file, or else
5768 each input file uses 'include'.
5770 Reading the common base of a big application, over and over again,
5771 may be time consuming. GNU 'm4' offers some machinery to speed up the
5772 start of an application using lengthy common bases.
5776 * Using frozen files:: Using frozen files
5777 * Frozen file format:: Frozen file format
5780 File: m4.info, Node: Using frozen files, Next: Frozen file format, Up: Frozen files
5782 15.1 Using frozen files
5783 =======================
5785 Suppose a user has a library of 'm4' initializations in 'base.m4', which
5786 is then used with multiple input files:
5788 $ m4 base.m4 input1.m4
5789 $ m4 base.m4 input2.m4
5790 $ m4 base.m4 input3.m4
5792 Rather than spending time parsing the fixed contents of 'base.m4'
5793 every time, the user might rather execute:
5795 $ m4 -F base.m4f base.m4
5797 once, and further execute, as often as needed:
5799 $ m4 -R base.m4f input1.m4
5800 $ m4 -R base.m4f input2.m4
5801 $ m4 -R base.m4f input3.m4
5803 with the varying input. The first call, containing the '-F' option,
5804 only reads and executes file 'base.m4', defining various application
5805 macros and computing other initializations. Once the input file
5806 'base.m4' has been completely processed, GNU 'm4' produces in 'base.m4f'
5807 a "frozen" file, that is, a file which contains a kind of snapshot of
5808 the 'm4' internal state.
5810 Later calls, containing the '-R' option, are able to reload the
5811 internal state of 'm4', from 'base.m4f', _prior_ to reading any other
5812 input files. This means instead of starting with a virgin copy of 'm4',
5813 input will be read after having effectively recovered the effect of a
5814 prior run. In our example, the effect is the same as if file 'base.m4'
5815 has been read anew. However, this effect is achieved a lot faster.
5817 Only one frozen file may be created or read in any one 'm4'
5818 invocation. It is not possible to recover two frozen files at once.
5819 However, frozen files may be updated incrementally, through using '-R'
5820 and '-F' options simultaneously. For example, if some care is taken,
5823 $ m4 file1.m4 file2.m4 file3.m4 file4.m4
5825 could be broken down in the following sequence, accumulating the same
5828 $ m4 -F file1.m4f file1.m4
5829 $ m4 -R file1.m4f -F file2.m4f file2.m4
5830 $ m4 -R file2.m4f -F file3.m4f file3.m4
5831 $ m4 -R file3.m4f file4.m4
5833 Some care is necessary because not every effort has been made for
5834 this to work in all cases. In particular, the trace attribute of macros
5835 is not handled, nor the current setting of 'changeword'. Currently,
5836 'm4wrap' and 'sysval' also have problems. Also, interactions for some
5837 options of 'm4', being used in one call and not in the next, have not
5838 been fully analyzed yet. On the other end, you may be confident that
5839 stacks of 'pushdef' definitions are handled correctly, as well as
5840 undefined or renamed builtins, and changed strings for quotes or
5841 comments. And future releases of GNU M4 will improve on the utility of
5844 When an 'm4' run is to be frozen, the automatic undiversion which
5845 takes place at end of execution is inhibited. Instead, all positively
5846 numbered diversions are saved into the frozen file. The active
5847 diversion number is also transmitted.
5849 A frozen file to be reloaded need not reside in the current
5850 directory. It is looked up the same way as an 'include' file (*note
5853 If the frozen file was generated with a newer version of 'm4', and
5854 contains directives that an older 'm4' cannot parse, attempting to load
5855 the frozen file with option '-R' will cause 'm4' to exit with status 63
5856 to indicate version mismatch.
5859 File: m4.info, Node: Frozen file format, Prev: Using frozen files, Up: Frozen files
5861 15.2 Frozen file format
5862 =======================
5864 Frozen files are sharable across architectures. It is safe to write a
5865 frozen file on one machine and read it on another, given that the second
5866 machine uses the same or newer version of GNU 'm4'. It is conventional,
5867 but not required, to give a frozen file the suffix of '.m4f'.
5869 These are simple (editable) text files, made up of directives, each
5870 starting with a capital letter and ending with a newline (<NL>).
5871 Wherever a directive is expected, the character '#' introduces a comment
5872 line; empty lines are also ignored if they are not part of an embedded
5873 string. In the following descriptions, each LEN refers to the length of
5874 the corresponding strings STR in the next line of input. Numbers are
5875 always expressed in decimal. There are no escape characters. The
5878 'C LEN1 , LEN2 <NL> STR1 STR2 <NL>'
5879 Uses STR1 and STR2 as the begin-comment and end-comment strings.
5880 If omitted, then '#' and <NL> are the comment delimiters.
5882 'D NUMBER, LEN <NL> STR <NL>'
5883 Selects diversion NUMBER, making it current, then copy STR in the
5884 current diversion. NUMBER may be a negative number for a
5885 non-existing diversion. To merely specify an active selection, use
5886 this command with an empty STR. With 0 as the diversion NUMBER,
5887 STR will be issued on standard output at reload time. GNU 'm4'
5888 will not produce the 'D' directive with non-zero length for
5889 diversion 0, but this can be done with manual edits. This
5890 directive may appear more than once for the same diversion, in
5891 which case the diversion is the concatenation of the various uses.
5892 If omitted, then diversion 0 is current.
5894 'F LEN1 , LEN2 <NL> STR1 STR2 <NL>'
5895 Defines, through 'pushdef', a definition for STR1 expanding to the
5896 function whose builtin name is STR2. If the builtin does not exist
5897 (for example, if the frozen file was produced by a copy of 'm4'
5898 compiled with changeword support, but the version of 'm4' reloading
5899 was compiled without it), the reload is silent, but any subsequent
5900 use of the definition of STR1 will result in a warning. This
5901 directive may appear more than once for the same name, and its
5902 order, along with 'T', is important. If omitted, you will have no
5903 access to any builtins.
5905 'Q LEN1 , LEN2 <NL> STR1 STR2 <NL>'
5906 Uses STR1 and STR2 as the begin-quote and end-quote strings. If
5907 omitted, then '`' and ''' are the quote delimiters.
5909 'T LEN1 , LEN2 <NL> STR1 STR2 <NL>'
5910 Defines, though 'pushdef', a definition for STR1 expanding to the
5911 text given by STR2. This directive may appear more than once for
5912 the same name, and its order, along with 'F', is important.
5915 Confirms the format of the file. 'm4' 1.4.17 only creates and
5916 understands frozen files where NUMBER is 1. This directive must be
5917 the first non-comment in the file, and may not appear more than
5921 File: m4.info, Node: Compatibility, Next: Answers, Prev: Frozen files, Up: Top
5923 16 Compatibility with other versions of 'm4'
5924 ********************************************
5926 This chapter describes the many of the differences between this
5927 implementation of 'm4', and of other implementations found under UNIX,
5928 such as System V Release 4, Solaris, and BSD flavors. In particular, it
5929 lists the known differences and extensions to POSIX. However, the list
5930 is not necessarily comprehensive.
5932 At the time of this writing, POSIX 2001 (also known as IEEE Std
5933 1003.1-2001) is the latest standard, although a new version of POSIX is
5934 under development and includes several proposals for modifying what 'm4'
5935 is required to do. The requirements for 'm4' are shared between SUSv3
5936 and POSIX, and can be viewed at
5937 <http://www.opengroup.org/onlinepubs/000095399/utilities/m4.html>.
5941 * Extensions:: Extensions in GNU M4
5942 * Incompatibilities:: Facilities in System V m4 not in GNU M4
5943 * Other Incompatibilities:: Other incompatibilities
5946 File: m4.info, Node: Extensions, Next: Incompatibilities, Up: Compatibility
5948 16.1 Extensions in GNU M4
5949 =========================
5951 This version of 'm4' contains a few facilities that do not exist in
5952 System V 'm4'. These extra facilities are all suppressed by using the
5953 '-G' command line option (*note Invoking m4: Limits control.), unless
5954 overridden by other command line options.
5956 * In the '$N' notation for macro arguments, N can contain several
5957 digits, while the System V 'm4' only accepts one digit. This
5958 allows macros in GNU 'm4' to take any number of arguments, and not
5959 only nine (*note Arguments::).
5961 This means that 'define(`foo', `$11')' is ambiguous between
5962 implementations. To portably choose between grabbing the first
5963 parameter and appending 1 to the expansion, or grabbing the
5964 eleventh parameter, you can do the following:
5968 dnl First argument, concatenated with 1
5969 define(`_1', `$1')define(`first1', `_1($@)1')
5971 dnl Eleventh argument, portable
5972 define(`_9', `$9')define(`eleventh', `_9(shift(shift($@)))')
5974 dnl Eleventh argument, GNU style
5975 define(`Eleventh', `$11')
5977 first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
5979 eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
5981 Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
5984 Also see the 'argn' macro (*note Shift::).
5986 * The 'divert' (*note Divert::) macro can manage more than 9
5987 diversions. GNU 'm4' treats all positive numbers as valid
5988 diversions, rather than discarding diversions greater than 9.
5990 * Files included with 'include' and 'sinclude' are sought in a user
5991 specified search path, if they are not found in the working
5992 directory. The search path is specified by the '-I' option and the
5993 'M4PATH' environment variable (*note Search Path::).
5995 * Arguments to 'undivert' can be non-numeric, in which case the named
5996 file will be included uninterpreted in the output (*note
5999 * Formatted output is supported through the 'format' builtin, which
6000 is modeled after the C library function 'printf' (*note Format::).
6002 * Searches and text substitution through basic regular expressions
6003 are supported by the 'regexp' (*note Regexp::) and 'patsubst'
6004 (*note Patsubst::) builtins. Some BSD implementations use extended
6005 regular expressions instead.
6007 * The output of shell commands can be read into 'm4' with 'esyscmd'
6010 * There is indirect access to any builtin macro with 'builtin' (*note
6013 * Macros can be called indirectly through 'indir' (*note Indir::).
6015 * The name of the program, the current input file, and the current
6016 input line number are accessible through the builtins
6017 '__program__', '__file__', and '__line__' (*note Location::).
6019 * The format of the output from 'dumpdef' and macro tracing can be
6020 controlled with 'debugmode' (*note Debug Levels::).
6022 * The destination of trace and debug output can be controlled with
6023 'debugfile' (*note Debug Output::).
6025 * The 'maketemp' (*note Mkstemp::) macro behaves like 'mkstemp',
6026 creating a new file with a unique name on every invocation, rather
6027 than following the insecure behavior of replacing the trailing 'X'
6028 characters with the 'm4' process id.
6030 * POSIX only requires support for the command line options '-s',
6031 '-D', and '-U', so all other options accepted by GNU M4 are
6032 extensions. *Note Invoking m4::, for a description of these
6035 The debugging and tracing facilities in GNU 'm4' are much more
6036 extensive than in most other versions of 'm4'.
6039 File: m4.info, Node: Incompatibilities, Next: Other Incompatibilities, Prev: Extensions, Up: Compatibility
6041 16.2 Facilities in System V 'm4' not in GNU 'm4'
6042 ================================================
6044 The version of 'm4' from System V contains a few facilities that have
6045 not been implemented in GNU 'm4' yet. Additionally, POSIX requires some
6046 behaviors that GNU 'm4' has not implemented yet. Relying on these
6047 behaviors is non-portable, as a future release of GNU 'm4' may change.
6049 * POSIX requires support for multiple arguments to 'defn', without
6050 any clarification on how 'defn' behaves when one of the multiple
6051 arguments names a builtin. System V 'm4' and some other
6052 implementations allow mixing builtins and text macros into a single
6053 macro. GNU 'm4' only supports joining multiple text arguments,
6054 although a future implementation may lift this restriction to
6055 behave more like System V. The only portable way to join text
6056 macros with builtins is via helper macros and implicit
6057 concatenation of macro results.
6059 * POSIX requires an application to exit with non-zero status if it
6060 wrote an error message to stderr. This has not yet been
6061 consistently implemented for the various builtins that are required
6062 to issue an error (such as 'eval' (*note Eval::) when an argument
6065 * Some traditional implementations only allow reading standard input
6066 once, but GNU 'm4' correctly handles multiple instances of '-' on
6069 * POSIX requires 'm4wrap' (*note M4wrap::) to act in FIFO (first-in,
6070 first-out) order, but GNU 'm4' currently uses LIFO order.
6071 Furthermore, POSIX states that only the first argument to 'm4wrap'
6072 is saved for later evaluation, but GNU 'm4' saves and processes all
6073 arguments, with output separated by spaces.
6075 * POSIX states that builtins that require arguments, but are called
6076 without arguments, have undefined behavior. Traditional
6077 implementations simply behave as though empty strings had been
6078 passed. For example, 'a`'define`'b' would expand to 'ab'. But GNU
6079 'm4' ignores certain builtins if they have missing arguments,
6080 giving 'adefineb' for the above example.
6082 * Traditional implementations handle 'define(`f',`1')' (*note
6083 Define::) by undefining the entire stack of previous definitions,
6084 and if doing 'undefine(`f')' first. GNU 'm4' replaces just the top
6085 definition on the stack, as if doing 'popdef(`f')' followed by
6086 'pushdef(`f',`1')'. POSIX allows either behavior.
6088 * POSIX 2001 requires 'syscmd' (*note Syscmd::) to evaluate command
6089 output for macro expansion, but this was a mistake that is
6090 anticipated to be corrected in the next version of POSIX. GNU 'm4'
6091 follows traditional behavior in 'syscmd' where output is not
6092 rescanned, and provides the extension 'esyscmd' that does scan the
6095 * At one point, POSIX required 'changequote(ARG)' (*note
6096 Changequote::) to use newline as the close quote, but this was a
6097 bug, and the next version of POSIX is anticipated to state that
6098 using empty strings or just one argument is unspecified.
6099 Meanwhile, the GNU 'm4' behavior of treating an empty end-quote
6100 delimiter as ''' is not portable, as Solaris treats it as repeating
6101 the start-quote delimiter, and BSD treats it as leaving the
6102 previous end-quote delimiter unchanged. For predictable results,
6103 never call changequote with just one argument, or with empty
6104 strings for arguments.
6106 * At one point, POSIX required 'changecom(ARG,)' (*note Changecom::)
6107 to make it impossible to end a comment, but this is a bug, and the
6108 next version of POSIX is anticipated to state that using empty
6109 strings is unspecified. Meanwhile, the GNU 'm4' behavior of
6110 treating an empty end-comment delimiter as newline is not portable,
6111 as BSD treats it as leaving the previous end-comment delimiter
6112 unchanged. It is also impossible in BSD implementations to disable
6113 comments, even though that is required by POSIX. For predictable
6114 results, never call changecom with empty strings for arguments.
6116 * Most implementations of 'm4' give macros a higher precedence than
6117 comments when parsing, meaning that if the start delimiter given to
6118 'changecom' (*note Changecom::) starts with a macro name, comments
6119 are effectively disabled. POSIX does not specify what the
6120 precedence is, so this version of GNU 'm4' parser recognizes
6121 comments, then macros, then quoted strings.
6123 * Traditional implementations allow argument collection, but not
6124 string and comment processing, to span file boundaries. Thus, if
6125 'a.m4' contains 'len(', and 'b.m4' contains 'abc)', 'm4 a.m4 b.m4'
6126 outputs '3' with traditional 'm4', but gives an error message that
6127 the end of file was encountered inside a macro with GNU 'm4'. On
6128 the other hand, traditional implementations do end of file
6129 processing for files included with 'include' or 'sinclude' (*note
6130 Include::), while GNU 'm4' seamlessly integrates the content of
6131 those files. Thus 'include(`a.m4')include(`b.m4')' will output '3'
6132 instead of giving an error.
6134 * Traditional 'm4' treats 'traceon' (*note Trace::) without arguments
6135 as a global variable, independent of named macro tracing. Also,
6136 once a macro is undefined, named tracing of that macro is lost. On
6137 the other hand, when GNU 'm4' encounters 'traceon' without
6138 arguments, it turns tracing on for all existing definitions at the
6139 time, but does not trace future definitions; 'traceoff' without
6140 arguments turns tracing off for all definitions regardless of
6141 whether they were also traced by name; and tracing by name, such as
6142 with '-tfoo' at the command line or 'traceon(`foo')' in the input,
6143 is an attribute that is preserved even if the macro is currently
6146 Additionally, while POSIX requires trace output, it makes no
6147 demands on the formatting of that output. Parsing trace output is
6148 not guaranteed to be reliable, even between different releases of
6149 GNU M4; however, the intent is that any future changes in trace
6150 output will only occur under the direction of additional
6151 'debugmode' flags (*note Debug Levels::).
6153 * POSIX requires 'eval' (*note Eval::) to treat all operators with
6154 the same precedence as C. However, earlier versions of GNU 'm4'
6155 followed the traditional behavior of other 'm4' implementations,
6156 where bitwise and logical negation ('~' and '!') have lower
6157 precedence than equality operators; and where equality operators
6158 ('==' and '!=') had the same precedence as relational operators
6159 (such as '<'). Use explicit parentheses to ensure proper
6160 precedence. As extensions to POSIX, GNU 'm4' gives well-defined
6161 semantics to operations that C leaves undefined, such as when
6162 overflow occurs, when shifting negative numbers, or when performing
6163 division by zero. POSIX also requires '=' to cause an error, but
6164 many traditional implementations allowed it as an alias for '=='.
6166 * POSIX 2001 requires 'translit' (*note Translit::) to treat each
6167 character of the second and third arguments literally. However, it
6168 is anticipated that the next version of POSIX will allow the GNU
6169 'm4' behavior of treating '-' as a range operator.
6171 * POSIX requires 'm4' to honor the locale environment variables of
6172 'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', and 'NLSPATH', but
6173 this has not yet been implemented in GNU 'm4'.
6175 * POSIX states that only unquoted leading newlines and blanks (that
6176 is, space and tab) are ignored when collecting macro arguments.
6177 However, this appears to be a bug in POSIX, since most traditional
6178 implementations also ignore all whitespace (formfeed, carriage
6179 return, and vertical tab). GNU 'm4' follows tradition and ignores
6180 all leading unquoted whitespace.
6182 * A strictly-compliant POSIX client is not allowed to use
6183 command-line arguments not specified by POSIX. However, since this
6184 version of M4 ignores 'POSIXLY_CORRECT' and enables the option
6185 '--gnu' by default (*note Invoking m4: Limits control.), a client
6186 desiring to be strictly compliant has no way to disable GNU
6187 extensions that conflict with POSIX when directly invoking the
6188 compiled 'm4'. A future version of 'GNU' M4 will honor the
6189 environment variable 'POSIXLY_CORRECT', implicitly enabling
6190 '--traditional' if it is set, in order to allow a
6191 strictly-compliant client. In the meantime, a client needing
6192 strict POSIX compliance can use the workaround of invoking a shell
6193 script wrapper, where the wrapper then adds '--traditional' to the
6194 arguments passed to the compiled 'm4'.
6197 File: m4.info, Node: Other Incompatibilities, Prev: Incompatibilities, Up: Compatibility
6199 16.3 Other incompatibilities
6200 ============================
6202 There are a few other incompatibilities between this implementation of
6203 'm4', and the System V version.
6205 * GNU 'm4' implements sync lines differently from System V 'm4', when
6206 text is being diverted. GNU 'm4' outputs the sync lines when the
6207 text is being diverted, and System V 'm4' when the diverted text is
6210 The problem is which lines and file names should be attached to
6211 text that is being, or has been, diverted. System V 'm4' regards
6212 all the diverted text as being generated by the source line
6213 containing the 'undivert' call, whereas GNU 'm4' regards the
6214 diverted text as being generated at the time it is diverted.
6216 The sync line option is used mostly when using 'm4' as a front end
6217 to a compiler. If a diverted line causes a compiler error, the
6218 error messages should most probably refer to the place where the
6219 diversion was made, and not where it was inserted again.
6232 The current 'm4' implementation has a limitation that the syncline
6233 output at the start of each diversion occurs no matter what, even
6234 if the previous diversion did not end with a newline. This goes
6235 contrary to the claim that synclines appear on a line by
6236 themselves, so this limitation may be corrected in a future version
6237 of 'm4'. In the meantime, when using '-s', it is wisest to make
6238 sure all diversions end with newline.
6240 * GNU 'm4' makes no attempt at prohibiting self-referential
6248 There is nothing inherently wrong with defining 'x' to return 'x'.
6249 The wrong thing is to expand 'x' unquoted, because that would cause
6250 an infinite rescan loop. In 'm4', one might use macros to hold
6251 strings, as we do for variables in other programming languages,
6252 further checking them with:
6254 ifelse(defn(`HOLDER'), `VALUE', ...)
6256 In cases like this one, an interdiction for a macro to hold its own
6257 name would be a useless limitation. Of course, this leaves more
6258 rope for the GNU 'm4' user to hang himself! Rescanning hangs may
6259 be avoided through careful programming, a little like for endless
6260 loops in traditional programming languages.
6263 File: m4.info, Node: Answers, Next: Copying This Package, Prev: Compatibility, Up: Top
6265 17 Correct version of some examples
6266 ***********************************
6268 Some of the examples in this manuals are buggy or not very robust, for
6269 demonstration purposes. Improved versions of these composite macros are
6274 * Improved exch:: Solution for 'exch'
6275 * Improved forloop:: Solution for 'forloop'
6276 * Improved foreach:: Solution for 'foreach'
6277 * Improved copy:: Solution for 'copy'
6278 * Improved m4wrap:: Solution for 'm4wrap'
6279 * Improved cleardivert:: Solution for 'cleardivert'
6280 * Improved capitalize:: Solution for 'capitalize'
6281 * Improved fatal_error:: Solution for 'fatal_error'
6284 File: m4.info, Node: Improved exch, Next: Improved forloop, Up: Answers
6286 17.1 Solution for 'exch'
6287 ========================
6289 The 'exch' macro (*note Arguments::) as presented requires clients to
6290 double quote their arguments. A nicer definition, which lets clients
6291 follow the rule of thumb of one level of quoting per level of
6292 parentheses, involves adding quotes in the definition of 'exch', as
6295 define(`exch', ``$2', `$1'')
6297 define(exch(`expansion text', `macro'))
6303 File: m4.info, Node: Improved forloop, Next: Improved foreach, Prev: Improved exch, Up: Answers
6305 17.2 Solution for 'forloop'
6306 ===========================
6308 The 'forloop' macro (*note Forloop::) as presented earlier can go into
6309 an infinite loop if given an iterator that is not parsed as a macro
6310 name. It does not do any sanity checking on its numeric bounds, and
6311 only permits decimal numbers for bounds. Here is an improved version,
6312 shipped as 'm4-1.4.17/examples/forloop2.m4'; this version also optimizes
6313 overhead by calling four macros instead of six per iteration (excluding
6314 those in TEXT), by not dereferencing the ITERATOR in the helper
6318 undivert(`forloop2.m4')dnl
6320 =># forloop(var, from, to, stmt) - improved version:
6321 =># works even if VAR is not a strict macro name
6322 =># performs sanity check that FROM is larger than TO
6323 =># allows complex numerical expressions in TO and FROM
6324 =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
6325 => `pushdef(`$1')_$0(`$1', eval(`$2'),
6326 => eval(`$3'), `$4')popdef(`$1')')')
6327 =>define(`_forloop',
6328 => `define(`$1', `$2')$4`'ifelse(`$2', `$3', `',
6329 => `$0(`$1', incr(`$2'), `$3', `$4')')')
6331 include(`forloop2.m4')
6333 forloop(`i', `2', `1', `no iteration occurs')
6335 forloop(`', `1', `2', ` odd iterator name')
6336 => odd iterator name odd iterator name
6337 forloop(`i', `5 + 5', `0xc', ` 0x`'eval(i, `16')')
6339 forloop(`i', `a', `b', `non-numeric bounds')
6340 error->m4:stdin:6: bad expression in eval (bad input): (a) <= (b)
6343 One other change to notice is that the improved version used '_$0'
6344 rather than '_foreach' to invoke the helper routine. In general, this
6345 is a good practice to follow, because then the set of macros can be
6346 uniformly transformed. The following example shows a transformation
6347 that doubles the current quoting and appends a suffix '2' to each
6348 transformed macro. If 'foreach' refers to the literal '_foreach', then
6349 'foreach2' invokes '_foreach' instead of the intended '_foreach2', and
6350 the mixing of quoting paradigms leads to an infinite recursion loop in
6353 $ m4 -d -L 9 -I examples
6354 define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4')
6356 define(`double', `define(`$1'`2',
6357 arg1(patsubst(dquote(defn(`$1')), `[`']', `\&\&')))')
6359 double(`forloop')double(`_forloop')defn(`forloop2')
6360 =>ifelse(eval(``($2) <= ($3)''), ``1'',
6361 => ``pushdef(``$1'')_$0(``$1'', eval(``$2''),
6362 => eval(``$3''), ``$4'')popdef(``$1'')'')
6363 forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
6365 changequote(`[', `]')changequote([``], [''])
6367 forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
6369 changequote`'include(`forloop.m4')
6371 double(`forloop')double(`_forloop')defn(`forloop2')
6372 =>pushdef(``$1'', ``$2'')_forloop($@)popdef(``$1'')
6373 forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
6375 changequote(`[', `]')changequote([``], [''])
6377 forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
6378 error->m4:stdin:12: recursion limit of 9 exceeded, use -L<N> to change it
6380 One more optimization is still possible. Instead of repeatedly
6381 assigning a variable then invoking or dereferencing it, it is possible
6382 to pass the current iterator value as a single argument. Coupled with
6383 'curry' if other arguments are needed (*note Composition::), or with
6384 helper macros if the argument is needed in more than one place in the
6385 expansion, the output can be generated with three, rather than four,
6386 macros of overhead per iteration. Notice how the file
6387 'm4-1.4.17/examples/forloop3.m4' rearranges the arguments of the helper
6388 '_forloop' to take two arguments that are placed around the current
6389 value. By splitting a balanced set of parantheses across multiple
6390 arguments, the helper macro can now be shared by 'forloop' and the new
6394 include(`forloop3.m4')
6396 undivert(`forloop3.m4')dnl
6398 =># forloop_arg(from, to, macro) - invoke MACRO(value) for
6399 =># each value between FROM and TO, without define overhead
6400 =>define(`forloop_arg', `ifelse(eval(`($1) <= ($2)'), `1',
6401 => `_forloop(`$1', eval(`$2'), `$3(', `)')')')
6402 =># forloop(var, from, to, stmt) - refactored to share code
6403 =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
6404 => `pushdef(`$1')_forloop(eval(`$2'), eval(`$3'),
6405 => `define(`$1',', `)$4')popdef(`$1')')')
6406 =>define(`_forloop',
6407 => `$3`$1'$4`'ifelse(`$1', `$2', `',
6408 => `$0(incr(`$1'), `$2', `$3', `$4')')')
6410 forloop(`i', `1', `3', ` i')
6412 define(`echo', `$@')
6414 forloop_arg(`1', `3', ` echo')
6418 forloop_arg(`1', `3', `curry(`pushdef', `a')')
6429 Of course, it is possible to make even more improvements, such as
6430 adding an optional step argument, or allowing iteration through
6431 descending sequences. GNU Autoconf provides some of these additional
6432 bells and whistles in its 'm4_for' macro.
6435 File: m4.info, Node: Improved foreach, Next: Improved copy, Prev: Improved forloop, Up: Answers
6437 17.3 Solution for 'foreach'
6438 ===========================
6440 The 'foreach' and 'foreachq' macros (*note Foreach::) as presented
6441 earlier each have flaws. First, we will examine and fix the quadratic
6442 behavior of 'foreachq':
6445 include(`foreachq.m4')
6447 traceon(`shift')debugmode(`aq')
6449 foreachq(`x', ``1', `2', `3', `4'', `x
6452 error->m4trace: -3- shift(`1', `2', `3', `4')
6453 error->m4trace: -2- shift(`1', `2', `3', `4')
6455 error->m4trace: -4- shift(`1', `2', `3', `4')
6456 error->m4trace: -3- shift(`2', `3', `4')
6457 error->m4trace: -3- shift(`1', `2', `3', `4')
6458 error->m4trace: -2- shift(`2', `3', `4')
6460 error->m4trace: -5- shift(`1', `2', `3', `4')
6461 error->m4trace: -4- shift(`2', `3', `4')
6462 error->m4trace: -3- shift(`3', `4')
6463 error->m4trace: -4- shift(`1', `2', `3', `4')
6464 error->m4trace: -3- shift(`2', `3', `4')
6465 error->m4trace: -2- shift(`3', `4')
6467 error->m4trace: -6- shift(`1', `2', `3', `4')
6468 error->m4trace: -5- shift(`2', `3', `4')
6469 error->m4trace: -4- shift(`3', `4')
6470 error->m4trace: -3- shift(`4')
6472 Each successive iteration was adding more quoted 'shift' invocations,
6473 and the entire list contents were passing through every iteration. In
6474 general, when recursing, it is a good idea to make the recursion use
6475 fewer arguments, rather than adding additional quoted uses of 'shift'.
6476 By doing so, 'm4' uses less memory, invokes fewer macros, is less likely
6477 to run into machine limits, and most importantly, performs faster. The
6478 fixed version of 'foreachq' can be found in
6479 'm4-1.4.17/examples/foreachq2.m4':
6482 include(`foreachq2.m4')
6484 undivert(`foreachq2.m4')dnl
6485 =>include(`quote.m4')dnl
6487 =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
6488 =># quoted list, improved version
6489 =>define(`foreachq', `pushdef(`$1')_$0($@)popdef(`$1')')
6490 =>define(`_arg1q', ``$1'')
6491 =>define(`_rest', `ifelse(`$#', `1', `', `dquote(shift($@))')')
6492 =>define(`_foreachq', `ifelse(`$2', `', `',
6493 => `define(`$1', _arg1q($2))$3`'$0(`$1', _rest($2), `$3')')')
6495 traceon(`shift')debugmode(`aq')
6497 foreachq(`x', ``1', `2', `3', `4'', `x
6500 error->m4trace: -3- shift(`1', `2', `3', `4')
6502 error->m4trace: -3- shift(`2', `3', `4')
6504 error->m4trace: -3- shift(`3', `4')
6507 Note that the fixed version calls unquoted helper macros in
6508 '_foreachq' to trim elements immediately; those helper macros in turn
6509 must re-supply the layer of quotes lost in the macro invocation.
6510 Contrast the use of '_arg1q', which quotes the first list element, with
6511 '_arg1' of the earlier implementation that returned the first list
6512 element directly. Additionally, by calling the helper method
6513 immediately, the 'defn(`ITERATOR')' no longer contains unexpanded
6516 The astute m4 programmer might notice that the solution above still
6517 uses more memory and macro invocations, and thus more time, than
6518 strictly necessary. Note that '$2', which contains an arbitrarily long
6519 quoted list, is expanded and rescanned three times per iteration of
6520 '_foreachq'. Furthermore, every iteration of the algorithm effectively
6521 unboxes then reboxes the list, which costs a couple of macro
6522 invocations. It is possible to rewrite the algorithm for a bit more
6523 speed by swapping the order of the arguments to '_foreachq' in order to
6524 operate on an unboxed list in the first place, and by using the
6525 fixed-length '$#' instead of an arbitrary length list as the key to end
6526 recursion. The result is an overhead of six macro invocations per loop
6527 (excluding any macros in TEXT), instead of eight. This alternative
6528 approach is available as 'm4-1.4.17/examples/foreach3.m4':
6531 include(`foreachq3.m4')
6533 undivert(`foreachq3.m4')dnl
6535 =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
6536 =># quoted list, alternate improved version
6537 =>define(`foreachq', `ifelse(`$2', `', `',
6538 => `pushdef(`$1')_$0(`$1', `$3', `', $2)popdef(`$1')')')
6539 =>define(`_foreachq', `ifelse(`$#', `3', `',
6540 => `define(`$1', `$4')$2`'$0(`$1', `$2',
6541 => shift(shift(shift($@))))')')
6543 traceon(`shift')debugmode(`aq')
6545 foreachq(`x', ``1', `2', `3', `4'', `x
6548 error->m4trace: -4- shift(`x', `x
6549 error->', `', `1', `2', `3', `4')
6550 error->m4trace: -3- shift(`x
6551 error->', `', `1', `2', `3', `4')
6552 error->m4trace: -2- shift(`', `1', `2', `3', `4')
6554 error->m4trace: -4- shift(`x', `x
6555 error->', `1', `2', `3', `4')
6556 error->m4trace: -3- shift(`x
6557 error->', `1', `2', `3', `4')
6558 error->m4trace: -2- shift(`1', `2', `3', `4')
6560 error->m4trace: -4- shift(`x', `x
6561 error->', `2', `3', `4')
6562 error->m4trace: -3- shift(`x
6563 error->', `2', `3', `4')
6564 error->m4trace: -2- shift(`2', `3', `4')
6566 error->m4trace: -4- shift(`x', `x
6568 error->m4trace: -3- shift(`x
6570 error->m4trace: -2- shift(`3', `4')
6572 In the current version of M4, every instance of '$@' is rescanned as
6573 it is encountered. Thus, the 'foreachq3.m4' alternative uses much less
6574 memory than 'foreachq2.m4', and executes as much as 10% faster, since
6575 each iteration encounters fewer '$@'. However, the implementation of
6576 rescanning every byte in '$@' is quadratic in the number of bytes
6577 scanned (for example, making the broken version in 'foreachq.m4' cubic,
6578 rather than quadratic, in behavior). A future release of M4 will
6579 improve the underlying implementation by reusing results of previous
6580 scans, so that both styles of 'foreachq' can become linear in the number
6581 of bytes scanned. Notice how the implementation injects an empty
6582 argument prior to expanding '$2' within 'foreachq'; the helper macro
6583 '_foreachq' then ignores the third argument altogether, and ends
6584 recursion when there are three arguments left because there was nothing
6585 left to pass through 'shift'. Thus, each iteration only needs one
6586 'ifelse', rather than the two conditionals used in the version from
6589 So far, all of the implementations of 'foreachq' presented have been
6590 quadratic with M4 1.4.x. But 'forloop' is linear, because each
6591 iteration parses a constant amount of arguments. So, it is possible to
6592 design a variant that uses 'forloop' to do the iteration, then uses '$@'
6593 only once at the end, giving a linear result even with older M4
6594 implementations. This implementation relies on the GNU extension that
6595 '$10' expands to the tenth argument rather than the first argument
6596 concatenated with '0'. The trick is to define an intermediate macro
6597 that repeats the text 'm4_define(`$1', `$N')$2`'', with 'n' set to
6598 successive integers corresponding to each argument. The helper macro
6599 '_foreachq_' is needed in order to generate the literal sequences such
6600 as '$1' into the intermediate macro, rather than expanding them as the
6601 arguments of '_foreachq'. With this approach, no 'shift' calls are even
6602 needed! Even though there are seven macros of overhead per iteration
6603 instead of six in 'foreachq3.m4', the linear scaling is apparent at
6604 relatively small list sizes. However, this approach will need
6605 adjustment when a future version of M4 follows POSIX by no longer
6606 treating '$10' as the tenth argument; the anticipation is that '${10}'
6607 can be used instead, although that alternative syntax is not yet
6611 include(`foreachq4.m4')
6613 undivert(`foreachq4.m4')dnl
6614 =>include(`forloop2.m4')dnl
6616 =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
6617 =># quoted list, version based on forloop
6618 =>define(`foreachq',
6619 =>`ifelse(`$2', `', `', `_$0(`$1', `$3', $2)')')
6620 =>define(`_foreachq',
6621 =>`pushdef(`$1', forloop(`$1', `3', `$#',
6622 => `$0_(`1', `2', indir(`$1'))')`popdef(
6623 => `$1')')indir(`$1', $@)')
6624 =>define(`_foreachq_',
6625 =>``define(`$$1', `$$3')$$2`''')
6627 traceon(`shift')debugmode(`aq')
6629 foreachq(`x', ``1', `2', `3', `4'', `x
6636 For yet another approach, the improved version of 'foreach',
6637 available in 'm4-1.4.17/examples/foreach2.m4', simply overquotes the
6638 arguments to '_foreach' to begin with, using 'dquote_elt'. Then
6639 '_foreach' can just use '_arg1' to remove the extra layer of quoting
6640 that was added up front:
6643 include(`foreach2.m4')
6645 undivert(`foreach2.m4')dnl
6646 =>include(`quote.m4')dnl
6648 =># foreach(x, (item_1, item_2, ..., item_n), stmt)
6649 =># parenthesized list, improved version
6650 =>define(`foreach', `pushdef(`$1')_$0(`$1',
6651 => (dquote(dquote_elt$2)), `$3')popdef(`$1')')
6652 =>define(`_arg1', `$1')
6653 =>define(`_foreach', `ifelse(`$2', `(`')', `',
6654 => `define(`$1', _arg1$2)$3`'$0(`$1', (dquote(shift$2)), `$3')')')
6656 traceon(`shift')debugmode(`aq')
6658 foreach(`x', `(`1', `2', `3', `4')', `x
6660 error->m4trace: -4- shift(`1', `2', `3', `4')
6661 error->m4trace: -4- shift(`2', `3', `4')
6662 error->m4trace: -4- shift(`3', `4')
6664 error->m4trace: -3- shift(``1'', ``2'', ``3'', ``4'')
6666 error->m4trace: -3- shift(``2'', ``3'', ``4'')
6668 error->m4trace: -3- shift(``3'', ``4'')
6670 error->m4trace: -3- shift(``4'')
6672 It is likewise possible to write a variant of 'foreach' that performs
6673 in linear time on M4 1.4.x; the easiest method is probably writing a
6674 version of 'foreach' that unboxes its list, then invokes '_foreachq' as
6675 previously defined in 'foreachq4.m4'.
6677 In summary, recursion over list elements is trickier than it appeared
6678 at first glance, but provides a powerful idiom within 'm4' processing.
6679 As a final demonstration, both list styles are now able to handle
6680 several scenarios that would wreak havoc on one or both of the original
6681 implementations. This points out one other difference between the list
6682 styles. 'foreach' evaluates unquoted list elements only once, in
6683 preparation for calling '_foreach', similary for 'foreachq' as provided
6684 by 'foreachq3.m4' or 'foreachq4.m4'. But 'foreachq', as provided by
6685 'foreachq2.m4', evaluates unquoted list elements twice while visiting
6686 the first list element, once in '_arg1q' and once in '_rest'. When
6687 deciding which list style to use, one must take into account whether
6688 repeating the side effects of unquoted list elements will have any
6689 detrimental effects.
6692 include(`foreach2.m4')
6694 include(`foreachq2.m4')
6697 foreach(`x', `', `<x>') / foreachq(`x', `', `<x>')
6699 dnl 1-element list of empty element
6700 foreach(`x', `()', `<x>') / foreachq(`x', ``'', `<x>')
6702 dnl 2-element list of empty elements
6703 foreach(`x', `(`',`')', `<x>') / foreachq(`x', ``',`'', `<x>')
6705 dnl 1-element list of a comma
6706 foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', `<x>')
6708 dnl 2-element list of unbalanced parentheses
6709 foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>')
6711 define(`ab', `oops')dnl using defn(`iterator')
6712 foreach(`x', `(`a', `b')', `defn(`x')') /dnl
6713 foreachq(`x', ``a', `b'', `defn(`x')')
6715 define(`active', `ACT, IVE')
6719 dnl list of unquoted macros; expansion occurs before recursion
6720 foreach(`x', `(active, active)', `<x>
6722 error->m4trace: -4- active -> `ACT, IVE'
6723 error->m4trace: -4- active -> `ACT, IVE'
6728 foreachq(`x', `active, active', `<x>
6730 error->m4trace: -3- active -> `ACT, IVE'
6731 error->m4trace: -3- active -> `ACT, IVE'
6733 error->m4trace: -3- active -> `ACT, IVE'
6734 error->m4trace: -3- active -> `ACT, IVE'
6738 dnl list of quoted macros; expansion occurs during recursion
6739 foreach(`x', `(`active', `active')', `<x>
6741 error->m4trace: -1- active -> `ACT, IVE'
6743 error->m4trace: -1- active -> `ACT, IVE'
6745 foreachq(`x', ``active', `active'', `<x>
6747 error->m4trace: -1- active -> `ACT, IVE'
6749 error->m4trace: -1- active -> `ACT, IVE'
6751 dnl list of double-quoted macro names; no expansion
6752 foreach(`x', `(``active'', ``active'')', `<x>
6756 foreachq(`x', ```active'', ``active''', `<x>
6762 File: m4.info, Node: Improved copy, Next: Improved m4wrap, Prev: Improved foreach, Up: Answers
6764 17.4 Solution for 'copy'
6765 ========================
6767 The macro 'copy' presented above is unable to handle builtin tokens with
6768 M4 1.4.x, because it tries to pass the builtin token through the macro
6769 'curry', where it is silently flattened to an empty string (*note
6770 Composition::). Rather than using the problematic 'curry' to work
6771 around the limitation that 'stack_foreach' expects to invoke a macro
6772 that takes exactly one argument, we can write a new macro that lets us
6773 form the exact two-argument 'pushdef' call sequence needed, so that we
6774 are no longer passing a builtin token through a text macro.
6776 -- Composite: stack_foreach_sep (MACRO, PRE, POST, SEP)
6777 -- Composite: stack_foreach_sep_lifo (MACRO, PRE, POST, SEP)
6778 For each of the 'pushdef' definitions associated with MACRO, expand
6779 the sequence 'PRE`'definition`'POST'. Additionally, expand SEP
6780 between definitions. 'stack_foreach_sep' visits the oldest
6781 definition first, while 'stack_foreach_sep_lifo' visits the current
6782 definition first. The expansion may dereference MACRO, but should
6783 not modify it. There are a few special macros, such as 'defn',
6784 which cannot be used as the MACRO parameter.
6786 Note that 'stack_foreach(`MACRO', `ACTION')' is equivalent to
6787 'stack_foreach_sep(`MACRO', `ACTION(', `)')'. By supplying explicit
6788 parentheses, split among the PRE and POST arguments to
6789 'stack_foreach_sep', it is now possible to construct macro calls with
6790 more than one argument, without passing builtin tokens through a macro
6791 call. It is likewise possible to directly reference the stack
6792 definitions without a macro call, by leaving PRE and POST empty. Thus,
6793 in addition to fixing 'copy' on builtin tokens, it also executes with
6794 fewer macro invocations.
6796 The new macro also adds a separator that is only output after the
6797 first iteration of the helper '_stack_reverse_sep', implemented by
6798 prepending the original SEP to PRE and omitting a SEP argument in
6799 subsequent iterations. Note that the empty string that separates SEP
6800 from PRE is provided as part of the fourth argument when originally
6801 calling '_stack_reverse_sep', and not by writing '$4`'$3' as the third
6802 argument in the recursive call; while the other approach would give the
6803 same output, it does so at the expense of increasing the argument size
6804 on each iteration of '_stack_reverse_sep', which results in quadratic
6805 instead of linear execution time. The improved stack walking macros are
6806 available in 'm4-1.4.17/examples/stack_sep.m4':
6809 include(`stack_sep.m4')
6811 define(`copy', `ifdef(`$2', `errprint(`$2 already defined
6813 `stack_foreach_sep(`$1', `pushdef(`$2',', `)')')')dnl
6814 pushdef(`a', `1')pushdef(`a', defn(`divnum'))
6824 pushdef(`c', `1')pushdef(`c', `2')
6826 stack_foreach_sep_lifo(`c', `', `', `, ')
6828 undivert(`stack_sep.m4')dnl
6830 =># stack_foreach_sep(macro, pre, post, sep)
6831 =># Invoke PRE`'defn`'POST with a single argument of each definition
6832 =># from the definition stack of MACRO, starting with the oldest, and
6833 =># separated by SEP between definitions.
6834 =>define(`stack_foreach_sep',
6835 =>`_stack_reverse_sep(`$1', `tmp-$1')'dnl
6836 =>`_stack_reverse_sep(`tmp-$1', `$1', `$2`'defn(`$1')$3', `$4`'')')
6837 =># stack_foreach_sep_lifo(macro, pre, post, sep)
6838 =># Like stack_foreach_sep, but starting with the newest definition.
6839 =>define(`stack_foreach_sep_lifo',
6840 =>`_stack_reverse_sep(`$1', `tmp-$1', `$2`'defn(`$1')$3', `$4`'')'dnl
6841 =>`_stack_reverse_sep(`tmp-$1', `$1')')
6842 =>define(`_stack_reverse_sep',
6843 =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0(
6844 => `$1', `$2', `$4$3')')')
6848 File: m4.info, Node: Improved m4wrap, Next: Improved cleardivert, Prev: Improved copy, Up: Answers
6850 17.5 Solution for 'm4wrap'
6851 ==========================
6853 The replacement 'm4wrap' versions presented above, designed to guarantee
6854 FIFO or LIFO order regardless of the underlying M4 implementation, share
6855 a bug when dealing with wrapped text that looks like parameter
6856 expansion. Note how the invocation of 'm4wrapN' interprets these
6857 parameters, while using the builtin preserves them for their intended
6861 include(`wraplifo.m4')
6863 m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
6866 builtin(`m4wrap', ``'define(`bar', ``$0:'-$1-$*-$#-')bar(`a', `b')
6873 Additionally, the computation of '_m4wrap_level' and creation of
6874 multiple 'm4wrapN' placeholders in the original examples is more
6875 expensive in time and memory than strictly necessary. Notice how the
6876 improved version grabs the wrapped text via 'defn' to avoid parameter
6877 expansion, then undefines '_m4wrap_text', before stripping a level of
6878 quotes with '_arg1' to expand the text. That way, each level of
6879 wrapping reuses the single placeholder, which starts each nesting level
6880 in an undefined state.
6882 Finally, it is worth emulating the GNU M4 extension of saving all
6883 arguments to 'm4wrap', separated by a space, rather than saving just the
6884 first argument. This is done with the 'join' macro documented
6885 previously (*note Shift::). The improved LIFO example is shipped as
6886 'm4-1.4.17/examples/wraplifo2.m4', and can easily be converted to a FIFO
6887 solution by swapping the adjacent invocations of 'joinall' and 'defn'.
6890 include(`wraplifo2.m4')
6892 undivert(`wraplifo2.m4')dnl
6893 =>dnl Redefine m4wrap to have LIFO semantics, improved example.
6894 =>include(`join.m4')dnl
6895 =>define(`_m4wrap', defn(`m4wrap'))dnl
6896 =>define(`_arg1', `$1')dnl
6898 =>`ifdef(`_$0_text',
6899 => `define(`_$0_text', joinall(` ', $@)defn(`_$0_text'))',
6900 => `_$0(`_arg1(defn(`_$0_text')undefine(`_$0_text'))')dnl
6901 =>define(`_$0_text', joinall(` ', $@))')')dnl
6902 m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
6906 m4wrap(`nested', `', `$@
6915 File: m4.info, Node: Improved cleardivert, Next: Improved capitalize, Prev: Improved m4wrap, Up: Answers
6917 17.6 Solution for 'cleardivert'
6918 ===============================
6920 The 'cleardivert' macro (*note Cleardivert::) cannot, as it stands, be
6921 called without arguments to clear all pending diversions. That is
6922 because using undivert with an empty string for an argument is different
6923 than using it with no arguments at all. Compare the earlier definition
6924 with one that takes the number of arguments into account:
6926 define(`cleardivert',
6927 `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
6937 define(`cleardivert',
6938 `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0',
6939 `undivert`'', `undivert($@)')divert(_num)popdef(`_num')')
6950 File: m4.info, Node: Improved capitalize, Next: Improved fatal_error, Prev: Improved cleardivert, Up: Answers
6952 17.7 Solution for 'capitalize'
6953 ==============================
6955 The 'capitalize' macro (*note Patsubst::) as presented earlier does not
6956 allow clients to follow the quoting rule of thumb. Consider the three
6957 macros 'active', 'Active', and 'ACTIVE', and the difference between
6958 calling 'capitalize' with the expansion of a macro, expanding the result
6959 of a case change, and changing the case of a double-quoted string:
6962 include(`capitalize.m4')dnl
6963 define(`active', `act1, ive')dnl
6964 define(`Active', `Act2, Ive')dnl
6965 define(`ACTIVE', `ACT3, IVE')dnl
6976 downcase(``ACTIVE'')
6980 capitalize(`active')
6982 capitalize(``active'')
6983 =>_capitalize(`active')
6988 capitalize(`active')
6991 First, when 'capitalize' is called with more than one argument, it
6992 was throwing away later arguments, whereas 'upcase' and 'downcase' used
6993 '$*' to collect them all. The fix is simple: use '$*' consistently.
6995 Next, with single-quoting, 'capitalize' outputs a single character, a
6996 set of quotes, then the rest of the characters, making it impossible to
6997 invoke 'Active' after the fact, and allowing the alternate macro 'A' to
6998 interfere. Here, the solution is to use additional quoting in the
6999 helper macros, then pass the final over-quoted output string through
7000 '_arg1' to remove the extra quoting and finally invoke the concatenated
7001 portions as a single string.
7003 Finally, when passed a double-quoted string, the nested macro
7004 '_capitalize' is never invoked because it ended up nested inside quotes.
7005 This one is the toughest to fix. In short, we have no idea how many
7006 levels of quotes are in effect on the substring being altered by
7007 'patsubst'. If the replacement string cannot be expressed entirely in
7008 terms of literal text and backslash substitutions, then we need a
7009 mechanism to guarantee that the helper macros are invoked outside of
7010 quotes. In other words, this sounds like a job for 'changequote' (*note
7011 Changequote::). By changing the active quoting characters, we can
7012 guarantee that replacement text injected by 'patsubst' always occurs in
7013 the middle of a string that has exactly one level of over-quoting using
7014 alternate quotes; so the replacement text closes the quoted string,
7015 invokes the helper macros, then reopens the quoted string. In turn,
7016 that means the replacement text has unbalanced quotes, necessitating
7017 another round of 'changequote'.
7019 In the fixed version below, (also shipped as
7020 'm4-1.4.17/examples/capitalize2.m4'), 'capitalize' uses the alternate
7021 quotes of '<<[' and ']>>' (the longer strings are chosen so as to be
7022 less likely to appear in the text being converted). The helpers
7023 '_to_alt' and '_from_alt' merely reduce the number of characters
7024 required to perform a 'changequote', since the definition changes twice.
7025 The outermost pair means that 'patsubst' and '_capitalize_alt' are
7026 invoked with alternate quoting; the innermost pair is used so that the
7027 third argument to 'patsubst' can contain an unbalanced ']>>'/'<<[' pair.
7028 Note that 'upcase' and 'downcase' must be redefined as '_upcase_alt' and
7029 '_downcase_alt', since they contain nested quotes but are invoked with
7030 the alternate quoting scheme in effect.
7033 include(`capitalize2.m4')dnl
7034 define(`active', `act1, ive')dnl
7035 define(`Active', `Act2, Ive')dnl
7036 define(`ACTIVE', `ACT3, IVE')dnl
7037 define(`A', `OOPS')dnl
7038 capitalize(active; `active'; ``active''; ```actIVE''')
7039 =>Act1,Ive; Act2, Ive; Active; `Active'
7040 undivert(`capitalize2.m4')dnl
7044 =># capitalize(text)
7045 =># change case of text, improved version
7046 =>define(`upcase', `translit(`$*', `a-z', `A-Z')')
7047 =>define(`downcase', `translit(`$*', `A-Z', `a-z')')
7048 =>define(`_arg1', `$1')
7049 =>define(`_to_alt', `changequote(`<<[', `]>>')')
7050 =>define(`_from_alt', `changequote(<<[`]>>, <<[']>>)')
7051 =>define(`_upcase_alt', `translit(<<[$*]>>, <<[a-z]>>, <<[A-Z]>>)')
7052 =>define(`_downcase_alt', `translit(<<[$*]>>, <<[A-Z]>>, <<[a-z]>>)')
7053 =>define(`_capitalize_alt',
7054 => `regexp(<<[$1]>>, <<[^\(\w\)\(\w*\)]>>,
7055 => <<[_upcase_alt(<<[<<[\1]>>]>>)_downcase_alt(<<[<<[\2]>>]>>)]>>)')
7056 =>define(`capitalize',
7057 => `_arg1(_to_alt()patsubst(<<[<<[$*]>>]>>, <<[\w+]>>,
7058 => _from_alt()`]>>_$0_alt(<<[\&]>>)<<['_to_alt())_from_alt())')
7062 File: m4.info, Node: Improved fatal_error, Prev: Improved capitalize, Up: Answers
7064 17.8 Solution for 'fatal_error'
7065 ===============================
7067 The 'fatal_error' macro (*note M4exit::) is not robust to versions of
7068 GNU M4 earlier than 1.4.8, where invoking '__file__' (*note Location::)
7069 inside 'm4wrap' would result in an empty string, and '__line__' resulted
7070 in '0' even though all files start at line 1. Furthermore, versions
7071 earlier than 1.4.6 did not support the '__program__' macro. If you want
7072 'fatal_error' to work across the entire 1.4.x release series, a better
7073 implementation would be:
7075 define(`fatal_error',
7076 `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl
7077 `:ifelse(__line__, `0', `',
7078 `__file__:__line__:')` fatal error: $*
7081 m4wrap(`divnum(`demo of internal message')
7082 fatal_error(`inside wrapped text')')
7085 error->m4:stdin:6: Warning: excess arguments to builtin `divnum' ignored
7087 error->m4:stdin:6: fatal error: inside wrapped text
7090 File: m4.info, Node: Copying This Package, Next: Copying This Manual, Prev: Answers, Up: Top
7092 Appendix A How to make copies of the overall M4 package
7093 *******************************************************
7095 This appendix covers the license for copying the source code of the
7096 overall M4 package. This manual is under a different set of
7097 restrictions, covered later (*note Copying This Manual::).
7101 * GNU General Public License:: License for copying the M4 package
7104 File: m4.info, Node: GNU General Public License, Up: Copying This Package
7106 A.1 License for copying the M4 package
7107 ======================================
7109 Version 3, 29 June 2007
7111 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
7113 Everyone is permitted to copy and distribute verbatim copies of this
7114 license document, but changing it is not allowed.
7119 The GNU General Public License is a free, copyleft license for software
7120 and other kinds of works.
7122 The licenses for most software and other practical works are designed
7123 to take away your freedom to share and change the works. By contrast,
7124 the GNU General Public License is intended to guarantee your freedom to
7125 share and change all versions of a program--to make sure it remains free
7126 software for all its users. We, the Free Software Foundation, use the
7127 GNU General Public License for most of our software; it applies also to
7128 any other work released this way by its authors. You can apply it to
7131 When we speak of free software, we are referring to freedom, not
7132 price. Our General Public Licenses are designed to make sure that you
7133 have the freedom to distribute copies of free software (and charge for
7134 them if you wish), that you receive source code or can get it if you
7135 want it, that you can change the software or use pieces of it in new
7136 free programs, and that you know you can do these things.
7138 To protect your rights, we need to prevent others from denying you
7139 these rights or asking you to surrender the rights. Therefore, you have
7140 certain responsibilities if you distribute copies of the software, or if
7141 you modify it: responsibilities to respect the freedom of others.
7143 For example, if you distribute copies of such a program, whether
7144 gratis or for a fee, you must pass on to the recipients the same
7145 freedoms that you received. You must make sure that they, too, receive
7146 or can get the source code. And you must show them these terms so they
7149 Developers that use the GNU GPL protect your rights with two steps:
7150 (1) assert copyright on the software, and (2) offer you this License
7151 giving you legal permission to copy, distribute and/or modify it.
7153 For the developers' and authors' protection, the GPL clearly explains
7154 that there is no warranty for this free software. For both users' and
7155 authors' sake, the GPL requires that modified versions be marked as
7156 changed, so that their problems will not be attributed erroneously to
7157 authors of previous versions.
7159 Some devices are designed to deny users access to install or run
7160 modified versions of the software inside them, although the manufacturer
7161 can do so. This is fundamentally incompatible with the aim of
7162 protecting users' freedom to change the software. The systematic
7163 pattern of such abuse occurs in the area of products for individuals to
7164 use, which is precisely where it is most unacceptable. Therefore, we
7165 have designed this version of the GPL to prohibit the practice for those
7166 products. If such problems arise substantially in other domains, we
7167 stand ready to extend this provision to those domains in future versions
7168 of the GPL, as needed to protect the freedom of users.
7170 Finally, every program is threatened constantly by software patents.
7171 States should not allow patents to restrict development and use of
7172 software on general-purpose computers, but in those that do, we wish to
7173 avoid the special danger that patents applied to a free program could
7174 make it effectively proprietary. To prevent this, the GPL assures that
7175 patents cannot be used to render the program non-free.
7177 The precise terms and conditions for copying, distribution and
7178 modification follow.
7180 TERMS AND CONDITIONS
7181 ====================
7185 "This License" refers to version 3 of the GNU General Public
7188 "Copyright" also means copyright-like laws that apply to other
7189 kinds of works, such as semiconductor masks.
7191 "The Program" refers to any copyrightable work licensed under this
7192 License. Each licensee is addressed as "you". "Licensees" and
7193 "recipients" may be individuals or organizations.
7195 To "modify" a work means to copy from or adapt all or part of the
7196 work in a fashion requiring copyright permission, other than the
7197 making of an exact copy. The resulting work is called a "modified
7198 version" of the earlier work or a work "based on" the earlier work.
7200 A "covered work" means either the unmodified Program or a work
7201 based on the Program.
7203 To "propagate" a work means to do anything with it that, without
7204 permission, would make you directly or secondarily liable for
7205 infringement under applicable copyright law, except executing it on
7206 a computer or modifying a private copy. Propagation includes
7207 copying, distribution (with or without modification), making
7208 available to the public, and in some countries other activities as
7211 To "convey" a work means any kind of propagation that enables other
7212 parties to make or receive copies. Mere interaction with a user
7213 through a computer network, with no transfer of a copy, is not
7216 An interactive user interface displays "Appropriate Legal Notices"
7217 to the extent that it includes a convenient and prominently visible
7218 feature that (1) displays an appropriate copyright notice, and (2)
7219 tells the user that there is no warranty for the work (except to
7220 the extent that warranties are provided), that licensees may convey
7221 the work under this License, and how to view a copy of this
7222 License. If the interface presents a list of user commands or
7223 options, such as a menu, a prominent item in the list meets this
7228 The "source code" for a work means the preferred form of the work
7229 for making modifications to it. "Object code" means any non-source
7232 A "Standard Interface" means an interface that either is an
7233 official standard defined by a recognized standards body, or, in
7234 the case of interfaces specified for a particular programming
7235 language, one that is widely used among developers working in that
7238 The "System Libraries" of an executable work include anything,
7239 other than the work as a whole, that (a) is included in the normal
7240 form of packaging a Major Component, but which is not part of that
7241 Major Component, and (b) serves only to enable use of the work with
7242 that Major Component, or to implement a Standard Interface for
7243 which an implementation is available to the public in source code
7244 form. A "Major Component", in this context, means a major
7245 essential component (kernel, window system, and so on) of the
7246 specific operating system (if any) on which the executable work
7247 runs, or a compiler used to produce the work, or an object code
7248 interpreter used to run it.
7250 The "Corresponding Source" for a work in object code form means all
7251 the source code needed to generate, install, and (for an executable
7252 work) run the object code and to modify the work, including scripts
7253 to control those activities. However, it does not include the
7254 work's System Libraries, or general-purpose tools or generally
7255 available free programs which are used unmodified in performing
7256 those activities but which are not part of the work. For example,
7257 Corresponding Source includes interface definition files associated
7258 with source files for the work, and the source code for shared
7259 libraries and dynamically linked subprograms that the work is
7260 specifically designed to require, such as by intimate data
7261 communication or control flow between those subprograms and other
7264 The Corresponding Source need not include anything that users can
7265 regenerate automatically from other parts of the Corresponding
7268 The Corresponding Source for a work in source code form is that
7271 2. Basic Permissions.
7273 All rights granted under this License are granted for the term of
7274 copyright on the Program, and are irrevocable provided the stated
7275 conditions are met. This License explicitly affirms your unlimited
7276 permission to run the unmodified Program. The output from running
7277 a covered work is covered by this License only if the output, given
7278 its content, constitutes a covered work. This License acknowledges
7279 your rights of fair use or other equivalent, as provided by
7282 You may make, run and propagate covered works that you do not
7283 convey, without conditions so long as your license otherwise
7284 remains in force. You may convey covered works to others for the
7285 sole purpose of having them make modifications exclusively for you,
7286 or provide you with facilities for running those works, provided
7287 that you comply with the terms of this License in conveying all
7288 material for which you do not control copyright. Those thus making
7289 or running the covered works for you must do so exclusively on your
7290 behalf, under your direction and control, on terms that prohibit
7291 them from making any copies of your copyrighted material outside
7292 their relationship with you.
7294 Conveying under any other circumstances is permitted solely under
7295 the conditions stated below. Sublicensing is not allowed; section
7296 10 makes it unnecessary.
7298 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
7300 No covered work shall be deemed part of an effective technological
7301 measure under any applicable law fulfilling obligations under
7302 article 11 of the WIPO copyright treaty adopted on 20 December
7303 1996, or similar laws prohibiting or restricting circumvention of
7306 When you convey a covered work, you waive any legal power to forbid
7307 circumvention of technological measures to the extent such
7308 circumvention is effected by exercising rights under this License
7309 with respect to the covered work, and you disclaim any intention to
7310 limit operation or modification of the work as a means of
7311 enforcing, against the work's users, your or third parties' legal
7312 rights to forbid circumvention of technological measures.
7314 4. Conveying Verbatim Copies.
7316 You may convey verbatim copies of the Program's source code as you
7317 receive it, in any medium, provided that you conspicuously and
7318 appropriately publish on each copy an appropriate copyright notice;
7319 keep intact all notices stating that this License and any
7320 non-permissive terms added in accord with section 7 apply to the
7321 code; keep intact all notices of the absence of any warranty; and
7322 give all recipients a copy of this License along with the Program.
7324 You may charge any price or no price for each copy that you convey,
7325 and you may offer support or warranty protection for a fee.
7327 5. Conveying Modified Source Versions.
7329 You may convey a work based on the Program, or the modifications to
7330 produce it from the Program, in the form of source code under the
7331 terms of section 4, provided that you also meet all of these
7334 a. The work must carry prominent notices stating that you
7335 modified it, and giving a relevant date.
7337 b. The work must carry prominent notices stating that it is
7338 released under this License and any conditions added under
7339 section 7. This requirement modifies the requirement in
7340 section 4 to "keep intact all notices".
7342 c. You must license the entire work, as a whole, under this
7343 License to anyone who comes into possession of a copy. This
7344 License will therefore apply, along with any applicable
7345 section 7 additional terms, to the whole of the work, and all
7346 its parts, regardless of how they are packaged. This License
7347 gives no permission to license the work in any other way, but
7348 it does not invalidate such permission if you have separately
7351 d. If the work has interactive user interfaces, each must display
7352 Appropriate Legal Notices; however, if the Program has
7353 interactive interfaces that do not display Appropriate Legal
7354 Notices, your work need not make them do so.
7356 A compilation of a covered work with other separate and independent
7357 works, which are not by their nature extensions of the covered
7358 work, and which are not combined with it such as to form a larger
7359 program, in or on a volume of a storage or distribution medium, is
7360 called an "aggregate" if the compilation and its resulting
7361 copyright are not used to limit the access or legal rights of the
7362 compilation's users beyond what the individual works permit.
7363 Inclusion of a covered work in an aggregate does not cause this
7364 License to apply to the other parts of the aggregate.
7366 6. Conveying Non-Source Forms.
7368 You may convey a covered work in object code form under the terms
7369 of sections 4 and 5, provided that you also convey the
7370 machine-readable Corresponding Source under the terms of this
7371 License, in one of these ways:
7373 a. Convey the object code in, or embodied in, a physical product
7374 (including a physical distribution medium), accompanied by the
7375 Corresponding Source fixed on a durable physical medium
7376 customarily used for software interchange.
7378 b. Convey the object code in, or embodied in, a physical product
7379 (including a physical distribution medium), accompanied by a
7380 written offer, valid for at least three years and valid for as
7381 long as you offer spare parts or customer support for that
7382 product model, to give anyone who possesses the object code
7383 either (1) a copy of the Corresponding Source for all the
7384 software in the product that is covered by this License, on a
7385 durable physical medium customarily used for software
7386 interchange, for a price no more than your reasonable cost of
7387 physically performing this conveying of source, or (2) access
7388 to copy the Corresponding Source from a network server at no
7391 c. Convey individual copies of the object code with a copy of the
7392 written offer to provide the Corresponding Source. This
7393 alternative is allowed only occasionally and noncommercially,
7394 and only if you received the object code with such an offer,
7395 in accord with subsection 6b.
7397 d. Convey the object code by offering access from a designated
7398 place (gratis or for a charge), and offer equivalent access to
7399 the Corresponding Source in the same way through the same
7400 place at no further charge. You need not require recipients
7401 to copy the Corresponding Source along with the object code.
7402 If the place to copy the object code is a network server, the
7403 Corresponding Source may be on a different server (operated by
7404 you or a third party) that supports equivalent copying
7405 facilities, provided you maintain clear directions next to the
7406 object code saying where to find the Corresponding Source.
7407 Regardless of what server hosts the Corresponding Source, you
7408 remain obligated to ensure that it is available for as long as
7409 needed to satisfy these requirements.
7411 e. Convey the object code using peer-to-peer transmission,
7412 provided you inform other peers where the object code and
7413 Corresponding Source of the work are being offered to the
7414 general public at no charge under subsection 6d.
7416 A separable portion of the object code, whose source code is
7417 excluded from the Corresponding Source as a System Library, need
7418 not be included in conveying the object code work.
7420 A "User Product" is either (1) a "consumer product", which means
7421 any tangible personal property which is normally used for personal,
7422 family, or household purposes, or (2) anything designed or sold for
7423 incorporation into a dwelling. In determining whether a product is
7424 a consumer product, doubtful cases shall be resolved in favor of
7425 coverage. For a particular product received by a particular user,
7426 "normally used" refers to a typical or common use of that class of
7427 product, regardless of the status of the particular user or of the
7428 way in which the particular user actually uses, or expects or is
7429 expected to use, the product. A product is a consumer product
7430 regardless of whether the product has substantial commercial,
7431 industrial or non-consumer uses, unless such uses represent the
7432 only significant mode of use of the product.
7434 "Installation Information" for a User Product means any methods,
7435 procedures, authorization keys, or other information required to
7436 install and execute modified versions of a covered work in that
7437 User Product from a modified version of its Corresponding Source.
7438 The information must suffice to ensure that the continued
7439 functioning of the modified object code is in no case prevented or
7440 interfered with solely because modification has been made.
7442 If you convey an object code work under this section in, or with,
7443 or specifically for use in, a User Product, and the conveying
7444 occurs as part of a transaction in which the right of possession
7445 and use of the User Product is transferred to the recipient in
7446 perpetuity or for a fixed term (regardless of how the transaction
7447 is characterized), the Corresponding Source conveyed under this
7448 section must be accompanied by the Installation Information. But
7449 this requirement does not apply if neither you nor any third party
7450 retains the ability to install modified object code on the User
7451 Product (for example, the work has been installed in ROM).
7453 The requirement to provide Installation Information does not
7454 include a requirement to continue to provide support service,
7455 warranty, or updates for a work that has been modified or installed
7456 by the recipient, or for the User Product in which it has been
7457 modified or installed. Access to a network may be denied when the
7458 modification itself materially and adversely affects the operation
7459 of the network or violates the rules and protocols for
7460 communication across the network.
7462 Corresponding Source conveyed, and Installation Information
7463 provided, in accord with this section must be in a format that is
7464 publicly documented (and with an implementation available to the
7465 public in source code form), and must require no special password
7466 or key for unpacking, reading or copying.
7468 7. Additional Terms.
7470 "Additional permissions" are terms that supplement the terms of
7471 this License by making exceptions from one or more of its
7472 conditions. Additional permissions that are applicable to the
7473 entire Program shall be treated as though they were included in
7474 this License, to the extent that they are valid under applicable
7475 law. If additional permissions apply only to part of the Program,
7476 that part may be used separately under those permissions, but the
7477 entire Program remains governed by this License without regard to
7478 the additional permissions.
7480 When you convey a copy of a covered work, you may at your option
7481 remove any additional permissions from that copy, or from any part
7482 of it. (Additional permissions may be written to require their own
7483 removal in certain cases when you modify the work.) You may place
7484 additional permissions on material, added by you to a covered work,
7485 for which you have or can give appropriate copyright permission.
7487 Notwithstanding any other provision of this License, for material
7488 you add to a covered work, you may (if authorized by the copyright
7489 holders of that material) supplement the terms of this License with
7492 a. Disclaiming warranty or limiting liability differently from
7493 the terms of sections 15 and 16 of this License; or
7495 b. Requiring preservation of specified reasonable legal notices
7496 or author attributions in that material or in the Appropriate
7497 Legal Notices displayed by works containing it; or
7499 c. Prohibiting misrepresentation of the origin of that material,
7500 or requiring that modified versions of such material be marked
7501 in reasonable ways as different from the original version; or
7503 d. Limiting the use for publicity purposes of names of licensors
7504 or authors of the material; or
7506 e. Declining to grant rights under trademark law for use of some
7507 trade names, trademarks, or service marks; or
7509 f. Requiring indemnification of licensors and authors of that
7510 material by anyone who conveys the material (or modified
7511 versions of it) with contractual assumptions of liability to
7512 the recipient, for any liability that these contractual
7513 assumptions directly impose on those licensors and authors.
7515 All other non-permissive additional terms are considered "further
7516 restrictions" within the meaning of section 10. If the Program as
7517 you received it, or any part of it, contains a notice stating that
7518 it is governed by this License along with a term that is a further
7519 restriction, you may remove that term. If a license document
7520 contains a further restriction but permits relicensing or conveying
7521 under this License, you may add to a covered work material governed
7522 by the terms of that license document, provided that the further
7523 restriction does not survive such relicensing or conveying.
7525 If you add terms to a covered work in accord with this section, you
7526 must place, in the relevant source files, a statement of the
7527 additional terms that apply to those files, or a notice indicating
7528 where to find the applicable terms.
7530 Additional terms, permissive or non-permissive, may be stated in
7531 the form of a separately written license, or stated as exceptions;
7532 the above requirements apply either way.
7536 You may not propagate or modify a covered work except as expressly
7537 provided under this License. Any attempt otherwise to propagate or
7538 modify it is void, and will automatically terminate your rights
7539 under this License (including any patent licenses granted under the
7540 third paragraph of section 11).
7542 However, if you cease all violation of this License, then your
7543 license from a particular copyright holder is reinstated (a)
7544 provisionally, unless and until the copyright holder explicitly and
7545 finally terminates your license, and (b) permanently, if the
7546 copyright holder fails to notify you of the violation by some
7547 reasonable means prior to 60 days after the cessation.
7549 Moreover, your license from a particular copyright holder is
7550 reinstated permanently if the copyright holder notifies you of the
7551 violation by some reasonable means, this is the first time you have
7552 received notice of violation of this License (for any work) from
7553 that copyright holder, and you cure the violation prior to 30 days
7554 after your receipt of the notice.
7556 Termination of your rights under this section does not terminate
7557 the licenses of parties who have received copies or rights from you
7558 under this License. If your rights have been terminated and not
7559 permanently reinstated, you do not qualify to receive new licenses
7560 for the same material under section 10.
7562 9. Acceptance Not Required for Having Copies.
7564 You are not required to accept this License in order to receive or
7565 run a copy of the Program. Ancillary propagation of a covered work
7566 occurring solely as a consequence of using peer-to-peer
7567 transmission to receive a copy likewise does not require
7568 acceptance. However, nothing other than this License grants you
7569 permission to propagate or modify any covered work. These actions
7570 infringe copyright if you do not accept this License. Therefore,
7571 by modifying or propagating a covered work, you indicate your
7572 acceptance of this License to do so.
7574 10. Automatic Licensing of Downstream Recipients.
7576 Each time you convey a covered work, the recipient automatically
7577 receives a license from the original licensors, to run, modify and
7578 propagate that work, subject to this License. You are not
7579 responsible for enforcing compliance by third parties with this
7582 An "entity transaction" is a transaction transferring control of an
7583 organization, or substantially all assets of one, or subdividing an
7584 organization, or merging organizations. If propagation of a
7585 covered work results from an entity transaction, each party to that
7586 transaction who receives a copy of the work also receives whatever
7587 licenses to the work the party's predecessor in interest had or
7588 could give under the previous paragraph, plus a right to possession
7589 of the Corresponding Source of the work from the predecessor in
7590 interest, if the predecessor has it or can get it with reasonable
7593 You may not impose any further restrictions on the exercise of the
7594 rights granted or affirmed under this License. For example, you
7595 may not impose a license fee, royalty, or other charge for exercise
7596 of rights granted under this License, and you may not initiate
7597 litigation (including a cross-claim or counterclaim in a lawsuit)
7598 alleging that any patent claim is infringed by making, using,
7599 selling, offering for sale, or importing the Program or any portion
7604 A "contributor" is a copyright holder who authorizes use under this
7605 License of the Program or a work on which the Program is based.
7606 The work thus licensed is called the contributor's "contributor
7609 A contributor's "essential patent claims" are all patent claims
7610 owned or controlled by the contributor, whether already acquired or
7611 hereafter acquired, that would be infringed by some manner,
7612 permitted by this License, of making, using, or selling its
7613 contributor version, but do not include claims that would be
7614 infringed only as a consequence of further modification of the
7615 contributor version. For purposes of this definition, "control"
7616 includes the right to grant patent sublicenses in a manner
7617 consistent with the requirements of this License.
7619 Each contributor grants you a non-exclusive, worldwide,
7620 royalty-free patent license under the contributor's essential
7621 patent claims, to make, use, sell, offer for sale, import and
7622 otherwise run, modify and propagate the contents of its contributor
7625 In the following three paragraphs, a "patent license" is any
7626 express agreement or commitment, however denominated, not to
7627 enforce a patent (such as an express permission to practice a
7628 patent or covenant not to sue for patent infringement). To "grant"
7629 such a patent license to a party means to make such an agreement or
7630 commitment not to enforce a patent against the party.
7632 If you convey a covered work, knowingly relying on a patent
7633 license, and the Corresponding Source of the work is not available
7634 for anyone to copy, free of charge and under the terms of this
7635 License, through a publicly available network server or other
7636 readily accessible means, then you must either (1) cause the
7637 Corresponding Source to be so available, or (2) arrange to deprive
7638 yourself of the benefit of the patent license for this particular
7639 work, or (3) arrange, in a manner consistent with the requirements
7640 of this License, to extend the patent license to downstream
7641 recipients. "Knowingly relying" means you have actual knowledge
7642 that, but for the patent license, your conveying the covered work
7643 in a country, or your recipient's use of the covered work in a
7644 country, would infringe one or more identifiable patents in that
7645 country that you have reason to believe are valid.
7647 If, pursuant to or in connection with a single transaction or
7648 arrangement, you convey, or propagate by procuring conveyance of, a
7649 covered work, and grant a patent license to some of the parties
7650 receiving the covered work authorizing them to use, propagate,
7651 modify or convey a specific copy of the covered work, then the
7652 patent license you grant is automatically extended to all
7653 recipients of the covered work and works based on it.
7655 A patent license is "discriminatory" if it does not include within
7656 the scope of its coverage, prohibits the exercise of, or is
7657 conditioned on the non-exercise of one or more of the rights that
7658 are specifically granted under this License. You may not convey a
7659 covered work if you are a party to an arrangement with a third
7660 party that is in the business of distributing software, under which
7661 you make payment to the third party based on the extent of your
7662 activity of conveying the work, and under which the third party
7663 grants, to any of the parties who would receive the covered work
7664 from you, a discriminatory patent license (a) in connection with
7665 copies of the covered work conveyed by you (or copies made from
7666 those copies), or (b) primarily for and in connection with specific
7667 products or compilations that contain the covered work, unless you
7668 entered into that arrangement, or that patent license was granted,
7669 prior to 28 March 2007.
7671 Nothing in this License shall be construed as excluding or limiting
7672 any implied license or other defenses to infringement that may
7673 otherwise be available to you under applicable patent law.
7675 12. No Surrender of Others' Freedom.
7677 If conditions are imposed on you (whether by court order, agreement
7678 or otherwise) that contradict the conditions of this License, they
7679 do not excuse you from the conditions of this License. If you
7680 cannot convey a covered work so as to satisfy simultaneously your
7681 obligations under this License and any other pertinent obligations,
7682 then as a consequence you may not convey it at all. For example,
7683 if you agree to terms that obligate you to collect a royalty for
7684 further conveying from those to whom you convey the Program, the
7685 only way you could satisfy both those terms and this License would
7686 be to refrain entirely from conveying the Program.
7688 13. Use with the GNU Affero General Public License.
7690 Notwithstanding any other provision of this License, you have
7691 permission to link or combine any covered work with a work licensed
7692 under version 3 of the GNU Affero General Public License into a
7693 single combined work, and to convey the resulting work. The terms
7694 of this License will continue to apply to the part which is the
7695 covered work, but the special requirements of the GNU Affero
7696 General Public License, section 13, concerning interaction through
7697 a network will apply to the combination as such.
7699 14. Revised Versions of this License.
7701 The Free Software Foundation may publish revised and/or new
7702 versions of the GNU General Public License from time to time. Such
7703 new versions will be similar in spirit to the present version, but
7704 may differ in detail to address new problems or concerns.
7706 Each version is given a distinguishing version number. If the
7707 Program specifies that a certain numbered version of the GNU
7708 General Public License "or any later version" applies to it, you
7709 have the option of following the terms and conditions either of
7710 that numbered version or of any later version published by the Free
7711 Software Foundation. If the Program does not specify a version
7712 number of the GNU General Public License, you may choose any
7713 version ever published by the Free Software Foundation.
7715 If the Program specifies that a proxy can decide which future
7716 versions of the GNU General Public License can be used, that
7717 proxy's public statement of acceptance of a version permanently
7718 authorizes you to choose that version for the Program.
7720 Later license versions may give you additional or different
7721 permissions. However, no additional obligations are imposed on any
7722 author or copyright holder as a result of your choosing to follow a
7725 15. Disclaimer of Warranty.
7727 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
7728 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
7729 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
7730 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
7731 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
7732 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
7733 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
7734 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
7735 NECESSARY SERVICING, REPAIR OR CORRECTION.
7737 16. Limitation of Liability.
7739 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
7740 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
7741 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
7742 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
7743 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
7744 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
7745 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
7746 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
7747 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
7748 THE POSSIBILITY OF SUCH DAMAGES.
7750 17. Interpretation of Sections 15 and 16.
7752 If the disclaimer of warranty and limitation of liability provided
7753 above cannot be given local legal effect according to their terms,
7754 reviewing courts shall apply local law that most closely
7755 approximates an absolute waiver of all civil liability in
7756 connection with the Program, unless a warranty or assumption of
7757 liability accompanies a copy of the Program in return for a fee.
7759 END OF TERMS AND CONDITIONS
7760 ===========================
7762 How to Apply These Terms to Your New Programs
7763 =============================================
7765 If you develop a new program, and you want it to be of the greatest
7766 possible use to the public, the best way to achieve this is to make it
7767 free software which everyone can redistribute and change under these
7770 To do so, attach the following notices to the program. It is safest
7771 to attach them to the start of each source file to most effectively
7772 state the exclusion of warranty; and each file should have at least the
7773 "copyright" line and a pointer to where the full notice is found.
7775 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
7776 Copyright (C) YEAR NAME OF AUTHOR
7778 This program is free software: you can redistribute it and/or modify
7779 it under the terms of the GNU General Public License as published by
7780 the Free Software Foundation, either version 3 of the License, or (at
7781 your option) any later version.
7783 This program is distributed in the hope that it will be useful, but
7784 WITHOUT ANY WARRANTY; without even the implied warranty of
7785 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7786 General Public License for more details.
7788 You should have received a copy of the GNU General Public License
7789 along with this program. If not, see <http://www.gnu.org/licenses/>.
7791 Also add information on how to contact you by electronic and paper
7794 If the program does terminal interaction, make it output a short
7795 notice like this when it starts in an interactive mode:
7797 PROGRAM Copyright (C) YEAR NAME OF AUTHOR
7798 This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
7799 This is free software, and you are welcome to redistribute it
7800 under certain conditions; type 'show c' for details.
7802 The hypothetical commands 'show w' and 'show c' should show the
7803 appropriate parts of the General Public License. Of course, your
7804 program's commands might be different; for a GUI interface, you would
7807 You should also get your employer (if you work as a programmer) or
7808 school, if any, to sign a "copyright disclaimer" for the program, if
7809 necessary. For more information on this, and how to apply and follow
7810 the GNU GPL, see <http://www.gnu.org/licenses/>.
7812 The GNU General Public License does not permit incorporating your
7813 program into proprietary programs. If your program is a subroutine
7814 library, you may consider it more useful to permit linking proprietary
7815 applications with the library. If this is what you want to do, use the
7816 GNU Lesser General Public License instead of this License. But first,
7817 please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.