1 This is m4.info, produced by makeinfo version 6.7 from m4.texi.
3 This manual (28 May 2021) is for GNU M4 (version 1.4.19), a package
4 containing an implementation of the m4 macro language.
6 Copyright © 1989–1994, 2004–2014, 2016–2017, 2020–2021 Free Software
9 Permission is granted to copy, distribute and/or modify this
10 document under the terms of the GNU Free Documentation License,
11 Version 1.3 or any later version published by the Free Software
12 Foundation; with no Invariant Sections, no Front-Cover Texts, and
13 no Back-Cover Texts. A copy of the license is included in the
14 section entitled “GNU Free Documentation License.”
15 INFO-DIR-SECTION Text creation and manipulation
17 * M4: (m4). A powerful macro processor.
21 File: m4.info, Node: Top, Next: Preliminaries, Up: (dir)
26 This manual (28 May 2021) is for GNU M4 (version 1.4.19), a package
27 containing an implementation of the m4 macro language.
29 Copyright © 1989–1994, 2004–2014, 2016–2017, 2020–2021 Free Software
32 Permission is granted to copy, distribute and/or modify this
33 document under the terms of the GNU Free Documentation License,
34 Version 1.3 or any later version published by the Free Software
35 Foundation; with no Invariant Sections, no Front-Cover Texts, and
36 no Back-Cover Texts. A copy of the license is included in the
37 section entitled “GNU Free Documentation License.”
39 GNU ‘m4’ is an implementation of the traditional UNIX macro
40 processor. It is mostly SVR4 compatible, although it has some
41 extensions (for example, handling more than 9 positional parameters to
42 macros). ‘m4’ also has builtin functions for including files, running
43 shell commands, doing arithmetic, etc. Autoconf needs GNU ‘m4’ for
44 generating ‘configure’ scripts, but not for running them.
46 GNU ‘m4’ was originally written by René Seindal, with subsequent
47 changes by François Pinard and other volunteers on the Internet. All
48 names and email addresses can be found in the files ‘m4-1.4.19/AUTHORS’
49 and ‘m4-1.4.19/THANKS’ from the GNU M4 distribution.
51 This is release 1.4.19. It is now considered stable: future releases
52 in the 1.4.x series are only meant to fix bugs, increase speed, or
53 improve documentation. However...
55 An experimental feature, which would improve ‘m4’ usefulness, allows
56 for changing the syntax for what is a “word” in ‘m4’. You should use:
57 ./configure --enable-changeword
58 if you want this feature compiled in. The current implementation slows
59 down ‘m4’ considerably and is hardly acceptable. In the future, ‘m4’
60 2.0 will come with a different set of new features that provide similar
61 capabilities, but without the inefficiencies, so changeword will go away
62 and _you should not count on it_.
66 * Preliminaries:: Introduction and preliminaries
67 * Invoking m4:: Invoking ‘m4’
68 * Syntax:: Lexical and syntactic conventions
70 * Macros:: How to invoke macros
71 * Definitions:: How to define new macros
72 * Conditionals:: Conditionals, loops, and recursion
74 * Debugging:: How to debug macros and input
76 * Input Control:: Input control
77 * File Inclusion:: File inclusion
78 * Diversions:: Diverting and undiverting output
80 * Text handling:: Macros for text handling
81 * Arithmetic:: Macros for doing arithmetic
82 * Shell commands:: Macros for running shell commands
83 * Miscellaneous:: Miscellaneous builtin macros
84 * Frozen files:: Fast loading of frozen state
86 * Compatibility:: Compatibility with other versions of ‘m4’
87 * Answers:: Correct version of some examples
89 * Copying This Package:: How to make copies of the overall M4 package
90 * Copying This Manual:: How to make copies of this manual
91 * Indices:: Indices of concepts and macros
93 — The Detailed Node Listing —
95 Introduction and preliminaries
97 * Intro:: Introduction to ‘m4’
98 * History:: Historical references
99 * Bugs:: Problems and bugs
100 * Manual:: Using this manual
104 * Operation modes:: Command line options for operation modes
105 * Preprocessor features:: Command line options for preprocessor features
106 * Limits control:: Command line options for limits control
107 * Frozen state:: Command line options for frozen state
108 * Debugging options:: Command line options for debugging
109 * Command line files:: Specifying input files on the command line
111 Lexical and syntactic conventions
113 * Names:: Macro names
114 * Quoted strings:: Quoting input to ‘m4’
115 * Comments:: Comments in ‘m4’ input
116 * Other tokens:: Other kinds of input tokens
117 * Input processing:: How ‘m4’ copies input to output
121 * Invocation:: Macro invocation
122 * Inhibiting Invocation:: Preventing macro invocation
123 * Macro Arguments:: Macro arguments
124 * Quoting Arguments:: On Quoting Arguments to macros
125 * Macro expansion:: Expanding macros
127 How to define new macros
129 * Define:: Defining a new macro
130 * Arguments:: Arguments to macros
131 * Pseudo Arguments:: Special arguments to macros
132 * Undefine:: Deleting a macro
133 * Defn:: Renaming macros
134 * Pushdef:: Temporarily redefining macros
136 * Indir:: Indirect call of macros
137 * Builtin:: Indirect call of builtins
139 Conditionals, loops, and recursion
141 * Ifdef:: Testing if a macro is defined
142 * Ifelse:: If-else construct, or multibranch
143 * Shift:: Recursion in ‘m4’
144 * Forloop:: Iteration by counting
145 * Foreach:: Iteration by list contents
146 * Stacks:: Working with definition stacks
147 * Composition:: Building macros with macros
149 How to debug macros and input
151 * Dumpdef:: Displaying macro definitions
152 * Trace:: Tracing macro calls
153 * Debug Levels:: Controlling debugging output
154 * Debug Output:: Saving debugging output
158 * Dnl:: Deleting whitespace in input
159 * Changequote:: Changing the quote characters
160 * Changecom:: Changing the comment delimiters
161 * Changeword:: Changing the lexical structure of words
162 * M4wrap:: Saving text until end of input
166 * Include:: Including named files
167 * Search Path:: Searching for include files
169 Diverting and undiverting output
171 * Divert:: Diverting output
172 * Undivert:: Undiverting output
173 * Divnum:: Diversion numbers
174 * Cleardivert:: Discarding diverted text
176 Macros for text handling
178 * Len:: Calculating length of strings
179 * Index macro:: Searching for substrings
180 * Regexp:: Searching for regular expressions
181 * Substr:: Extracting substrings
182 * Translit:: Translating characters
183 * Patsubst:: Substituting text by regular expression
184 * Format:: Formatting strings (printf-like)
186 Macros for doing arithmetic
188 * Incr:: Decrement and increment operators
189 * Eval:: Evaluating integer expressions
191 Macros for running shell commands
193 * Platform macros:: Determining the platform
194 * Syscmd:: Executing simple commands
195 * Esyscmd:: Reading the output of commands
196 * Sysval:: Exit status
197 * Mkstemp:: Making temporary files
199 Miscellaneous builtin macros
201 * Errprint:: Printing error messages
202 * Location:: Printing current location
203 * M4exit:: Exiting from ‘m4’
205 Fast loading of frozen state
207 * Using frozen files:: Using frozen files
208 * Frozen file format:: Frozen file format
210 Compatibility with other versions of ‘m4’
212 * Extensions:: Extensions in GNU M4
213 * Incompatibilities:: Facilities in System V m4 not in GNU M4
214 * Other Incompatibilities:: Other incompatibilities
216 Correct version of some examples
218 * Improved exch:: Solution for ‘exch’
219 * Improved forloop:: Solution for ‘forloop’
220 * Improved foreach:: Solution for ‘foreach’
221 * Improved copy:: Solution for ‘copy’
222 * Improved m4wrap:: Solution for ‘m4wrap’
223 * Improved cleardivert:: Solution for ‘cleardivert’
224 * Improved capitalize:: Solution for ‘capitalize’
225 * Improved fatal_error:: Solution for ‘fatal_error’
227 How to make copies of the overall M4 package
229 * GNU General Public License:: License for copying the M4 package
231 How to make copies of this manual
233 * GNU Free Documentation License:: License for copying this manual
235 Indices of concepts and macros
237 * Macro index:: Index for all ‘m4’ macros
238 * Concept index:: Index for many concepts
242 File: m4.info, Node: Preliminaries, Next: Invoking m4, Prev: Top, Up: Top
244 1 Introduction and preliminaries
245 ********************************
247 This first chapter explains what GNU ‘m4’ is, where ‘m4’ comes from, how
248 to read and use this documentation, how to call the ‘m4’ program, and
249 how to report bugs about it. It concludes by giving tips for reading
250 the remainder of the manual.
252 The following chapters then detail all the features of the ‘m4’
257 * Intro:: Introduction to ‘m4’
258 * History:: Historical references
259 * Bugs:: Problems and bugs
260 * Manual:: Using this manual
263 File: m4.info, Node: Intro, Next: History, Up: Preliminaries
265 1.1 Introduction to ‘m4’
266 ========================
268 ‘m4’ is a macro processor, in the sense that it copies its input to the
269 output, expanding macros as it goes. Macros are either builtin or
270 user-defined, and can take any number of arguments. Besides just doing
271 macro expansion, ‘m4’ has builtin functions for including named files,
272 running shell commands, doing integer arithmetic, manipulating text in
273 various ways, performing recursion, etc.... ‘m4’ can be used either as a
274 front-end to a compiler, or as a macro processor in its own right.
276 The ‘m4’ macro processor is widely available on all UNIXes, and has
277 been standardized by POSIX. Usually, only a small percentage of users
278 are aware of its existence. However, those who find it often become
279 committed users. The popularity of GNU Autoconf, which requires GNU
280 ‘m4’ for _generating_ ‘configure’ scripts, is an incentive for many to
281 install it, while these people will not themselves program in ‘m4’. GNU
282 ‘m4’ is mostly compatible with the System V, Release 4 version, except
283 for some minor differences. *Note Compatibility::, for more details.
285 Some people find ‘m4’ to be fairly addictive. They first use ‘m4’
286 for simple problems, then take bigger and bigger challenges, learning
287 how to write complex sets of ‘m4’ macros along the way. Once really
288 addicted, users pursue writing of sophisticated ‘m4’ applications even
289 to solve simple problems, devoting more time debugging their ‘m4’
290 scripts than doing real work. Beware that ‘m4’ may be dangerous for the
291 health of compulsive programmers.
294 File: m4.info, Node: History, Next: Bugs, Prev: Intro, Up: Preliminaries
296 1.2 Historical references
297 =========================
299 Macro languages were invented early in the history of computing. In the
300 1950s Alan Perlis suggested that the macro language be independent of
301 the language being processed. Techniques such as conditional and
302 recursive macros, and using macros to define other macros, were
303 described by Doug McIlroy of Bell Labs in “Macro Instruction Extensions
304 of Compiler Languages”, _Communications of the ACM_ 3, 4 (1960), 214–20,
305 <https://dl.acm.org/doi/10.1145/367177.367223>.
307 An important precursor of ‘m4’ was GPM; see C. Strachey, “A general
308 purpose macrogenerator”, _Computer Journal_ 8, 3 (1965), 225–41,
309 <https://academic.oup.com/comjnl/article/8/3/225/336044>. GPM is also
310 succinctly described in David Gries’s book _Compiler Construction for
311 Digital Computers_, Wiley (1971). Strachey was a brilliant programmer:
312 GPM fit into 250 machine instructions!
314 Inspired by GPM while visiting Strachey’s Lab in 1968, McIlroy wrote
315 a model preprocessor in that fit into a page of Snobol 3 code, and
316 McIlroy and Robert Morris developed a series of further models at Bell
317 Labs. Andrew D. Hall followed up with M6, a general purpose macro
318 processor used to port the Fortran source code of the Altran computer
319 algebra system; see Hall’s “The M6 Macro Processor”, Computing Science
320 Technical Report #2, Bell Labs (1972),
321 <http://cm.bell-labs.com/cm/cs/cstr/2.pdf>. M6’s source code consisted
322 of about 600 Fortran statements. Its name was the first of the ‘m4’
325 The Brian Kernighan and P.J. Plauger book _Software Tools_,
326 Addison-Wesley (1976), describes and implements a Unix macro-processor
327 language, which inspired Dennis Ritchie to write ‘m3’, a macro processor
328 for the AP-3 minicomputer.
330 Kernighan and Ritchie then joined forces to develop the original
331 ‘m4’, described in “The M4 Macro Processor”, Bell Laboratories (1977),
332 <https://wolfram.schneider.org/bsd/7thEdManVol2/m4/m4.pdf>. It had only
335 While ‘GPM’ was more _pure_, ‘m4’ is meant to deal with the true
336 intricacies of real life: macros can be recognized without being
337 pre-announced, skipping whitespace or end-of-lines is easier, more
338 constructs are builtin instead of derived, etc.
340 Originally, the Kernighan and Plauger macro-processor, and then ‘m3’,
341 formed the engine for the Rational FORTRAN preprocessor, that is, the
342 ‘Ratfor’ equivalent of ‘cpp’. Later, ‘m4’ was used as a front-end for
343 ‘Ratfor’, ‘C’ and ‘Cobol’.
345 René Seindal released his implementation of ‘m4’, GNU ‘m4’, in 1990,
346 with the aim of removing the artificial limitations in many of the
347 traditional ‘m4’ implementations, such as maximum line length, macro
348 size, or number of macros.
350 The late Professor A. Dain Samples described and implemented a
351 further evolution in the form of ‘M5’: “User’s Guide to the M5 Macro
352 Language: 2nd edition”, Electronic Announcement on comp.compilers
355 François Pinard took over maintenance of GNU ‘m4’ in 1992, until 1994
356 when he released GNU ‘m4’ 1.4, which was the stable release for 10
357 years. It was at this time that GNU Autoconf decided to require GNU
358 ‘m4’ as its underlying engine, since all other implementations of ‘m4’
359 had too many limitations.
361 More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which
362 addressed some long standing bugs in the venerable 1.4 release. Then in
363 2005, Gary V. Vaughan collected together the many patches to GNU ‘m4’
364 1.4 that were floating around the net and released 1.4.3 and 1.4.4. And
365 in 2006, Eric Blake joined the team and prepared patches for the release
366 of 1.4.5, with subsequent releases through intervening years, as recent
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
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’], [ARGUMENT]...)
441 This is a sample prototype. There is not really a macro named
442 ‘example’, but this documents that if there were, it would be a
443 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 65537 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 <https://lists.gnu.org/archive/html/bug-gnulib/2007-01/msg00389.html>,
1119 and a followup patch in
1120 <https://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'.')
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..
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')
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], [STRING-2],
2398 [EQUAL-2], ..., [NOT-EQUAL])
2399 Similar to ‘ifelse’, where an equal comparison between the first
2400 two strings results in the third, otherwise the first three
2401 arguments are discarded and the process repeats. The difference is
2402 that each TEST-<N> is expanded only when it is encountered. This
2403 means that every third argument to ‘cond’ is normally given one
2404 more level of quoting than the corresponding argument to ‘ifelse’.
2406 Here is the implementation of ‘cond’, along with a demonstration of
2407 how it can short-circuit the side effects in ‘side’. Notice how all the
2408 unquoted side effects happen regardless of how many comparisons are made
2409 with ‘ifelse’, compared with only the relevant effects with ‘cond’.
2412 `ifelse(`$#', `1', `$1',
2413 `ifelse($1, `$2', `$3',
2414 `$0(shift(shift(shift($@))))')')')dnl
2415 define(`side', `define(`counter', incr(counter))$1')dnl
2417 `define(`counter', `0')dnl
2418 ifelse(side(`$1'), `yes', `one comparison: ',
2419 side(`$1'), `no', `two comparisons: ',
2420 side(`$1'), `maybe', `three comparisons: ',
2421 `side(`default answer: ')')counter')dnl
2423 `define(`counter', `0')dnl
2424 cond(`side(`$1')', `yes', `one comparison: ',
2425 `side(`$1')', `no', `two comparisons: ',
2426 `side(`$1')', `maybe', `three comparisons: ',
2427 `side(`default answer: ')')counter')dnl
2433 ⇒three comparisons: 3
2434 example1(`feeling rather indecisive today')
2441 ⇒three comparisons: 3
2442 example2(`feeling rather indecisive today')
2445 Another common task that requires iteration is joining a list of
2446 arguments into a single string.
2448 -- Composite: join ([SEPARATOR], [ARGS...])
2449 -- Composite: joinall ([SEPARATOR], [ARGS...])
2450 Generate a single-quoted string, consisting of each ARG separated
2451 by SEPARATOR. While ‘joinall’ always outputs a SEPARATOR between
2452 arguments, ‘join’ avoids the SEPARATOR for an empty ARG.
2454 Here are some examples of its usage, based on the implementation
2455 ‘m4-1.4.19/examples/join.m4’ distributed in this package:
2460 join,join(`-'),join(`-', `'),join(`-', `', `')
2462 joinall,joinall(`-'),joinall(`-', `'),joinall(`-', `', `')
2466 join(`-', `1', `2', `3')
2468 join(`', `1', `2', `3')
2470 join(`-', `', `1', `', `', `2', `')
2472 joinall(`-', `', `1', `', `', `2', `')
2474 join(`,', `1', `2', `3')
2476 define(`nargs', `$#')dnl
2477 nargs(join(`,', `1', `2', `3'))
2480 Examining the implementation shows some interesting points about
2481 several m4 programming idioms.
2484 undivert(`join.m4')dnl
2486 ⇒# join(sep, args) - join each non-empty ARG into a single
2487 ⇒# string, with each element separated by SEP
2489 ⇒`ifelse(`$#', `2', ``$2'',
2490 ⇒ `ifelse(`$2', `', `', ``$2'_')$0(`$1', shift(shift($@)))')')
2492 ⇒`ifelse(`$#$2', `2', `',
2493 ⇒ `ifelse(`$2', `', `', ``$1$2'')$0(`$1', shift(shift($@)))')')
2494 ⇒# joinall(sep, args) - join each ARG, including empty ones,
2495 ⇒# into a single string, with each element separated by SEP
2496 ⇒define(`joinall', ``$2'_$0(`$1', shift($@))')
2498 ⇒`ifelse(`$#', `2', `', ``$1$3'$0(`$1', shift(shift($@)))')')
2501 First, notice that this implementation creates helper macros ‘_join’
2502 and ‘_joinall’. This division of labor makes it easier to output the
2503 correct number of SEPARATOR instances: ‘join’ and ‘joinall’ are
2504 responsible for the first argument, without a separator, while ‘_join’
2505 and ‘_joinall’ are responsible for all remaining arguments, always
2506 outputting a separator when outputting an argument.
2508 Next, observe how ‘join’ decides to iterate to itself, because the
2509 first ARG was empty, or to output the argument and swap over to ‘_join’.
2510 If the argument is non-empty, then the nested ‘ifelse’ results in an
2511 unquoted ‘_’, which is concatenated with the ‘$0’ to form the next macro
2512 name to invoke. The ‘joinall’ implementation is simpler since it does
2513 not have to suppress empty ARG; it always executes once then defers to
2516 Another important idiom is the idea that SEPARATOR is reused for each
2517 iteration. Each iteration has one less argument, but rather than
2518 discarding ‘$1’ by iterating with ‘$0(shift($@))’, the macro discards
2519 ‘$2’ by using ‘$0(`$1', shift(shift($@)))’.
2521 Next, notice that it is possible to compare more than one condition
2522 in a single ‘ifelse’ test. The test of ‘$#$2’ against ‘2’ allows
2523 ‘_join’ to iterate for two separate reasons—either there are still more
2524 than two arguments, or there are exactly two arguments but the last
2525 argument is not empty.
2527 Finally, notice that these macros require exactly two arguments to
2528 terminate recursion, but that they still correctly result in empty
2529 output when given no ARGS (i.e., zero or one macro argument). On the
2530 first pass when there are too few arguments, the ‘shift’ results in no
2531 output, but leaves an empty string to serve as the required second
2532 argument for the second pass. Put another way, ‘`$1', shift($@)’ is not
2533 the same as ‘$@’, since only the former guarantees at least two
2536 Sometimes, a recursive algorithm requires adding quotes to each
2537 element, or treating multiple arguments as a single element:
2539 -- Composite: quote (...)
2540 -- Composite: dquote (...)
2541 -- Composite: dquote_elt (...)
2542 Takes any number of arguments, and adds quoting. With ‘quote’,
2543 only one level of quoting is added, effectively removing whitespace
2544 after commas and turning multiple arguments into a single string.
2545 With ‘dquote’, two levels of quoting are added, one around each
2546 element, and one around the list. And with ‘dquote_elt’, two
2547 levels of quoting are added around each element.
2549 An actual implementation of these three macros is distributed as
2550 ‘m4-1.4.19/examples/quote.m4’ in this package. First, let’s examine
2556 -quote-dquote-dquote_elt-
2558 -quote()-dquote()-dquote_elt()-
2560 -quote(`1')-dquote(`1')-dquote_elt(`1')-
2562 -quote(`1', `2')-dquote(`1', `2')-dquote_elt(`1', `2')-
2563 ⇒-1,2-`1',`2'-`1',`2'-
2564 define(`n', `$#')dnl
2565 -n(quote(`1', `2'))-n(dquote(`1', `2'))-n(dquote_elt(`1', `2'))-
2567 dquote(dquote_elt(`1', `2'))
2569 dquote_elt(dquote(`1', `2'))
2572 The last two lines show that when given two arguments, ‘dquote’
2573 results in one string, while ‘dquote_elt’ results in two. Now, examine
2574 the implementation. Note that ‘quote’ and ‘dquote_elt’ make decisions
2575 based on their number of arguments, so that when called without
2576 arguments, they result in nothing instead of a quoted empty string; this
2577 is so that it is possible to distinguish between no arguments and an
2578 empty first argument. ‘dquote’, on the other hand, results in a string
2579 no matter what, since it is still possible to tell whether it was
2580 invoked without arguments based on the resulting string.
2583 undivert(`quote.m4')dnl
2585 ⇒# quote(args) - convert args to single-quoted string
2586 ⇒define(`quote', `ifelse(`$#', `0', `', ``$*'')')
2587 ⇒# dquote(args) - convert args to quoted list of quoted strings
2588 ⇒define(`dquote', ``$@'')
2589 ⇒# dquote_elt(args) - convert args to list of double-quoted strings
2590 ⇒define(`dquote_elt', `ifelse(`$#', `0', `', `$#', `1', ```$1''',
2591 ⇒ ```$1'',$0(shift($@))')')
2594 It is worth pointing out that ‘quote(ARGS)’ is more efficient than
2595 ‘joinall(`,', ARGS)’ for producing the same output.
2597 One more useful macro based on ‘shift’ allows portably selecting an
2598 arbitrary argument (usually greater than the ninth argument), without
2599 relying on the GNU extension of multi-digit arguments (*note
2602 -- Composite: argn (N, ...)
2603 Expands to argument N out of the remaining arguments. N must be a
2604 positive number. Usually invoked as ‘argn(`N',$@)’.
2606 It is implemented as:
2608 define(`argn', `ifelse(`$1', 1, ``$2'',
2609 `argn(decr(`$1'), shift(shift($@)))')')
2613 define(`foo', `argn(`11', $@)')
2615 foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l')
2619 File: m4.info, Node: Forloop, Next: Foreach, Prev: Shift, Up: Conditionals
2621 6.4 Iteration by counting
2622 =========================
2624 Here is an example of a loop macro that implements a simple for loop.
2626 -- Composite: forloop (ITERATOR, START, END, TEXT)
2627 Takes the name in ITERATOR, which must be a valid macro name, and
2628 successively assign it each integer value from START to END,
2629 inclusive. For each assignment to ITERATOR, append TEXT to the
2630 expansion of the ‘forloop’. TEXT may refer to ITERATOR. Any
2631 definition of ITERATOR prior to this invocation is restored.
2633 It can, for example, be used for simple counting:
2636 include(`forloop.m4')
2638 forloop(`i', `1', `8', `i ')
2641 For-loops can be nested, like:
2644 include(`forloop.m4')
2646 forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)')
2648 ⇒ (1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8)
2649 ⇒ (2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8)
2650 ⇒ (3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8)
2651 ⇒ (4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8)
2654 The implementation of the ‘forloop’ macro is fairly straightforward.
2655 The ‘forloop’ macro itself is simply a wrapper, which saves the previous
2656 definition of the first argument, calls the internal macro ‘_forloop’,
2657 and re-establishes the saved definition of the first argument.
2659 The macro ‘_forloop’ expands the fourth argument once, and tests to
2660 see if the iterator has reached the final value. If it has not
2661 finished, it increments the iterator (using the predefined macro ‘incr’,
2662 *note Incr::), and recurses.
2664 Here is an actual implementation of ‘forloop’, distributed as
2665 ‘m4-1.4.19/examples/forloop.m4’ in this package:
2668 undivert(`forloop.m4')dnl
2670 ⇒# forloop(var, from, to, stmt) - simple version
2671 ⇒define(`forloop', `pushdef(`$1', `$2')_forloop($@)popdef(`$1')')
2673 ⇒ `$4`'ifelse($1, `$3', `', `define(`$1', incr($1))$0($@)')')
2676 Notice the careful use of quotes. Certain macro arguments are left
2677 unquoted, each for its own reason. Try to find out _why_ these
2678 arguments are left unquoted, and see what happens if they are quoted.
2679 (As presented, these two macros are useful but not very robust for
2680 general use. They lack even basic error handling for cases like START
2681 less than END, END not numeric, or ITERATOR not being a macro name. See
2682 if you can improve these macros; or *note Answers: Improved forloop.).
2685 File: m4.info, Node: Foreach, Next: Stacks, Prev: Forloop, Up: Conditionals
2687 6.5 Iteration by list contents
2688 ==============================
2690 Here is an example of a loop macro that implements list iteration.
2692 -- Composite: foreach (ITERATOR, PAREN-LIST, TEXT)
2693 -- Composite: foreachq (ITERATOR, QUOTE-LIST, TEXT)
2694 Takes the name in ITERATOR, which must be a valid macro name, and
2695 successively assign it each value from PAREN-LIST or QUOTE-LIST.
2696 In ‘foreach’, PAREN-LIST is a comma-separated list of elements
2697 contained in parentheses. In ‘foreachq’, QUOTE-LIST is a
2698 comma-separated list of elements contained in a quoted string. For
2699 each assignment to ITERATOR, append TEXT to the overall expansion.
2700 TEXT may refer to ITERATOR. Any definition of ITERATOR prior to
2701 this invocation is restored.
2703 As an example, this displays each word in a list inside of a
2704 sentence, using an implementation of ‘foreach’ distributed as
2705 ‘m4-1.4.19/examples/foreach.m4’, and ‘foreachq’ in
2706 ‘m4-1.4.19/examples/foreachq.m4’.
2709 include(`foreach.m4')
2711 foreach(`x', (foo, bar, foobar), `Word was: x
2716 include(`foreachq.m4')
2718 foreachq(`x', `foo, bar, foobar', `Word was: x
2724 It is possible to be more complex; each element of the PAREN-LIST or
2725 QUOTE-LIST can itself be a list, to pass as further arguments to a
2726 helper macro. This example generates a shell case statement:
2729 include(`foreach.m4')
2731 define(`_case', ` $1)
2734 define(`_cat', `$1$2')dnl
2737 foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')',
2738 `_cat(`_case', x)')dnl
2748 The implementation of the ‘foreach’ macro is a bit more involved; it
2749 is a wrapper around two helper macros. First, ‘_arg1’ is needed to grab
2750 the first element of a list. Second, ‘_foreach’ implements the
2751 recursion, successively walking through the original list. Here is a
2752 simple implementation of ‘foreach’:
2755 undivert(`foreach.m4')dnl
2757 ⇒# foreach(x, (item_1, item_2, ..., item_n), stmt)
2758 ⇒# parenthesized list, simple version
2759 ⇒define(`foreach', `pushdef(`$1')_foreach($@)popdef(`$1')')
2760 ⇒define(`_arg1', `$1')
2761 ⇒define(`_foreach', `ifelse(`$2', `()', `',
2762 ⇒ `define(`$1', _arg1$2)$3`'$0(`$1', (shift$2), `$3')')')
2765 Unfortunately, that implementation is not robust to macro names as
2766 list elements. Each iteration of ‘_foreach’ is stripping another layer
2767 of quotes, leading to erratic results if list elements are not already
2768 fully expanded. The first cut at implementing ‘foreachq’ takes this
2769 into account. Also, when using quoted elements in a PAREN-LIST, the
2770 overall list must be quoted. A QUOTE-LIST has the nice property of
2771 requiring fewer characters to create a list containing the same quoted
2772 elements. To see the difference between the two macros, we attempt to
2773 pass double-quoted macro names in a list, expecting the macro name on
2774 output after one layer of quotes is removed during list iteration and
2775 the final layer removed during the final rescan:
2778 define(`a', `1')define(`b', `2')define(`c', `3')
2780 include(`foreach.m4')
2782 include(`foreachq.m4')
2784 foreach(`x', `(``a'', ``(b'', ``c)'')', `x
2791 foreachq(`x', ```a'', ``(b'', ``c)''', `x
2797 Obviously, ‘foreachq’ did a better job; here is its implementation:
2800 undivert(`foreachq.m4')dnl
2801 ⇒include(`quote.m4')dnl
2803 ⇒# foreachq(x, `item_1, item_2, ..., item_n', stmt)
2804 ⇒# quoted list, simple version
2805 ⇒define(`foreachq', `pushdef(`$1')_foreachq($@)popdef(`$1')')
2806 ⇒define(`_arg1', `$1')
2807 ⇒define(`_foreachq', `ifelse(quote($2), `', `',
2808 ⇒ `define(`$1', `_arg1($2)')$3`'$0(`$1', `shift($2)', `$3')')')
2811 Notice that ‘_foreachq’ had to use the helper macro ‘quote’ defined
2812 earlier (*note Shift::), to ensure that the embedded ‘ifelse’ call does
2813 not go haywire if a list element contains a comma. Unfortunately, this
2814 implementation of ‘foreachq’ has its own severe flaw. Whereas the
2815 ‘foreach’ implementation was linear, this macro is quadratic in the
2816 number of list elements, and is much more likely to trip up the limit
2817 set by the command line option ‘--nesting-limit’ (or ‘-L’, *note
2818 Invoking m4: Limits control.). Additionally, this implementation does
2819 not expand ‘defn(`ITERATOR')’ very well, when compared with ‘foreach’.
2822 include(`foreach.m4')include(`foreachq.m4')
2824 foreach(`name', `(`a', `b')', ` defn(`name')')
2826 foreachq(`name', ``a', `b'', ` defn(`name')')
2827 ⇒ _arg1(`a', `b') _arg1(shift(`a', `b'))
2829 It is possible to have robust iteration with linear behavior and sane
2830 ITERATOR contents for either list style. See if you can learn from the
2831 best elements of both of these implementations to create robust macros
2832 (or *note Answers: Improved foreach.).
2835 File: m4.info, Node: Stacks, Next: Composition, Prev: Foreach, Up: Conditionals
2837 6.6 Working with definition stacks
2838 ==================================
2840 Thanks to ‘pushdef’, manipulation of a stack is an intrinsic operation
2841 in ‘m4’. Normally, only the topmost definition in a stack is important,
2842 but sometimes, it is desirable to manipulate the entire definition
2845 -- Composite: stack_foreach (MACRO, ACTION)
2846 -- Composite: stack_foreach_lifo (MACRO, ACTION)
2847 For each of the ‘pushdef’ definitions associated with MACRO, invoke
2848 the macro ACTION with a single argument of that definition.
2849 ‘stack_foreach’ visits the oldest definition first, while
2850 ‘stack_foreach_lifo’ visits the current definition first. ACTION
2851 should not modify or dereference MACRO. There are a few special
2852 macros, such as ‘defn’, which cannot be used as the MACRO
2855 A sample implementation of these macros is distributed in the file
2856 ‘m4-1.4.19/examples/stack.m4’.
2861 pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
2863 define(`show', ``$1'
2866 stack_foreach(`a', `show')dnl
2870 stack_foreach_lifo(`a', `show')dnl
2875 Now for the implementation. Note the definition of a helper macro,
2876 ‘_stack_reverse’, which destructively swaps the contents of one stack of
2877 definitions into the reverse order in the temporary macro ‘tmp-$1’. By
2878 calling the helper twice, the original order is restored back into the
2879 macro ‘$1’; since the operation is destructive, this explains why ‘$1’
2880 must not be modified or dereferenced during the traversal. The caller
2881 can then inject additional code to pass the definition currently being
2882 visited to ‘$2’. The choice of helper names is intentional; since ‘-’
2883 is not valid as part of a macro name, there is no risk of conflict with
2884 a valid macro name, and the code is guaranteed to use ‘defn’ where
2885 necessary. Finally, note that any macro used in the traversal of a
2886 ‘pushdef’ stack, such as ‘pushdef’ or ‘defn’, cannot be handled by
2887 ‘stack_foreach’, since the macro would temporarily be undefined during
2891 undivert(`stack.m4')dnl
2893 ⇒# stack_foreach(macro, action)
2894 ⇒# Invoke ACTION with a single argument of each definition
2895 ⇒# from the definition stack of MACRO, starting with the oldest.
2896 ⇒define(`stack_foreach',
2897 ⇒`_stack_reverse(`$1', `tmp-$1')'dnl
2898 ⇒`_stack_reverse(`tmp-$1', `$1', `$2(defn(`$1'))')')
2899 ⇒# stack_foreach_lifo(macro, action)
2900 ⇒# Invoke ACTION with a single argument of each definition
2901 ⇒# from the definition stack of MACRO, starting with the newest.
2902 ⇒define(`stack_foreach_lifo',
2903 ⇒`_stack_reverse(`$1', `tmp-$1', `$2(defn(`$1'))')'dnl
2904 ⇒`_stack_reverse(`tmp-$1', `$1')')
2905 ⇒define(`_stack_reverse',
2906 ⇒`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0($@)')')
2910 File: m4.info, Node: Composition, Prev: Stacks, Up: Conditionals
2912 6.7 Building macros with macros
2913 ===============================
2915 Since m4 is a macro language, it is possible to write macros that can
2916 build other macros. First on the list is a way to automate the creation
2919 -- Composite: define_blind (NAME, [VALUE])
2920 Defines NAME as a blind macro, such that NAME will expand to VALUE
2921 only when given explicit arguments. VALUE should not be the result
2922 of ‘defn’ (*note Defn::). This macro is only recognized with
2923 parameters, and results in an empty string.
2925 Defining a macro to define another macro can be a bit tricky. We
2926 want to use a literal ‘$#’ in the argument to the nested ‘define’.
2927 However, if ‘$’ and ‘#’ are adjacent in the definition of
2928 ‘define_blind’, then it would be expanded as the number of arguments to
2929 ‘define_blind’ rather than the intended number of arguments to NAME.
2930 The solution is to pass the difficult characters through extra arguments
2931 to a helper macro ‘_define_blind’. When composing macros, it is a
2932 common idiom to need a helper macro to concatenate text that forms
2933 parameters in the composed macro, rather than interpreting the text as a
2934 parameter of the composing macro.
2936 As for the limitation against using ‘defn’, there are two reasons.
2937 If a macro was previously defined with ‘define_blind’, then it can
2938 safely be renamed to a new blind macro using plain ‘define’; using
2939 ‘define_blind’ to rename it just adds another layer of ‘ifelse’,
2940 occupying memory and slowing down execution. And if a macro is a
2941 builtin, then it would result in an attempt to define a macro consisting
2942 of both text and a builtin token; this is not supported, and the builtin
2943 token is flattened to an empty string.
2945 With that explanation, here’s the definition, and some sample usage.
2946 Notice that ‘define_blind’ is itself a blind macro.
2949 define(`define_blind', `ifelse(`$#', `0', ``$0'',
2950 `_$0(`$1', `$2', `$'`#', `$'`0')')')
2952 define(`_define_blind', `define(`$1',
2953 `ifelse(`$3', `0', ``$4'', `$2')')')
2957 define_blind(`foo', `arguments were $*')
2963 define(`blah', defn(`foo'))
2970 ⇒ifelse(`$#', `0', ``$0'', `arguments were $*')
2972 Another interesting composition tactic is argument “currying”, or
2973 factoring a macro that takes multiple arguments for use in a context
2974 that provides exactly one argument.
2976 -- Composite: curry (MACRO, ...)
2977 Expand to a macro call that takes exactly one argument, then
2978 appends that argument to the original arguments and invokes MACRO
2979 with the resulting list of arguments.
2981 A demonstration of currying makes the intent of this macro a little
2982 more obvious. The macro ‘stack_foreach’ mentioned earlier is an example
2983 of a context that provides exactly one argument to a macro name. But
2984 coupled with currying, we can invoke ‘reverse’ with two arguments for
2985 each definition of a macro stack. This example uses the file
2986 ‘m4-1.4.19/examples/curry.m4’ included in the distribution.
2989 include(`curry.m4')include(`stack.m4')
2991 define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
2992 `reverse(shift($@)), `$1'')')
2994 pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
2996 stack_foreach(`a', `:curry(`reverse', `4')')
2998 curry(`curry', `reverse', `1')(`2')(`3')
3001 Now for the implementation. Notice how ‘curry’ leaves off with a
3002 macro name but no open parenthesis, while still in the middle of
3003 collecting arguments for ‘$1’. The macro ‘_curry’ is the helper macro
3004 that takes one argument, then adds it to the list and finally supplies
3005 the closing parenthesis. The use of a comma inside the ‘shift’ call
3006 allows currying to also work for a macro that takes one argument,
3007 although it often makes more sense to invoke that macro directly rather
3008 than going through ‘curry’.
3011 undivert(`curry.m4')dnl
3013 ⇒# curry(macro, args)
3014 ⇒# Expand to a macro call that takes one argument, then invoke
3015 ⇒# macro(args, extra).
3016 ⇒define(`curry', `$1(shift($@,)_$0')
3017 ⇒define(`_curry', ``$1')')
3020 Unfortunately, with M4 1.4.x, ‘curry’ is unable to handle builtin
3021 tokens, which are silently flattened to the empty string when passed
3022 through another text macro. This limitation will be lifted in a future
3025 Putting the last few concepts together, it is possible to copy or
3026 rename an entire stack of macro definitions.
3028 -- Composite: copy (SOURCE, DEST)
3029 -- Composite: rename (SOURCE, DEST)
3030 Ensure that DEST is undefined, then define it to the same stack of
3031 definitions currently in SOURCE. ‘copy’ leaves SOURCE unchanged,
3032 while ‘rename’ undefines SOURCE. There are only a few macros, such
3033 as ‘copy’ or ‘defn’, which cannot be copied via this macro.
3035 The implementation is relatively straightforward (although since it
3036 uses ‘curry’, it is unable to copy builtin macros, such as the second
3037 definition of ‘a’ as a synonym for ‘divnum’. See if you can design a
3038 version that works around this limitation, or *note Answers: Improved
3042 include(`curry.m4')include(`stack.m4')
3044 define(`rename', `copy($@)undefine(`$1')')dnl
3045 define(`copy', `ifdef(`$2', `errprint(`$2 already defined
3047 `stack_foreach(`$1', `curry(`pushdef', `$2')')')')dnl
3048 pushdef(`a', `1')pushdef(`a', defn(`divnum'))pushdef(`a', `2')
3062 File: m4.info, Node: Debugging, Next: Input Control, Prev: Conditionals, Up: Top
3064 7 How to debug macros and input
3065 *******************************
3067 When writing macros for ‘m4’, they often do not work as intended on the
3068 first try (as is the case with most programming languages).
3069 Fortunately, there is support for macro debugging in ‘m4’.
3073 * Dumpdef:: Displaying macro definitions
3074 * Trace:: Tracing macro calls
3075 * Debug Levels:: Controlling debugging output
3076 * Debug Output:: Saving debugging output
3079 File: m4.info, Node: Dumpdef, Next: Trace, Up: Debugging
3081 7.1 Displaying macro definitions
3082 ================================
3084 If you want to see what a name expands into, you can use the builtin
3087 -- Builtin: dumpdef ([NAMES...])
3088 Accepts any number of arguments. If called without any arguments,
3089 it displays the definitions of all known names, otherwise it
3090 displays the definitions of the NAMES given. The output is printed
3091 to the current debug file (usually standard error), and is sorted
3092 by name. If an unknown name is encountered, a warning is printed.
3094 The expansion of ‘dumpdef’ is void.
3097 define(`foo', `Hello world.')
3104 The last example shows how builtin macros definitions are displayed.
3105 The definition that is dumped corresponds to what would occur if the
3106 macro were to be called at that point, even if other definitions are
3107 still live due to redefining a macro during argument collection.
3110 pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
3112 f(popdef(`f')dumpdef(`f'))
3114 f(popdef(`f')dumpdef(`f'))
3115 error→m4:stdin:3: undefined macro `f'
3118 *Note Debug Levels::, for information on controlling the details of
3122 File: m4.info, Node: Trace, Next: Debug Levels, Prev: Dumpdef, Up: Debugging
3124 7.2 Tracing macro calls
3125 =======================
3127 It is possible to trace macro calls and expansions through the builtins
3128 ‘traceon’ and ‘traceoff’:
3130 -- Builtin: traceon ([NAMES...])
3131 -- Builtin: traceoff ([NAMES...])
3132 When called without any arguments, ‘traceon’ and ‘traceoff’ will
3133 turn tracing on and off, respectively, for all currently defined
3136 When called with arguments, only the macros listed in NAMES are
3137 affected, whether or not they are currently defined.
3139 The expansion of ‘traceon’ and ‘traceoff’ is void.
3141 Whenever a traced macro is called and the arguments have been
3142 collected, the call is displayed. If the expansion of the macro call is
3143 not void, the expansion can be displayed after the call. The output is
3144 printed to the current debug file (defaulting to standard error, *note
3148 define(`foo', `Hello World.')
3150 define(`echo', `$@')
3152 traceon(`foo', `echo')
3155 error→m4trace: -1- foo -> `Hello World.'
3157 echo(`gnus', `and gnats')
3158 error→m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
3161 The number between dashes is the depth of the expansion. It is one
3162 most of the time, signifying an expansion at the outermost level, but it
3163 increases when macro arguments contain unquoted macro calls. The
3164 maximum number that will appear between dashes is controlled by the
3165 option ‘--nesting-limit’ (or ‘-L’, *note Invoking m4: Limits control.).
3166 Additionally, the option ‘--trace’ (or ‘-t’) can be used to invoke
3167 ‘traceon(NAME)’ before parsing input.
3171 error→m4trace: -1- ifelse
3173 ifelse(ifelse(ifelse(`three levels')))
3174 error→m4trace: -3- ifelse
3175 error→m4trace: -2- ifelse
3176 error→m4trace: -1- ifelse
3178 ifelse(ifelse(ifelse(ifelse(`four levels'))))
3179 error→m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it
3181 Tracing by name is an attribute that is preserved whether the macro
3182 is defined or not. This allows the selection of macros to trace before
3183 those macros are defined.
3194 define(`foo', `bar')
3197 error→m4trace: -1- foo -> `bar'
3201 ifdef(`foo', `yes', `no')
3204 error→m4:stdin:9: undefined macro `foo'
3206 define(`foo', `blah')
3209 error→m4trace: -1- foo -> `blah'
3216 Tracing even works on builtins. However, ‘defn’ (*note Defn::) does
3217 not transfer tracing status.
3223 error→m4trace: -1- traceon(`traceoff')
3225 traceoff(`traceoff')
3226 error→m4trace: -1- traceoff(`traceoff')
3230 traceon(`eval', `m4_divnum')
3232 define(`m4_eval', defn(`eval'))
3234 define(`m4_divnum', defn(`divnum'))
3237 error→m4trace: -1- eval(`0') -> `0'
3240 error→m4trace: -2- m4_divnum -> `0'
3243 *Note Debug Levels::, for information on controlling the details of
3244 the display. The format of the trace output is not specified by POSIX,
3245 and varies between implementations of ‘m4’.
3248 File: m4.info, Node: Debug Levels, Next: Debug Output, Prev: Trace, Up: Debugging
3250 7.3 Controlling debugging output
3251 ================================
3253 The ‘-d’ option to ‘m4’ (or ‘--debug’, *note Invoking m4: Debugging
3254 options.) controls the amount of details presented in three categories
3255 of output. Trace output is requested by ‘traceon’ (*note Trace::), and
3256 each line is prefixed by ‘m4trace:’ in relation to a macro invocation.
3257 Debug output tracks useful events not associated with a macro
3258 invocation, and each line is prefixed by ‘m4debug:’. Finally, ‘dumpdef’
3259 (*note Dumpdef::) output is affected, with no prefix added to the output
3262 The FLAGS following the option can be one or more of the following:
3265 In trace output, show the actual arguments that were collected
3266 before invoking the macro. This applies to all macro calls if the
3267 ‘t’ flag is used, otherwise only the macros covered by calls of
3268 ‘traceon’. Arguments are subject to length truncation specified by
3269 the command line option ‘--arglength’ (or ‘-l’).
3272 In trace output, show several trace lines for each macro call. A
3273 line is shown when the macro is seen, but before the arguments are
3274 collected; a second line when the arguments have been collected and
3275 a third line after the call has completed.
3278 In trace output, show the expansion of each macro call, if it is
3279 not void. This applies to all macro calls if the ‘t’ flag is used,
3280 otherwise only the macros covered by calls of ‘traceon’. The
3281 expansion is subject to length truncation specified by the command
3282 line option ‘--arglength’ (or ‘-l’).
3285 In debug and trace output, include the name of the current input
3286 file in the output line.
3289 In debug output, print a message each time the current input file
3293 In debug and trace output, include the current input line number in
3297 In debug output, print a message when a named file is found through
3298 the path search mechanism (*note Search Path::), giving the actual
3302 In trace and dumpdef output, quote actual arguments and macro
3303 expansions in the display with the current quotes. This is useful
3304 in connection with the ‘a’ and ‘e’ flags above.
3307 In trace output, trace all macro calls made in this invocation of
3308 ‘m4’, regardless of the settings of ‘traceon’.
3311 In trace output, add a unique ‘macro call id’ to each line of the
3312 trace output. This is useful in connection with the ‘c’ flag
3316 A shorthand for all of the above flags.
3318 If no flags are specified with the ‘-d’ option, the default is ‘aeq’.
3319 The examples throughout this manual assume the default flags.
3321 There is a builtin macro ‘debugmode’, which allows on-the-fly control
3322 of the debugging output format:
3324 -- Builtin: debugmode ([FLAGS])
3325 The argument FLAGS should be a subset of the letters listed above.
3326 As special cases, if the argument starts with a ‘+’, the flags are
3327 added to the current debug flags, and if it starts with a ‘-’, they
3328 are removed. If no argument is present, all debugging flags are
3329 cleared (as if no ‘-d’ was given), and with an empty argument the
3330 flags are reset to the default of ‘aeq’.
3332 The expansion of ‘debugmode’ is void.
3335 define(`foo', `FOO')
3342 error→m4trace: -1- foo -> `FOO'
3347 error→m4trace: -1- foo
3352 error→m4trace:8: -1- foo
3355 The following example demonstrates the behavior of length truncation,
3356 when specified on the command line. Note that each argument and the
3357 final result are individually truncated. Also, the special tokens for
3358 builtin functions are not truncated.
3361 define(`echo', `$@')debugmode(`+t')
3363 echo(`1', `long string')
3364 error→m4trace: -1- echo(`1', `long s...') -> ``1',`l...'
3366 indir(`echo', defn(`changequote'))
3367 error→m4trace: -2- defn(`change...')
3368 error→m4trace: -1- indir(`echo', <changequote>) -> ``''
3371 This example shows the effects of the debug flags that are not
3372 related to macro tracing.
3374 $ m4 -dip -I examples
3375 error→m4debug: input read from stdin
3377 error→m4debug: path search for `foo' found `examples/foo'
3378 error→m4debug: input read from examples/foo
3380 error→m4debug: input reverted to stdin, line 1
3382 error→m4debug: input exhausted
3385 File: m4.info, Node: Debug Output, Prev: Debug Levels, Up: Debugging
3387 7.4 Saving debugging output
3388 ===========================
3390 Debug and tracing output can be redirected to files using either the
3391 ‘--debugfile’ option to ‘m4’ (*note Invoking m4: Debugging options.), or
3392 with the builtin macro ‘debugfile’:
3394 -- Builtin: debugfile ([FILE])
3395 Sends all further debug and trace output to FILE, opened in append
3396 mode. If FILE is the empty string, debug and trace output are
3397 discarded. If ‘debugfile’ is called without any arguments, debug
3398 and trace output are sent to standard error. This does not affect
3399 warnings, error messages, or ‘errprint’ output, which are always
3400 sent to standard error. If FILE cannot be opened, the current
3401 debug file is unchanged, and an error is issued.
3403 The expansion of ‘debugfile’ is void.
3409 error→m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored
3410 error→m4trace: -1- divnum(`extra') -> `0'
3415 error→m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored
3420 error→m4trace: -1- divnum -> `0'
3424 File: m4.info, Node: Input Control, Next: File Inclusion, Prev: Debugging, Up: Top
3429 This chapter describes various builtin macros for controlling the input
3434 * Dnl:: Deleting whitespace in input
3435 * Changequote:: Changing the quote characters
3436 * Changecom:: Changing the comment delimiters
3437 * Changeword:: Changing the lexical structure of words
3438 * M4wrap:: Saving text until end of input
3441 File: m4.info, Node: Dnl, Next: Changequote, Up: Input Control
3443 8.1 Deleting whitespace in input
3444 ================================
3446 The builtin ‘dnl’ stands for “Discard to Next Line”:
3449 All characters, up to and including the next newline, are discarded
3450 without performing any macro expansion. A warning is issued if the
3451 end of the file is encountered without a newline.
3453 The expansion of ‘dnl’ is void.
3455 It is often used in connection with ‘define’, to remove the newline
3456 that follows the call to ‘define’. Thus
3458 define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
3462 The input up to and including the next newline is discarded, as
3463 opposed to the way comments are treated (*note Comments::).
3465 Usually, ‘dnl’ is immediately followed by an end of line or some
3466 other whitespace. GNU ‘m4’ will produce a warning diagnostic if ‘dnl’
3467 is followed by an open parenthesis. In this case, ‘dnl’ will collect
3468 and process all arguments, looking for a matching close parenthesis.
3469 All predictable side effects resulting from this collection will take
3470 place. ‘dnl’ will return no output. The input following the matching
3471 close parenthesis up to and including the next newline, on whatever line
3472 containing it, will still be discarded.
3474 dnl(`args are ignored, but side effects occur',
3475 define(`foo', `like this')) while this text is ignored: undefine(`foo')
3476 error→m4:stdin:1: Warning: excess arguments to builtin `dnl' ignored
3477 See how `foo' was defined, foo?
3478 ⇒See how foo was defined, like this?
3480 If the end of file is encountered without a newline character, a
3481 warning is issued and dnl stops consuming input.
3483 m4wrap(`m4wrap(`2 hi
3489 error→m4:stdin:1: Warning: end of file treated as newline
3493 File: m4.info, Node: Changequote, Next: Changecom, Prev: Dnl, Up: Input Control
3495 8.2 Changing the quote characters
3496 =================================
3498 The default quote delimiters can be changed with the builtin
3501 -- Builtin: changequote ([START = ‘`’], [END = ‘'’])
3502 This sets START as the new begin-quote delimiter and END as the new
3503 end-quote delimiter. If both arguments are missing, the default
3504 quotes (‘`’ and ‘'’) are used. If START is void, then quoting is
3505 disabled. Otherwise, if END is missing or void, the default
3506 end-quote delimiter (‘'’) is used. The quote delimiters can be of
3509 The expansion of ‘changequote’ is void.
3511 changequote(`[', `]')
3513 define([foo], [Macro [foo].])
3518 The quotation strings can safely contain non-ASCII characters.
3524 changequote(`«', `»')
3529 If no single character is appropriate, START and END can be of any
3530 length. Other implementations cap the delimiter length to five
3531 characters, but GNU has no inherent limit.
3533 changequote(`[[[', `]]]')
3535 define([[[foo]]], [[[Macro [[[[[foo]]]]].]]])
3540 Calling ‘changequote’ with START as the empty string will effectively
3541 disable the quoting mechanism, leaving no way to quote text. However,
3542 using an empty string is not portable, as some other implementations of
3543 ‘m4’ revert to the default quoting, while others preserve the prior
3544 non-empty delimiter. If START is not empty, then an empty END will use
3545 the default end-quote delimiter of ‘'’, as otherwise, it would be
3546 impossible to end a quoted string. Again, this is not portable, as some
3547 other ‘m4’ implementations reuse START as the end-quote delimiter, while
3548 others preserve the previous non-empty value. Omitting both arguments
3549 restores the default begin-quote and end-quote delimiters; fortunately
3550 this behavior is portable to all implementations of ‘m4’.
3552 define(`foo', `Macro `FOO'.')
3565 There is no way in ‘m4’ to quote a string containing an unmatched
3566 begin-quote, except using ‘changequote’ to change the current quotes.
3568 If the quotes should be changed from, say, ‘[’ to ‘[[’, temporary
3569 quote characters have to be defined. To achieve this, two calls of
3570 ‘changequote’ must be made, one for the temporary quotes and one for the
3573 Macros are recognized in preference to the begin-quote string, so if
3574 a prefix of START can be recognized as part of a potential macro name,
3575 the quoting mechanism is effectively disabled. Unless you use
3576 ‘changeword’ (*note Changeword::), this means that START should not
3577 begin with a letter, digit, or ‘_’ (underscore). However, even though
3578 quoted strings are not recognized, the quote characters can still be
3579 discerned in macro expansion and in trace output.
3581 define(`echo', `$@')
3585 changequote(`q', `Q')
3593 changequote(`-', `EOF')
3599 changequote(`1', `2')
3606 Quotes are recognized in preference to argument collection. In
3607 particular, if START is a single ‘(’, then argument collection is
3608 effectively disabled. For portability with other implementations, it is
3609 a good idea to avoid ‘(’, ‘,’, and ‘)’ as the first character in START.
3611 define(`echo', `$#:$@:')
3615 changequote(`(',`)')
3621 changequote(`((', `))')
3629 changequote(`,', `)')
3634 However, if you are not worried about portability, using ‘(’ and ‘)’
3635 as quoting characters has an interesting property—you can use it to
3636 compute a quoted string containing the expansion of any quoted text, as
3637 long as the expansion results in both balanced quotes and balanced
3638 parentheses. The trick is realizing ‘expand’ uses ‘$1’ unquoted, to
3639 trigger its expansion using the normal quoting characters, but uses
3640 extra parentheses to group unquoted commas that occur in the expansion
3641 without consuming whitespace following those commas. Then ‘_expand’
3642 uses ‘changequote’ to convert the extra parentheses back into quoting
3643 characters. Note that it takes two more ‘changequote’ invocations to
3644 restore the original quotes. Contrast the behavior on whitespace when
3645 using ‘$*’, via ‘quote’, to attempt the same task.
3647 changequote(`[', `]')dnl
3648 define([a], [1, (b)])dnl
3650 define([quote], [[$*]])dnl
3651 define([expand], [_$0(($1))])dnl
3653 [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl
3654 expand([a, a, [a, a], [[a, a]]])
3655 ⇒1, (2), 1, (2), a, a, [a, a]
3656 quote(a, a, [a, a], [[a, a]])
3657 ⇒1,(2),1,(2),a, a,[a, a]
3659 If END is a prefix of START, the end-quote will be recognized in
3660 preference to a nested begin-quote. In particular, changing the quotes
3661 to have the same string for START and END disables nesting of quotes.
3662 When quote nesting is disabled, it is impossible to double-quote strings
3663 across macro expansions, so using the same string is not done very
3668 changequote(`""', `"')
3680 changequote(`"', `"')
3685 It is an error if the end of file occurs within a quoted string.
3691 error→m4:stdin:2: ERROR: end of file in string
3693 ifelse(`dangling quote
3695 error→m4:stdin:1: ERROR: end of file in string
3698 File: m4.info, Node: Changecom, Next: Changeword, Prev: Changequote, Up: Input Control
3700 8.3 Changing the comment delimiters
3701 ===================================
3703 The default comment delimiters can be changed with the builtin macro
3706 -- Builtin: changecom ([START], [END = ‘<NL>’])
3707 This sets START as the new begin-comment delimiter and END as the
3708 new end-comment delimiter. If both arguments are missing, or START
3709 is void, then comments are disabled. Otherwise, if END is missing
3710 or void, the default end-comment delimiter of newline is used. The
3711 comment delimiters can be of any length.
3713 The expansion of ‘changecom’ is void.
3715 define(`comment', `COMMENT')
3719 changecom(`/*', `*/')
3721 # Not a comment anymore
3722 ⇒# Not a COMMENT anymore
3723 But: /* this is a comment now */ while this is not a comment
3724 ⇒But: /* this is a comment now */ while this is not a COMMENT
3726 Note how comments are copied to the output, much as if they were
3727 quoted strings. If you want the text inside a comment expanded, quote
3728 the begin-comment delimiter.
3730 Calling ‘changecom’ without any arguments, or with START as the empty
3731 string, will effectively disable the commenting mechanism. To restore
3732 the original comment start of ‘#’, you must explicitly ask for it. If
3733 START is not empty, then an empty END will use the default end-comment
3734 delimiter of newline, as otherwise, it would be impossible to end a
3735 comment. However, this is not portable, as some other ‘m4’
3736 implementations preserve the previous non-empty delimiters instead.
3738 define(`comment', `COMMENT')
3742 # Not a comment anymore
3743 ⇒# Not a COMMENT anymore
3749 The comment strings can safely contain non-ASCII characters.
3760 If no single character is appropriate, START and END can be of any
3761 length. Other implementations cap the delimiter length to five
3762 characters, but GNU has no inherent limit.
3764 Comments are recognized in preference to macros. However, this is
3765 not compatible with other implementations, where macros and even quoting
3766 takes precedence over comments, so it may change in a future release.
3767 For portability, this means that START should not begin with a letter,
3768 digit, or ‘_’ (underscore), and that neither the start-quote nor the
3769 start-comment string should be a prefix of the other.
3773 define(`hi1hi2', `hello')
3786 Comments are recognized in preference to argument collection. In
3787 particular, if START is a single ‘(’, then argument collection is
3788 effectively disabled. For portability with other implementations, it is
3789 a good idea to avoid ‘(’, ‘,’, and ‘)’ as the first character in START.
3791 define(`echo', `$#:$*:$@:')
3801 changecom(`((', `))')
3810 ⇒1:HI,hi)bye:HI,hi)bye:
3814 ⇒3:HI,,HI,HI:HI,,`'hi,HI:
3815 echo(hi,`,`'hi',hi`'changecom(`,,', `hi'))
3816 ⇒3:HI,,`'hi,HI:HI,,`'hi,HI:
3818 It is an error if the end of file occurs within a comment.
3820 changecom(`/*', `*/')
3824 error→m4:stdin:2: ERROR: end of file in comment
3827 File: m4.info, Node: Changeword, Next: M4wrap, Prev: Changecom, Up: Input Control
3829 8.4 Changing the lexical structure of words
3830 ===========================================
3832 The macro ‘changeword’ and all associated functionality is
3833 experimental. It is only available if the ‘--enable-changeword’
3834 option was given to ‘configure’, at GNU ‘m4’ installation time.
3835 The functionality will go away in the future, to be replaced by
3836 other new features that are more efficient at providing the same
3837 capabilities. _Do not rely on it_. Please direct your comments
3838 about it the same way you would do for bugs.
3840 A file being processed by ‘m4’ is split into quoted strings, words
3841 (potential macro names) and simple tokens (any other single character).
3842 Initially a word is defined by the following regular expression:
3844 [_a-zA-Z][_a-zA-Z0-9]*
3846 Using ‘changeword’, you can change this regular expression:
3848 -- Optional builtin: changeword (REGEX)
3849 Changes the regular expression for recognizing macro names to be
3850 REGEX. If REGEX is empty, use ‘[_a-zA-Z][_a-zA-Z0-9]*’. REGEX
3851 must obey the constraint that every prefix of the desired final
3852 pattern is also accepted by the regular expression. If REGEX
3853 contains grouping parentheses, the macro invoked is the portion
3854 that matched the first group, rather than the entire matching
3857 The expansion of ‘changeword’ is void. The macro ‘changeword’ is
3858 recognized only with parameters.
3860 Relaxing the lexical rules of ‘m4’ might be useful (for example) if
3861 you wanted to apply translations to a file of numbers:
3863 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3865 changeword(`[_a-zA-Z0-9]+')
3870 Tightening the lexical rules is less useful, because it will
3871 generally make some of the builtins unavailable. You could use it to
3872 prevent accidental call of builtins, for example:
3874 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3876 define(`_indir', defn(`indir'))
3878 changeword(`_[_a-zA-Z0-9]*')
3882 _indir(`esyscmd', `echo hi')
3886 Because ‘m4’ constructs its words a character at a time, there is a
3887 restriction on the regular expressions that may be passed to
3888 ‘changeword’. This is that if your regular expression accepts ‘foo’, it
3889 must also accept ‘f’ and ‘fo’.
3891 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3897 dnl This example wants to recognize changeword, dnl, and `foo\n'.
3898 dnl First, we check that our regexp will match.
3899 regexp(`changeword', `[cd][a-z]*\|foo[
3903 ', `[cd][a-z]*\|foo[
3906 regexp(`f', `[cd][a-z]*\|foo[
3911 changeword(`[cd][a-z]*\|foo[
3914 dnl Even though `foo\n' matches, we forgot to allow `f'.
3917 changeword(`[cd][a-z]*\|fo*[
3920 dnl Now we can call `foo\n'.
3924 ‘changeword’ has another function. If the regular expression
3925 supplied contains any grouped subexpressions, then text outside the
3926 first of these is discarded before symbol lookup. So:
3928 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3931 `errprint(` skipping: syscmd does not have unix semantics
3933 changecom(`/*', `*/')dnl
3934 define(`foo', `bar')dnl
3935 changeword(`#\([_a-zA-Z0-9]*\)')
3937 #esyscmd(`echo foo \#foo')
3941 ‘m4’ now requires a ‘#’ mark at the beginning of every macro
3942 invocation, so one can use ‘m4’ to preprocess plain text without losing
3943 various words like ‘divert’.
3945 In ‘m4’, macro substitution is based on text, while in TeX, it is
3946 based on tokens. ‘changeword’ can throw this difference into relief.
3947 For example, here is the same idea represented in TeX and ‘m4’. First,
3950 \def\a{\message{Hello}}
3957 Then, the ‘m4’ version:
3959 ifdef(`changeword', `', `errprint(` skipping: no changeword support
3961 define(`a', `errprint(`Hello')')dnl
3962 changeword(`@\([_a-zA-Z0-9]*\)')
3967 In the TeX example, the first line defines a macro ‘a’ to print the
3968 message ‘Hello’. The second line defines <@> to be usable instead of
3969 <\> as an escape character. The third line defines <\> to be a normal
3970 printing character, not an escape. The fourth line invokes the macro
3971 ‘a’. So, when TeX is run on this file, it displays the message ‘Hello’.
3973 When the ‘m4’ example is passed through ‘m4’, it outputs
3974 ‘errprint(Hello)’. The reason for this is that TeX does lexical
3975 analysis of macro definition when the macro is _defined_. ‘m4’ just
3976 stores the text, postponing the lexical analysis until the macro is
3979 You should note that using ‘changeword’ will slow ‘m4’ down by a
3980 factor of about seven, once it is changed to something other than the
3981 default regular expression. You can invoke ‘changeword’ with the empty
3982 string to restore the default word definition, and regain the parsing
3986 File: m4.info, Node: M4wrap, Prev: Changeword, Up: Input Control
3988 8.5 Saving text until end of input
3989 ==================================
3991 It is possible to ‘save’ some text until the end of the normal input has
3992 been seen. Text can be saved, to be read again by ‘m4’ when the normal
3993 input has been exhausted. This feature is normally used to initiate
3994 cleanup actions before normal exit, e.g., deleting temporary files.
3996 To save input text, use the builtin ‘m4wrap’:
3998 -- Builtin: m4wrap (STRING, ...)
3999 Stores STRING in a safe place, to be reread when end of input is
4000 reached. As a GNU extension, additional arguments are concatenated
4001 with a space to the STRING.
4003 The expansion of ‘m4wrap’ is void. The macro ‘m4wrap’ is
4004 recognized only with parameters.
4006 define(`cleanup', `This is the `cleanup' action.
4011 This is the first and last normal input line.
4012 ⇒This is the first and last normal input line.
4014 ⇒This is the cleanup action.
4016 The saved input is only reread when the end of normal input is seen,
4017 and not if ‘m4exit’ is used to exit ‘m4’.
4019 It is safe to call ‘m4wrap’ from saved text, but then the order in
4020 which the saved text is reread is undefined. If ‘m4wrap’ is not used
4021 recursively, the saved pieces of text are reread in the opposite order
4022 in which they were saved (LIFO—last in, first out). However, this
4023 behavior is likely to change in a future release, to match POSIX, so you
4024 should not depend on this order.
4026 It is possible to emulate POSIX behavior even with older versions of
4027 GNU M4 by including the file ‘m4-1.4.19/examples/wrapfifo.m4’ from the
4031 undivert(`wrapfifo.m4')dnl
4032 ⇒dnl Redefine m4wrap to have FIFO semantics.
4033 ⇒define(`_m4wrap_level', `0')dnl
4035 ⇒`ifdef(`m4wrap'_m4wrap_level,
4036 ⇒ `define(`m4wrap'_m4wrap_level,
4037 ⇒ defn(`m4wrap'_m4wrap_level)`$1')',
4038 ⇒ `builtin(`m4wrap', `define(`_m4wrap_level',
4039 ⇒ incr(_m4wrap_level))dnl
4040 ⇒m4wrap'_m4wrap_level)dnl
4041 ⇒define(`m4wrap'_m4wrap_level, `$1')')')dnl
4042 include(`wrapfifo.m4')
4044 m4wrap(`a`'m4wrap(`c
4045 ', `d')')m4wrap(`b')
4050 It is likewise possible to emulate LIFO behavior without resorting to
4051 the GNU M4 extension of ‘builtin’, by including the file
4052 ‘m4-1.4.19/examples/wraplifo.m4’ from the distribution. (Unfortunately,
4053 both examples shown here share some subtle bugs. See if you can find
4054 and correct them; or *note Answers: Improved m4wrap.).
4057 undivert(`wraplifo.m4')dnl
4058 ⇒dnl Redefine m4wrap to have LIFO semantics.
4059 ⇒define(`_m4wrap_level', `0')dnl
4060 ⇒define(`_m4wrap', defn(`m4wrap'))dnl
4062 ⇒`ifdef(`m4wrap'_m4wrap_level,
4063 ⇒ `define(`m4wrap'_m4wrap_level,
4064 ⇒ `$1'defn(`m4wrap'_m4wrap_level))',
4065 ⇒ `_m4wrap(`define(`_m4wrap_level', incr(_m4wrap_level))dnl
4066 ⇒m4wrap'_m4wrap_level)dnl
4067 ⇒define(`m4wrap'_m4wrap_level, `$1')')')dnl
4068 include(`wraplifo.m4')
4070 m4wrap(`a`'m4wrap(`c
4071 ', `d')')m4wrap(`b')
4076 Here is an example of implementing a factorial function using
4079 define(`f', `ifelse(`$1', `0', `Answer: 0!=1
4080 ', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1')
4081 ', `m4wrap(`f(decr(`$1'), `$2$1*')')')')
4086 ⇒Answer: 10*9*8*7*6*5*4*3*2*1=3628800
4088 Invocations of ‘m4wrap’ at the same recursion level are concatenated
4089 and rescanned as usual:
4094 m4wrap(`a')m4wrap(`a')
4099 however, the transition between recursion levels behaves like an end of
4100 file condition between two input files.
4102 m4wrap(`m4wrap(`)')len(abc')
4105 error→m4:stdin:1: ERROR: end of file in argument list
4108 File: m4.info, Node: File Inclusion, Next: Diversions, Prev: Input Control, Up: Top
4113 ‘m4’ allows you to include named files at any point in the input.
4117 * Include:: Including named files
4118 * Search Path:: Searching for include files
4121 File: m4.info, Node: Include, Next: Search Path, Up: File Inclusion
4123 9.1 Including named files
4124 =========================
4126 There are two builtin macros in ‘m4’ for including files:
4128 -- Builtin: include (FILE)
4129 -- Builtin: sinclude (FILE)
4130 Both macros cause the file named FILE to be read by ‘m4’. When the
4131 end of the file is reached, input is resumed from the previous
4134 The expansion of ‘include’ and ‘sinclude’ is therefore the contents
4137 If FILE does not exist, is a directory, or cannot otherwise be
4138 read, the expansion is void, and ‘include’ will fail with an error
4139 while ‘sinclude’ is silent. The empty string counts as a file that
4142 The macros ‘include’ and ‘sinclude’ are recognized only with
4146 error→m4:stdin:1: cannot open `none': No such file or directory
4149 error→m4:stdin:2: cannot open `': No such file or directory
4156 The rest of this section assumes that ‘m4’ is invoked with the ‘-I’
4157 option (*note Invoking m4: Preprocessor features.) pointing to the
4158 ‘m4-1.4.19/examples’ directory shipped as part of the GNU ‘m4’ package.
4159 The file ‘m4-1.4.19/examples/incl.m4’ in the distribution contains the
4162 $ cat examples/incl.m4
4167 Normally file inclusion is used to insert the contents of a file into
4168 the input stream. The contents of the file will be read by ‘m4’ and
4169 macro calls in the file will be expanded:
4172 define(`foo', `FOO')
4180 The fact that ‘include’ and ‘sinclude’ expand to the contents of the
4181 file can be used to define macros that operate on entire files. Here is
4182 an example, which defines ‘bar’ to expand to the contents of ‘incl.m4’:
4185 define(`bar', include(`incl.m4'))
4187 This is `bar': >>bar<<
4188 ⇒This is bar: >>Include file start
4193 This use of ‘include’ is not trivial, though, as files can contain
4194 quotes, commas, and parentheses, which can interfere with the way the
4195 ‘m4’ parser works. GNU ‘m4’ seamlessly concatenates the file contents
4196 with the next character, even if the included file ended in the middle
4197 of a comment, string, or macro call. These conditions are only treated
4198 as end of file errors if specified as input files on the command line.
4200 In GNU ‘m4’, an alternative method of reading files is using
4201 ‘undivert’ (*note Undivert::) on a named file.
4204 File: m4.info, Node: Search Path, Prev: Include, Up: File Inclusion
4206 9.2 Searching for include files
4207 ===============================
4209 GNU ‘m4’ allows included files to be found in other directories than the
4210 current working directory.
4212 If the ‘--prepend-include’ or ‘-B’ command-line option was provided
4213 (*note Invoking m4: Preprocessor features.), those directories are
4214 searched first, in reverse order that those options were listed on the
4215 command line. Then ‘m4’ looks in the current working directory. Next
4216 comes the directories specified with the ‘--include’ or ‘-I’ option, in
4217 the order found on the command line. Finally, if the ‘M4PATH’
4218 environment variable is set, it is expected to contain a colon-separated
4219 list of directories, which will be searched in order.
4221 If the automatic search for include-files causes trouble, the ‘p’
4222 debug flag (*note Debug Levels::) can help isolate the problem.
4225 File: m4.info, Node: Diversions, Next: Text handling, Prev: File Inclusion, Up: Top
4227 10 Diverting and undiverting output
4228 ***********************************
4230 Diversions are a way of temporarily saving output. The output of ‘m4’
4231 can at any time be diverted to a temporary file, and be reinserted into
4232 the output stream, “undiverted”, again at a later time.
4234 Numbered diversions are counted from 0 upwards, diversion number 0
4235 being the normal output stream. GNU ‘m4’ tries to keep diversions in
4236 memory. However, there is a limit to the overall memory usable by all
4237 diversions taken together (512K, currently). When this maximum is about
4238 to be exceeded, a temporary file is opened to receive the contents of
4239 the biggest diversion still in memory, freeing this memory for other
4240 diversions. When creating the temporary file, ‘m4’ honors the value of
4241 the environment variable ‘TMPDIR’, and falls back to ‘/tmp’. Thus, the
4242 amount of available disk space provides the only real limit on the
4243 number and aggregate size of diversions.
4245 Diversions make it possible to generate output in a different order
4246 than the input was read. It is possible to implement topological
4247 sorting dependencies. For example, GNU Autoconf makes use of diversions
4248 under the hood to ensure that the expansion of a prerequisite macro
4249 appears in the output prior to the expansion of a dependent macro,
4250 regardless of which order the two macros were invoked in the user’s
4255 * Divert:: Diverting output
4256 * Undivert:: Undiverting output
4257 * Divnum:: Diversion numbers
4258 * Cleardivert:: Discarding diverted text
4261 File: m4.info, Node: Divert, Next: Undivert, Up: Diversions
4263 10.1 Diverting output
4264 =====================
4266 Output is diverted using ‘divert’:
4268 -- Builtin: divert ([NUMBER = ‘0’])
4269 The current diversion is changed to NUMBER. If NUMBER is left out
4270 or empty, it is assumed to be zero. If NUMBER cannot be parsed,
4271 the diversion is unchanged.
4273 The expansion of ‘divert’ is void.
4275 When all the ‘m4’ input will have been processed, all existing
4276 diversions are automatically undiverted, in numerical order.
4279 This text is diverted.
4282 This text is not diverted.
4283 ⇒This text is not diverted.
4286 ⇒This text is diverted.
4288 Several calls of ‘divert’ with the same argument do not overwrite the
4289 previous diverted text, but append to it. Diversions are printed after
4290 any wrapped text is expanded.
4292 define(`text', `TEXT')
4294 divert(`1')`diverted text.'
4297 m4wrap(`Wrapped text precedes ')
4300 ⇒Wrapped TEXT precedes diverted text.
4302 If output is diverted to a negative diversion, it is simply
4303 discarded. This can be used to suppress unwanted output. A common
4304 example of unwanted output is the trailing newlines after macro
4305 definitions. Here is a common programming idiom in ‘m4’ for avoiding
4309 define(`foo', `Macro `foo'.')
4310 define(`bar', `Macro `bar'.')
4314 Traditional implementations only supported ten diversions. But as a
4315 GNU extension, diversion numbers can be as large as positive integers
4316 will allow, rather than treating a multi-digit diversion number as a
4317 request to discard text.
4319 divert(eval(`1<<28'))world
4325 Note that ‘divert’ is an English word, but also an active macro
4326 without arguments. When processing plain text, the word might appear in
4327 normal text and be unintentionally swallowed as a macro invocation. One
4328 way to avoid this is to use the ‘-P’ option to rename all builtins
4329 (*note Invoking m4: Operation modes.). Another is to write a wrapper
4330 that requires a parameter to be recognized.
4332 We decided to divert the stream for irrigation.
4333 ⇒We decided to the stream for irrigation.
4334 define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@)')')
4340 We decided to divert the stream for irrigation.
4341 ⇒We decided to divert the stream for irrigation.
4344 File: m4.info, Node: Undivert, Next: Divnum, Prev: Divert, Up: Diversions
4346 10.2 Undiverting output
4347 =======================
4349 Diverted text can be undiverted explicitly using the builtin ‘undivert’:
4351 -- Builtin: undivert ([DIVERSIONS...])
4352 Undiverts the numeric DIVERSIONS given by the arguments, in the
4353 order given. If no arguments are supplied, all diversions are
4354 undiverted, in numerical order.
4356 As a GNU extension, DIVERSIONS may contain non-numeric strings,
4357 which are treated as the names of files to copy into the output
4358 without expansion. A warning is issued if a file could not be
4361 The expansion of ‘undivert’ is void.
4364 This text is diverted.
4367 This text is not diverted.
4368 ⇒This text is not diverted.
4371 ⇒This text is diverted.
4374 Notice the last two blank lines. One of them comes from the newline
4375 following ‘undivert’, the other from the newline that followed the
4376 ‘divert’! A diversion often starts with a blank line like this.
4378 When diverted text is undiverted, it is _not_ reread by ‘m4’, but
4379 rather copied directly to the current output, and it is therefore not an
4380 error to undivert into a diversion. Undiverting the empty string is the
4381 same as specifying diversion 0; in either case nothing happens since the
4382 output has already been flushed.
4384 divert(`1')diverted text
4395 divert(`2')undivert(`1')diverted text`'divert
4403 When a diversion has been undiverted, the diverted text is discarded,
4404 and it is not possible to bring back diverted text more than once.
4407 This text is diverted first.
4408 divert(`0')undivert(`1')dnl
4410 ⇒This text is diverted first.
4414 This text is also diverted but not appended.
4415 divert(`0')undivert(`1')dnl
4417 ⇒This text is also diverted but not appended.
4419 Attempts to undivert the current diversion are silently ignored.
4420 Thus, when the current diversion is not 0, the current diversion does
4421 not get rearranged among the other diversions.
4426 divert(`2')undivert`'dnl
4427 divert`'undivert`'dnl
4432 GNU ‘m4’ allows named files to be undiverted. Given a non-numeric
4433 argument, the contents of the file named will be copied, uninterpreted,
4434 to the current output. This complements the builtin ‘include’ (*note
4435 Include::). To illustrate the difference, assume the file ‘foo’
4443 define(`bar', `BAR')
4452 If the file is not found (or cannot be read), an error message is
4453 issued, and the expansion is void. It is possible to intermix files and
4456 divert(`1')diversion one
4457 divert(`2')undivert(`foo')dnl
4458 divert(`3')diversion three
4460 undivert(`1', `2', `foo', `3')dnl
4467 File: m4.info, Node: Divnum, Next: Cleardivert, Prev: Undivert, Up: Diversions
4469 10.3 Diversion numbers
4470 ======================
4472 The current diversion is tracked by the builtin ‘divnum’:
4475 Expands to the number of the current diversion.
4480 Diversion one: divnum
4482 Diversion two: divnum
4490 File: m4.info, Node: Cleardivert, Prev: Divnum, Up: Diversions
4492 10.4 Discarding diverted text
4493 =============================
4495 Often it is not known, when output is diverted, whether the diverted
4496 text is actually needed. Since all non-empty diversion are brought back
4497 on the main output stream when the end of input is seen, a method of
4498 discarding a diversion is needed. If all diversions should be
4499 discarded, the easiest is to end the input to ‘m4’ with ‘divert(`-1')’
4500 followed by an explicit ‘undivert’:
4503 Diversion one: divnum
4505 Diversion two: divnum
4510 No output is produced at all.
4512 Clearing selected diversions can be done with the following macro:
4514 -- Composite: cleardivert ([DIVERSIONS...])
4515 Discard the contents of each of the listed numeric DIVERSIONS.
4517 define(`cleardivert',
4518 `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
4521 It is called just like ‘undivert’, but the effect is to clear the
4522 diversions, given by the arguments. (This macro has a nasty bug! You
4523 should try to see if you can find it and correct it; or *note Answers:
4524 Improved cleardivert.).
4527 File: m4.info, Node: Text handling, Next: Arithmetic, Prev: Diversions, Up: Top
4529 11 Macros for text handling
4530 ***************************
4532 There are a number of builtins in ‘m4’ for manipulating text in various
4533 ways, extracting substrings, searching, substituting, and so on.
4537 * Len:: Calculating length of strings
4538 * Index macro:: Searching for substrings
4539 * Regexp:: Searching for regular expressions
4540 * Substr:: Extracting substrings
4541 * Translit:: Translating characters
4542 * Patsubst:: Substituting text by regular expression
4543 * Format:: Formatting strings (printf-like)
4546 File: m4.info, Node: Len, Next: Index macro, Up: Text handling
4548 11.1 Calculating length of strings
4549 ==================================
4551 The length of a string can be calculated by ‘len’:
4553 -- Builtin: len (STRING)
4554 Expands to the length of STRING, as a decimal number.
4556 The macro ‘len’ is recognized only with parameters.
4564 File: m4.info, Node: Index macro, Next: Regexp, Prev: Len, Up: Text handling
4566 11.2 Searching for substrings
4567 =============================
4569 Searching for substrings is done with ‘index’:
4571 -- Builtin: index (STRING, SUBSTRING)
4572 Expands to the index of the first occurrence of SUBSTRING in
4573 STRING. The first character in STRING has index 0. If SUBSTRING
4574 does not occur in STRING, ‘index’ expands to ‘-1’.
4576 The macro ‘index’ is recognized only with parameters.
4578 index(`gnus, gnats, and armadillos', `nat')
4580 index(`gnus, gnats, and armadillos', `dag')
4583 Omitting SUBSTRING evokes a warning, but still produces output;
4584 contrast this with an empty SUBSTRING.
4587 error→m4:stdin:1: Warning: too few arguments to builtin `index'
4595 File: m4.info, Node: Regexp, Next: Substr, Prev: Index macro, Up: Text handling
4597 11.3 Searching for regular expressions
4598 ======================================
4600 Searching for regular expressions is done with the builtin ‘regexp’:
4602 -- Builtin: regexp (STRING, REGEXP, [REPLACEMENT])
4603 Searches for REGEXP in STRING. The syntax for regular expressions
4604 is the same as in GNU Emacs, which is similar to BRE, Basic Regular
4605 Expressions in POSIX. *Note Syntax of Regular Expressions:
4606 (emacs)Regexps. Support for ERE, Extended Regular Expressions is
4607 not available, but will be added in GNU M4 2.0.
4609 If REPLACEMENT is omitted, ‘regexp’ expands to the index of the
4610 first match of REGEXP in STRING. If REGEXP does not match anywhere
4611 in STRING, it expands to -1.
4613 If REPLACEMENT is supplied, and there was a match, ‘regexp’ changes
4614 the expansion to this argument, with ‘\N’ substituted by the text
4615 matched by the Nth parenthesized sub-expression of REGEXP, up to
4616 nine sub-expressions. The escape ‘\&’ is replaced by the text of
4617 the entire regular expression matched. For all other characters,
4618 ‘\’ treats the next character literally. A warning is issued if
4619 there were fewer sub-expressions than the ‘\N’ requested, or if
4620 there is a trailing ‘\’. If there was no match, ‘regexp’ expands
4621 to the empty string.
4623 The macro ‘regexp’ is recognized only with parameters.
4625 regexp(`GNUs not Unix', `\<[a-z]\w+')
4627 regexp(`GNUs not Unix', `\<Q\w*')
4629 regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
4630 ⇒*** Unix *** nix ***
4631 regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
4634 Here are some more examples on the handling of backslash:
4636 regexp(`abc', `\(b\)', `\\\10\a')
4638 regexp(`abc', `b', `\1\')
4639 error→m4:stdin:2: Warning: sub-expression 1 not present
4640 error→m4:stdin:2: Warning: trailing \ ignored in replacement
4642 regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6')
4643 error→m4:stdin:3: Warning: sub-expression 4 not present
4644 error→m4:stdin:3: Warning: sub-expression 5 not present
4645 error→m4:stdin:3: Warning: sub-expression 6 not present
4648 Omitting REGEXP evokes a warning, but still produces output; contrast
4649 this with an empty REGEXP argument.
4652 error→m4:stdin:1: Warning: too few arguments to builtin `regexp'
4656 regexp(`abc', `', `\\def')
4660 File: m4.info, Node: Substr, Next: Translit, Prev: Regexp, Up: Text handling
4662 11.4 Extracting substrings
4663 ==========================
4665 Substrings are extracted with ‘substr’:
4667 -- Builtin: substr (STRING, FROM, [LENGTH])
4668 Expands to the substring of STRING, which starts at index FROM, and
4669 extends for LENGTH characters, or to the end of STRING, if LENGTH
4670 is omitted. The starting index of a string is always 0. The
4671 expansion is empty if there is an error parsing FROM or LENGTH, if
4672 FROM is beyond the end of STRING, or if LENGTH is negative.
4674 The macro ‘substr’ is recognized only with parameters.
4676 substr(`gnus, gnats, and armadillos', `6')
4677 ⇒gnats, and armadillos
4678 substr(`gnus, gnats, and armadillos', `6', `5')
4681 Omitting FROM evokes a warning, but still produces output.
4684 error→m4:stdin:1: Warning: too few arguments to builtin `substr'
4687 error→m4:stdin:2: empty string treated as 0 in builtin `substr'
4691 File: m4.info, Node: Translit, Next: Patsubst, Prev: Substr, Up: Text handling
4693 11.5 Translating characters
4694 ===========================
4696 Character translation is done with ‘translit’:
4698 -- Builtin: translit (STRING, CHARS, [REPLACEMENT])
4699 Expands to STRING, with each character that occurs in CHARS
4700 translated into the character from REPLACEMENT with the same index.
4702 If REPLACEMENT is shorter than CHARS, the excess characters of
4703 CHARS are deleted from the expansion; if CHARS is shorter, the
4704 excess characters in REPLACEMENT are silently ignored. If
4705 REPLACEMENT is omitted, all characters in STRING that are present
4706 in CHARS are deleted from the expansion. If a character appears
4707 more than once in CHARS, only the first instance is used in making
4708 the translation. Only a single translation pass is made, even if
4709 characters in REPLACEMENT also appear in CHARS.
4711 As a GNU extension, both CHARS and REPLACEMENT can contain
4712 character-ranges, e.g., ‘a-z’ (meaning all lowercase letters) or
4713 ‘0-9’ (meaning all digits). To include a dash ‘-’ in CHARS or
4714 REPLACEMENT, place it first or last in the entire string, or as the
4715 last character of a range. Back-to-back ranges can share a common
4716 endpoint. It is not an error for the last character in the range
4717 to be ‘larger’ than the first. In that case, the range runs
4718 backwards, i.e., ‘9-0’ means the string ‘9876543210’. The
4719 expansion of a range is dependent on the underlying encoding of
4720 characters, so using ranges is not always portable between
4723 The macro ‘translit’ is recognized only with parameters.
4725 translit(`GNUs not Unix', `A-Z')
4727 translit(`GNUs not Unix', `a-z', `A-Z')
4729 translit(`GNUs not Unix', `A-Z', `z-a')
4731 translit(`+,-12345', `+--1-5', `<;>a-c-a')
4733 translit(`abcdef', `aabdef', `bcged')
4736 In the ASCII encoding, the first example deletes all uppercase
4737 letters, the second converts lowercase to uppercase, and the third
4738 ‘mirrors’ all uppercase letters, while converting them to lowercase.
4739 The two first cases are by far the most common, even though they are not
4740 portable to EBCDIC or other encodings. The fourth example shows a range
4741 ending in ‘-’, as well as back-to-back ranges. The final example shows
4742 that ‘a’ is mapped to ‘b’, not ‘c’; the resulting ‘b’ is not further
4743 remapped to ‘g’; the ‘d’ and ‘e’ are swapped, and the ‘f’ is discarded.
4745 Omitting CHARS evokes a warning, but still produces output.
4748 error→m4:stdin:1: Warning: too few arguments to builtin `translit'
4752 File: m4.info, Node: Patsubst, Next: Format, Prev: Translit, Up: Text handling
4754 11.6 Substituting text by regular expression
4755 ============================================
4757 Global substitution in a string is done by ‘patsubst’:
4759 -- Builtin: patsubst (STRING, REGEXP, [REPLACEMENT])
4760 Searches STRING for matches of REGEXP, and substitutes REPLACEMENT
4761 for each match. The syntax for regular expressions is the same as
4762 in GNU Emacs (*note Regexp::).
4764 The parts of STRING that are not covered by any match of REGEXP are
4765 copied to the expansion. Whenever a match is found, the search
4766 proceeds from the end of the match, so a character from STRING will
4767 never be substituted twice. If REGEXP matches a string of zero
4768 length, the start position for the search is incremented, to avoid
4771 When a replacement is to be made, REPLACEMENT is inserted into the
4772 expansion, with ‘\N’ substituted by the text matched by the Nth
4773 parenthesized sub-expression of PATSUBST, for up to nine
4774 sub-expressions. The escape ‘\&’ is replaced by the text of the
4775 entire regular expression matched. For all other characters, ‘\’
4776 treats the next character literally. A warning is issued if there
4777 were fewer sub-expressions than the ‘\N’ requested, or if there is
4780 The REPLACEMENT argument can be omitted, in which case the text
4781 matched by REGEXP is deleted.
4783 The macro ‘patsubst’ is recognized only with parameters.
4785 patsubst(`GNUs not Unix', `^', `OBS: ')
4787 patsubst(`GNUs not Unix', `\<', `OBS: ')
4788 ⇒OBS: GNUs OBS: not OBS: Unix
4789 patsubst(`GNUs not Unix', `\w*', `(\&)')
4790 ⇒(GNUs)() (not)() (Unix)()
4791 patsubst(`GNUs not Unix', `\w+', `(\&)')
4792 ⇒(GNUs) (not) (Unix)
4793 patsubst(`GNUs not Unix', `[A-Z][a-z]+')
4795 patsubst(`GNUs not Unix', `not', `NOT\')
4796 error→m4:stdin:6: Warning: trailing \ ignored in replacement
4799 Here is a slightly more realistic example, which capitalizes
4800 individual words or whole sentences, by substituting calls of the macros
4801 ‘upcase’ and ‘downcase’ into the strings.
4803 -- Composite: upcase (TEXT)
4804 -- Composite: downcase (TEXT)
4805 -- Composite: capitalize (TEXT)
4806 Expand to TEXT, but with capitalization changed: ‘upcase’ changes
4807 all letters to upper case, ‘downcase’ changes all letters to lower
4808 case, and ‘capitalize’ changes the first character of each word to
4809 upper case and the remaining characters to lower case.
4811 First, an example of their usage, using implementations distributed
4812 in ‘m4-1.4.19/examples/capitalize.m4’.
4815 include(`capitalize.m4')
4817 upcase(`GNUs not Unix')
4819 downcase(`GNUs not Unix')
4821 capitalize(`GNUs not Unix')
4824 Now for the implementation. There is a helper macro ‘_capitalize’
4825 which puts only its first word in mixed case. Then ‘capitalize’ merely
4826 parses out the words, and replaces them with an invocation of
4827 ‘_capitalize’. (As presented here, the ‘capitalize’ macro has some
4828 subtle flaws. You should try to see if you can find and correct them;
4829 or *note Answers: Improved capitalize.).
4832 undivert(`capitalize.m4')dnl
4837 ⇒# change case of text, simple version
4838 ⇒define(`upcase', `translit(`$*', `a-z', `A-Z')')
4839 ⇒define(`downcase', `translit(`$*', `A-Z', `a-z')')
4840 ⇒define(`_capitalize',
4841 ⇒ `regexp(`$1', `^\(\w\)\(\w*\)',
4842 ⇒ `upcase(`\1')`'downcase(`\2')')')
4843 ⇒define(`capitalize', `patsubst(`$1', `\w+', `_$0(`\&')')')
4846 While ‘regexp’ replaces the whole input with the replacement as soon
4847 as there is a match, ‘patsubst’ replaces each _occurrence_ of a match
4848 and preserves non-matching pieces:
4853 patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
4856 patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
4860 Omitting REGEXP evokes a warning, but still produces output; contrast
4861 this with an empty REGEXP argument.
4864 error→m4:stdin:1: Warning: too few arguments to builtin `patsubst'
4868 patsubst(`abc', `', `\\-')
4872 File: m4.info, Node: Format, Prev: Patsubst, Up: Text handling
4874 11.7 Formatting strings (printf-like)
4875 =====================================
4877 Formatted output can be made with ‘format’:
4879 -- Builtin: format (FORMAT-STRING, ...)
4880 Works much like the C function ‘printf’. The first argument
4881 FORMAT-STRING can contain ‘%’ specifications which are satisfied by
4882 additional arguments, and the expansion of ‘format’ is the
4885 The macro ‘format’ is recognized only with parameters.
4887 Its use is best described by a few examples:
4889 define(`foo', `The brown fox jumped over the lazy dog')
4891 format(`The string "%s" uses %d characters', foo, len(foo))
4892 ⇒The string "The brown fox jumped over the lazy dog" uses 38 characters
4893 format(`%*.*d', `-1', `-1', `1')
4895 format(`%.0f', `56789.9876')
4897 len(format(`%-*X', `5000', `1'))
4899 ifelse(format(`%010F', `infinity'), ` INF', `success',
4900 format(`%010F', `infinity'), ` INFINITY', `success',
4901 format(`%010F', `infinity'))
4903 ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success',
4904 format(`%.1A', `1.999'), `0X2.0P+0', `success',
4905 format(`%.1A', `1.999'))
4907 format(`%g', `0xa.P+1')
4910 Using the ‘forloop’ macro defined earlier (*note Forloop::), this
4911 example shows how ‘format’ can be used to produce tabular output.
4914 include(`forloop.m4')
4916 forloop(`i', `1', `10', `format(`%6d squared is %10d
4930 The builtin ‘format’ is modeled after the ANSI C ‘printf’ function,
4931 and supports these ‘%’ specifiers: ‘c’, ‘s’, ‘d’, ‘o’, ‘x’, ‘X’, ‘u’,
4932 ‘a’, ‘A’, ‘e’, ‘E’, ‘f’, ‘F’, ‘g’, ‘G’, and ‘%’; it supports field
4933 widths and precisions, and the flags ‘+’, ‘-’, ‘ ’, ‘0’, ‘#’, and ‘'’.
4934 For integer specifiers, the width modifiers ‘hh’, ‘h’, and ‘l’ are
4935 recognized, and for floating point specifiers, the width modifier ‘l’ is
4936 recognized. Items not yet supported include positional arguments, the
4937 ‘n’, ‘p’, ‘S’, and ‘C’ specifiers, the ‘z’, ‘t’, ‘j’, ‘L’ and ‘ll’
4938 modifiers, and any platform extensions available in the native ‘printf’.
4939 For more details on the functioning of ‘printf’, see the C Library
4940 Manual, or the POSIX specification (for example, ‘%a’ is supported even
4941 on platforms that haven’t yet implemented C99 hexadecimal floating point
4944 Unrecognized specifiers result in a warning. It is anticipated that
4945 a future release of GNU ‘m4’ will support more specifiers, and give
4946 better warnings when various problems such as overflow are encountered.
4947 Likewise, escape sequences are not yet recognized.
4950 error→m4:stdin:1: Warning: unrecognized specifier in `%p'
4954 File: m4.info, Node: Arithmetic, Next: Shell commands, Prev: Text handling, Up: Top
4956 12 Macros for doing arithmetic
4957 ******************************
4959 Integer arithmetic is included in ‘m4’, with a C-like syntax. As
4960 convenient shorthands, there are builtins for simple increment and
4961 decrement operations.
4965 * Incr:: Decrement and increment operators
4966 * Eval:: Evaluating integer expressions
4969 File: m4.info, Node: Incr, Next: Eval, Up: Arithmetic
4971 12.1 Decrement and increment operators
4972 ======================================
4974 Increment and decrement of integers are supported using the builtins
4977 -- Builtin: incr (NUMBER)
4978 -- Builtin: decr (NUMBER)
4979 Expand to the numerical value of NUMBER, incremented or
4980 decremented, respectively, by one. Except for the empty string,
4981 the expansion is empty if NUMBER could not be parsed.
4983 The macros ‘incr’ and ‘decr’ are recognized only with parameters.
4990 error→m4:stdin:3: empty string treated as 0 in builtin `incr'
4993 error→m4:stdin:4: empty string treated as 0 in builtin `decr'
4997 File: m4.info, Node: Eval, Prev: Incr, Up: Arithmetic
4999 12.2 Evaluating integer expressions
5000 ===================================
5002 Integer expressions are evaluated with ‘eval’:
5004 -- Builtin: eval (EXPRESSION, [RADIX = ‘10’], [WIDTH])
5005 Expands to the value of EXPRESSION. The expansion is empty if a
5006 problem is encountered while parsing the arguments. If specified,
5007 RADIX and WIDTH control the format of the output.
5009 Calculations are done with 32-bit signed numbers. Overflow
5010 silently results in wraparound. A warning is issued if division by
5011 zero is attempted, or if EXPRESSION could not be parsed.
5013 Expressions can contain the following operators, listed in order of
5014 decreasing precedence.
5019 Unary plus and minus, and bitwise and logical negation
5023 Multiplication, division, and modulo
5025 Addition and subtraction
5029 Relational operators
5035 Bitwise exclusive-or
5043 The macro ‘eval’ is recognized only with parameters.
5045 All binary operators, except exponentiation, are left associative. C
5046 operators that perform variable assignment, such as ‘+=’ or ‘--’, are
5047 not implemented, since ‘eval’ only operates on constants, not variables.
5048 Attempting to use them results in an error. However, since traditional
5049 implementations treated ‘=’ as an undocumented alias for ‘==’ as opposed
5050 to an assignment operator, this usage is supported as a special case.
5051 Be aware that a future version of GNU M4 may support assignment
5052 semantics as an extension when POSIX mode is not requested, and that
5053 using ‘=’ to check equality is not portable.
5056 error→m4:stdin:1: Warning: recommend ==, not =, for equality operator
5059 error→m4:stdin:2: invalid operator in eval: ++0
5062 error→m4:stdin:3: invalid operator in eval: 0 |= 1
5065 Note that some older ‘m4’ implementations use ‘^’ as an alternate
5066 operator for the exponentiation, although POSIX requires the C behavior
5067 of bitwise exclusive-or. The precedence of the negation operators, ‘~’
5068 and ‘!’, was traditionally lower than equality. The unary operators
5069 could not be used reliably more than once on the same term without
5070 intervening parentheses. The traditional precedence of the equality
5071 operators ‘==’ and ‘!=’ was identical instead of lower than the
5072 relational operators such as ‘<’, even through GNU M4 1.4.8. Starting
5073 with version 1.4.9, GNU M4 correctly follows POSIX precedence rules. M4
5074 scripts designed to be portable between releases must be aware that
5075 parentheses may be required to enforce C precedence rules. Likewise,
5076 division by zero, even in the unused branch of a short-circuiting
5077 operator, is not always well-defined in other implementations.
5079 Following are some examples where the current version of M4 follows C
5080 precedence rules, but where older versions and some other
5081 implementations of ‘m4’ require explicit parentheses to get the correct
5086 eval(`(1 == 2) > 0')
5096 eval(`+ + - ~ ! ~ 0')
5101 error→m4:stdin:9: divide by zero in eval: 0 || 1 / 0
5106 error→m4:stdin:11: modulo by zero in eval: 2 && 1 % 0
5109 As a GNU extension, the operator ‘**’ performs integral
5110 exponentiation. The operator is right-associative, and if evaluated,
5111 the exponent must be non-negative, and at least one of the arguments
5112 must be non-zero, or a warning is issued.
5116 eval(`(2 ** 3) ** 2')
5124 error→m4:stdin:5: divide by zero in eval: 0 ** 0
5126 error→m4:stdin:6: negative exponent in eval: 4 ** -2
5129 Within EXPRESSION, (but not RADIX or WIDTH), numbers without a
5130 special prefix are decimal. A simple ‘0’ prefix introduces an octal
5131 number. ‘0x’ introduces a hexadecimal number. As GNU extensions, ‘0b’
5132 introduces a binary number. ‘0r’ introduces a number expressed in any
5133 radix between 1 and 36: the prefix should be immediately followed by the
5134 decimal expression of the radix, a colon, then the digits making the
5135 number. For radix 1, leading zeros are ignored, and all remaining
5136 digits must be ‘1’; for all other radices, the digits are ‘0’, ‘1’, ‘2’,
5137 .... Beyond ‘9’, the digits are ‘a’, ‘b’ ... up to ‘z’. Lower and
5138 upper case letters can be used interchangeably in numbers prefixes and
5141 Parentheses may be used to group subexpressions whenever needed. For
5142 the relational operators, a true relation returns ‘1’, and a false
5143 relation return ‘0’.
5145 Here are a few examples of use of ‘eval’.
5155 eval(index(`Hello world', `llo') >= 0)
5157 eval(`0r1:0111 + 0b100 + 0r3:12')
5159 define(`square', `eval(`($1) ** 2')')
5163 square(square(`5')` + 1')
5165 define(`foo', `666')
5168 error→m4:stdin:11: bad expression in eval: foo / 6
5173 As the last two lines show, ‘eval’ does not handle macro names, even
5174 if they expand to a valid expression (or part of a valid expression).
5175 Therefore all macros must be expanded before they are passed to ‘eval’.
5177 Some calculations are not portable to other implementations, since
5178 they have undefined semantics in C, but GNU ‘m4’ has well-defined
5179 behavior on overflow. When shifting, an out-of-range shift amount is
5180 implicitly brought into the range of 32-bit signed integers using an
5181 implicit bit-wise and with 0x1f).
5183 define(`max_int', eval(`0x7fffffff'))
5185 define(`min_int', incr(max_int))
5191 ifelse(eval(min_int` / -1'), min_int, `overflow occurred')
5195 eval(`0x80000000 % -1')
5202 If RADIX is specified, it specifies the radix to be used in the
5203 expansion. The default radix is 10; this is also the case if RADIX is
5204 the empty string. A warning results if the radix is outside the range
5205 of 1 through 36, inclusive. The result of ‘eval’ is always taken to be
5206 signed. No radix prefix is output, and for radices greater than 10, the
5207 digits are lower case. The WIDTH argument specifies the minimum output
5208 width, excluding any negative sign. The result is zero-padded to extend
5209 the expansion to the requested width. A warning results if the width is
5210 negative. If RADIX or WIDTH is out of bounds, the expansion of ‘eval’
5219 eval(`666', `6', `10')
5221 eval(`-666', `6', `10')
5225 `0r1:'eval(`10', `1', `11')
5230 error→m4:stdin:9: radix 37 in builtin `eval' out of range
5233 error→m4:stdin:10: negative width to builtin `eval'
5236 error→m4:stdin:11: empty string treated as 0 in builtin `eval'
5240 File: m4.info, Node: Shell commands, Next: Miscellaneous, Prev: Arithmetic, Up: Top
5242 13 Macros for running shell commands
5243 ************************************
5245 There are a few builtin macros in ‘m4’ that allow you to run shell
5246 commands from within ‘m4’.
5248 Note that the definition of a valid shell command is system
5249 dependent. On UNIX systems, this is the typical ‘/bin/sh’. But on
5250 other systems, such as native Windows, the shell has a different syntax
5251 of commands that it understands. Some examples in this chapter assume
5252 ‘/bin/sh’, and also demonstrate how to quit early with a known exit
5253 value if this is not the case.
5257 * Platform macros:: Determining the platform
5258 * Syscmd:: Executing simple commands
5259 * Esyscmd:: Reading the output of commands
5260 * Sysval:: Exit status
5261 * Mkstemp:: Making temporary files
5264 File: m4.info, Node: Platform macros, Next: Syscmd, Up: Shell commands
5266 13.1 Determining the platform
5267 =============================
5269 Sometimes it is desirable for an input file to know which platform ‘m4’
5270 is running on. GNU ‘m4’ provides several macros that are predefined to
5271 expand to the empty string; checking for their existence will confirm
5274 -- Optional builtin: __gnu__
5275 -- Optional builtin: __os2__
5276 -- Optional builtin: os2
5277 -- Optional builtin: __unix__
5278 -- Optional builtin: unix
5279 -- Optional builtin: __windows__
5280 -- Optional builtin: windows
5281 Each of these macros is conditionally defined as needed to describe
5282 the environment of ‘m4’. If defined, each macro expands to the
5283 empty string. For now, these macros silently ignore all arguments,
5284 but in a future release of M4, they might warn if arguments are
5287 When GNU extensions are in effect (that is, when you did not use the
5288 ‘-G’ option, *note Invoking m4: Limits control.), GNU ‘m4’ will define
5289 the macro ‘__gnu__’ to expand to the empty string.
5296 Extensions are ifdef(`__gnu__', `active', `inactive')
5297 ⇒Extensions are active
5304 Extensions are ifdef(`__gnu__', `active', `inactive')
5305 ⇒Extensions are inactive
5307 On UNIX systems, GNU ‘m4’ will define ‘__unix__’ by default, or
5308 ‘unix’ when the ‘-G’ option is specified.
5310 On native Windows systems, GNU ‘m4’ will define ‘__windows__’ by
5311 default, or ‘windows’ when the ‘-G’ option is specified.
5313 On OS/2 systems, GNU ‘m4’ will define ‘__os2__’ by default, or ‘os2’
5314 when the ‘-G’ option is specified.
5316 If GNU ‘m4’ does not provide a platform macro for your system, please
5317 report that as a bug.
5319 define(`provided', `0')
5321 ifdef(`__unix__', `define(`provided', incr(provided))')
5323 ifdef(`__windows__', `define(`provided', incr(provided))')
5325 ifdef(`__os2__', `define(`provided', incr(provided))')
5331 File: m4.info, Node: Syscmd, Next: Esyscmd, Prev: Platform macros, Up: Shell commands
5333 13.2 Executing simple commands
5334 ==============================
5336 Any shell command can be executed, using ‘syscmd’:
5338 -- Builtin: syscmd (SHELL-COMMAND)
5339 Executes SHELL-COMMAND as a shell command.
5341 The expansion of ‘syscmd’ is void, _not_ the output from
5342 SHELL-COMMAND! Output or error messages from SHELL-COMMAND are not
5343 read by ‘m4’. *Note Esyscmd::, if you need to process the command
5346 Prior to executing the command, ‘m4’ flushes its buffers. The
5347 default standard input, output and error of SHELL-COMMAND are the
5348 same as those of ‘m4’.
5350 By default, the SHELL-COMMAND will be used as the argument to the
5351 ‘-c’ option of the ‘/bin/sh’ shell (or the version of ‘sh’
5352 specified by ‘command -p getconf PATH’, if your system supports
5353 that). If you prefer a different shell, the ‘configure’ script can
5354 be given the option ‘--with-syscmd-shell=LOCATION’ to set the
5355 location of an alternative shell at GNU ‘m4’ installation; the
5356 alternative shell must still support ‘-c’.
5358 The macro ‘syscmd’ is recognized only with parameters.
5360 define(`foo', `FOO')
5366 Note how the expansion of ‘syscmd’ keeps the trailing newline of the
5367 command, as well as using the newline that appeared after the macro.
5369 The following is an example of SHELL-COMMAND using the same standard
5372 $ echo "m4wrap(\`syscmd(\`cat')')" | m4
5375 It tells ‘m4’ to read all of its input before executing the wrapped
5376 text, then hand a valid (albeit emptied) pipe as standard input for the
5377 ‘cat’ subcommand. Therefore, you should be careful when using standard
5378 input (either by specifying no files, or by passing ‘-’ as a file name
5379 on the command line, *note Invoking m4: Command line files.), and also
5380 invoking subcommands via ‘syscmd’ or ‘esyscmd’ that consume data from
5381 standard input. When standard input is a seekable file, the subprocess
5382 will pick up with the next character not yet processed by ‘m4’; when it
5383 is a pipe or other non-seekable file, there is no guarantee how much
5384 data will already be buffered by ‘m4’ and thus unavailable to the child.
5387 File: m4.info, Node: Esyscmd, Next: Sysval, Prev: Syscmd, Up: Shell commands
5389 13.3 Reading the output of commands
5390 ===================================
5392 If you want ‘m4’ to read the output of a shell command, use ‘esyscmd’:
5394 -- Builtin: esyscmd (SHELL-COMMAND)
5395 Expands to the standard output of the shell command SHELL-COMMAND.
5397 Prior to executing the command, ‘m4’ flushes its buffers. The
5398 default standard input and standard error of SHELL-COMMAND are the
5399 same as those of ‘m4’. The error output of SHELL-COMMAND is not a
5400 part of the expansion: it will appear along with the error output
5403 By default, the SHELL-COMMAND will be used as the argument to the
5404 ‘-c’ option of the ‘/bin/sh’ shell (or the version of ‘sh’
5405 specified by ‘command -p getconf PATH’, if your system supports
5406 that). If you prefer a different shell, the ‘configure’ script can
5407 be given the option ‘--with-syscmd-shell=LOCATION’ to set the
5408 location of an alternative shell at GNU ‘m4’ installation; the
5409 alternative shell must still support ‘-c’.
5411 The macro ‘esyscmd’ is recognized only with parameters.
5413 define(`foo', `FOO')
5419 Note how the expansion of ‘esyscmd’ keeps the trailing newline of the
5420 command, as well as using the newline that appeared after the macro.
5422 Just as with ‘syscmd’, care must be exercised when sharing standard
5423 input between ‘m4’ and the child process of ‘esyscmd’.
5426 File: m4.info, Node: Sysval, Next: Mkstemp, Prev: Esyscmd, Up: Shell commands
5431 To see whether a shell command succeeded, use ‘sysval’:
5434 Expands to the exit status of the last shell command run with
5435 ‘syscmd’ or ‘esyscmd’. Expands to 0 if no command has been run
5442 ifelse(sysval, `0', `zero', `non-zero')
5454 ifelse(sysval, `0', `zero', `non-zero')
5456 esyscmd(`echo dnl && exit 127')
5465 ‘sysval’ results in 127 if there was a problem executing the command,
5466 for example, if the system-imposed argument length is exceeded, or if
5467 there were not enough resources to fork. It is not possible to
5468 distinguish between failed execution and successful execution that had
5469 an exit status of 127, unless there was output from the child process.
5471 On UNIX platforms, where it is possible to detect when command
5472 execution is terminated by a signal, rather than a normal exit, the
5473 result is the signal number shifted left by eight bits.
5475 dnl This test assumes kill is a shell builtin, and that signals are
5478 `errprint(` skipping: syscmd does not have unix semantics
5480 changequote(`[', `]')
5482 syscmd([/bin/sh -c 'kill -9 $$'; st=$?; test $st = 137 || test $st = 265])
5484 ifelse(sysval, [0], , [errprint([ skipping: shell does not send signal 9
5486 syscmd([kill -9 $$])
5494 esyscmd([kill -9 $$])
5500 File: m4.info, Node: Mkstemp, Prev: Sysval, Up: Shell commands
5502 13.5 Making temporary files
5503 ===========================
5505 Commands specified to ‘syscmd’ or ‘esyscmd’ might need a temporary file,
5506 for output or for some other purpose. There is a builtin macro,
5507 ‘mkstemp’, for making a temporary file:
5509 -- Builtin: mkstemp (TEMPLATE)
5510 -- Builtin: maketemp (TEMPLATE)
5511 Expands to the quoted name of a new, empty file, made from the
5512 string TEMPLATE, which should end with the string ‘XXXXXX’. The
5513 six ‘X’ characters are then replaced with random characters
5514 matching the regular expression ‘[a-zA-Z0-9._-]’, in order to make
5515 the file name unique. If fewer than six ‘X’ characters are found
5516 at the end of ‘template’, the result will be longer than the
5517 template. The created file will have access permissions as if by
5518 ‘chmod =rw,go=’, meaning that the current umask of the ‘m4’ process
5519 is taken into account, and at most only the current user can read
5522 The traditional behavior, standardized by POSIX, is that ‘maketemp’
5523 merely replaces the trailing ‘X’ with the process id, without
5524 creating a file or quoting the expansion, and without ensuring that
5525 the resulting string is a unique file name. In part, this means
5526 that using the same TEMPLATE twice in the same input file will
5527 result in the same expansion. This behavior is a security hole, as
5528 it is very easy for another process to guess the name that will be
5529 generated, and thus interfere with a subsequent use of ‘syscmd’
5530 trying to manipulate that file name. Hence, POSIX has recommended
5531 that all new implementations of ‘m4’ provide the secure ‘mkstemp’
5532 builtin, and that users of ‘m4’ check for its existence.
5534 The expansion is void and an error issued if a temporary file could
5537 The macros ‘mkstemp’ and ‘maketemp’ are recognized only with
5540 If you try this next example, you will most likely get different
5541 output for the two file names, since the replacement characters are
5545 define(`tmp', `oops')
5547 maketemp(`/tmp/fooXXXXXX')
5549 ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))',
5550 `define(`mkstemp', defn(`maketemp'))dnl
5551 errprint(`warning: potentially insecure maketemp implementation
5557 Unless you use the ‘--traditional’ command line option (or ‘-G’,
5558 *note Invoking m4: Limits control.), the GNU version of ‘maketemp’ is
5559 secure. This means that using the same template to multiple calls will
5560 generate multiple files. However, we recommend that you use the new
5561 ‘mkstemp’ macro, introduced in GNU M4 1.4.8, which is secure even in
5562 traditional mode. Also, as of M4 1.4.11, the secure implementation
5563 quotes the resulting file name, so that you are guaranteed to know what
5564 file was created even if the random file name happens to match an
5565 existing macro. Notice that this example is careful to use ‘defn’ to
5566 avoid unintended expansion of ‘foo’.
5569 define(`foo', `errprint(`oops')')
5571 syscmd(`rm -f foo-??????')sysval
5573 define(`file1', maketemp(`foo-XXXXXX'))dnl
5574 ifelse(esyscmd(`echo \` foo-?????? \''), ` foo-?????? ',
5575 `no file', `created')
5577 define(`file2', maketemp(`foo-XX'))dnl
5578 define(`file3', mkstemp(`foo-XXXXXX'))dnl
5579 ifelse(len(defn(`file1')), len(defn(`file2')),
5580 `same length', `different')
5582 ifelse(defn(`file1'), defn(`file2'), `same', `different file')
5584 ifelse(defn(`file2'), defn(`file3'), `same', `different file')
5586 ifelse(defn(`file1'), defn(`file3'), `same', `different file')
5588 syscmd(`rm 'defn(`file1') defn(`file2') defn(`file3'))
5594 File: m4.info, Node: Miscellaneous, Next: Frozen files, Prev: Shell commands, Up: Top
5596 14 Miscellaneous builtin macros
5597 *******************************
5599 This chapter describes various builtins, that do not really belong in
5600 any of the previous chapters.
5604 * Errprint:: Printing error messages
5605 * Location:: Printing current location
5606 * M4exit:: Exiting from ‘m4’
5609 File: m4.info, Node: Errprint, Next: Location, Up: Miscellaneous
5611 14.1 Printing error messages
5612 ============================
5614 You can print error messages using ‘errprint’:
5616 -- Builtin: errprint (MESSAGE, ...)
5617 Prints MESSAGE and the rest of the arguments to standard error,
5618 separated by spaces. Standard error is used, regardless of the
5619 ‘--debugfile’ option (*note Invoking m4: Debugging options.).
5621 The expansion of ‘errprint’ is void. The macro ‘errprint’ is
5622 recognized only with parameters.
5624 errprint(`Invalid arguments to forloop
5626 error→Invalid arguments to forloop
5628 errprint(`1')errprint(`2',`3
5633 A trailing newline is _not_ printed automatically, so it should be
5634 supplied as part of the argument, as in the example. Unfortunately, the
5635 exact output of ‘errprint’ is not very portable to other ‘m4’
5636 implementations: POSIX requires that all arguments be printed, but some
5637 implementations of ‘m4’ only print the first. Furthermore, some BSD
5638 implementations always append a newline for each ‘errprint’ call,
5639 regardless of whether the last argument already had one, and POSIX is
5640 silent on whether this is acceptable.
5643 File: m4.info, Node: Location, Next: M4exit, Prev: Errprint, Up: Miscellaneous
5645 14.2 Printing current location
5646 ==============================
5648 To make it possible to specify the location of an error, three utility
5651 -- Builtin: __file__
5652 -- Builtin: __line__
5653 -- Builtin: __program__
5654 Expand to the quoted name of the current input file, the current
5655 input line number in that file, and the quoted name of the current
5658 errprint(__program__:__file__:__line__: `input error
5660 error→m4:stdin:1: input error
5663 Line numbers start at 1 for each file. If the file was found due to
5664 the ‘-I’ option or ‘M4PATH’ environment variable, that is reflected in
5665 the file name. The syncline option (‘-s’, *note Invoking m4:
5666 Preprocessor features.), and the ‘f’ and ‘l’ flags of ‘debugmode’ (*note
5667 Debug Levels::), also use this notion of current file and line.
5668 Redefining the three location macros has no effect on syncline, debug,
5669 warning, or error message output.
5671 This example reuses the file ‘incl.m4’ mentioned earlier (*note
5675 define(`foo', ``$0' called at __file__:__line__')
5678 ⇒foo called at stdin:2
5681 ⇒foo called at examples/incl.m4:2
5685 The location of macros invoked during the rescanning of macro
5686 expansion text corresponds to the location in the file where the
5687 expansion was triggered, regardless of how many newline characters the
5688 expansion text contains. As of GNU M4 1.4.8, the location of text
5689 wrapped with ‘m4wrap’ (*note M4wrap::) is the point at which the
5690 ‘m4wrap’ was invoked. Previous versions, however, behaved as though
5691 wrapped text came from line 0 of the file “”.
5693 define(`echo', `$@')
5695 define(`foo', `echo(__line__
5705 foo(errprint(__line__
5722 The ‘__program__’ macro behaves like ‘$0’ in shell terminology. If
5723 you invoke ‘m4’ through an absolute path or a link with a different
5724 spelling, rather than by relying on a ‘PATH’ search for plain ‘m4’, it
5725 will affect how ‘__program__’ expands. The intent is that you can use
5726 it to produce error messages with the same formatting that ‘m4’ produces
5727 internally. It can also be used within ‘syscmd’ (*note Syscmd::) to
5728 pick the same version of ‘m4’ that is currently running, rather than
5729 whatever version of ‘m4’ happens to be first in ‘PATH’. It was first
5730 introduced in GNU M4 1.4.6.
5733 File: m4.info, Node: M4exit, Prev: Location, Up: Miscellaneous
5735 14.3 Exiting from ‘m4’
5736 ======================
5738 If you need to exit from ‘m4’ before the entire input has been read, you
5741 -- Builtin: m4exit ([CODE = ‘0’])
5742 Causes ‘m4’ to exit, with exit status CODE. If CODE is left out,
5743 the exit status is zero. If CODE cannot be parsed, or is outside
5744 the range of 0 to 255, the exit status is one. No further input is
5745 read, and all wrapped and diverted text is discarded.
5747 m4wrap(`This text is lost due to `m4exit'.')
5749 divert(`1') So is this.
5752 m4exit And this is never read.
5754 A common use of this is to abort processing:
5756 -- Composite: fatal_error (MESSAGE)
5757 Abort processing with an error message and non-zero status. Prefix
5758 MESSAGE with details about where the error occurred, and print the
5759 resulting string to standard error.
5761 define(`fatal_error',
5762 `errprint(__program__:__file__:__line__`: fatal error: $*
5765 fatal_error(`this is a BAD one, buster')
5766 error→m4:stdin:4: fatal error: this is a BAD one, buster
5768 After this macro call, ‘m4’ will exit with exit status 1. This macro
5769 is only intended for error exits, since the normal exit procedures are
5770 not followed, i.e., diverted text is not undiverted, and saved text
5771 (*note M4wrap::) is not reread. (This macro could be made more robust
5772 to earlier versions of ‘m4’. You should try to see if you can find
5773 weaknesses and correct them; or *note Answers: Improved fatal_error.).
5775 Note that it is still possible for the exit status to be different
5776 than what was requested by ‘m4exit’. If ‘m4’ detects some other error,
5777 such as a write error on standard output, the exit status will be
5778 non-zero even if ‘m4exit’ requested zero.
5780 If standard input is seekable, then the file will be positioned at
5781 the next unread character. If it is a pipe or other non-seekable file,
5782 then there are no guarantees how much data ‘m4’ might have read into
5783 buffers, and thus discarded.
5786 File: m4.info, Node: Frozen files, Next: Compatibility, Prev: Miscellaneous, Up: Top
5788 15 Fast loading of frozen state
5789 *******************************
5791 Some bigger ‘m4’ applications may be built over a common base containing
5792 hundreds of definitions and other costly initializations. Usually, the
5793 common base is kept in one or more declarative files, which files are
5794 listed on each ‘m4’ invocation prior to the user’s input file, or else
5795 each input file uses ‘include’.
5797 Reading the common base of a big application, over and over again,
5798 may be time consuming. GNU ‘m4’ offers some machinery to speed up the
5799 start of an application using lengthy common bases.
5803 * Using frozen files:: Using frozen files
5804 * Frozen file format:: Frozen file format
5807 File: m4.info, Node: Using frozen files, Next: Frozen file format, Up: Frozen files
5809 15.1 Using frozen files
5810 =======================
5812 Suppose a user has a library of ‘m4’ initializations in ‘base.m4’, which
5813 is then used with multiple input files:
5815 $ m4 base.m4 input1.m4
5816 $ m4 base.m4 input2.m4
5817 $ m4 base.m4 input3.m4
5819 Rather than spending time parsing the fixed contents of ‘base.m4’
5820 every time, the user might rather execute:
5822 $ m4 -F base.m4f base.m4
5824 once, and further execute, as often as needed:
5826 $ m4 -R base.m4f input1.m4
5827 $ m4 -R base.m4f input2.m4
5828 $ m4 -R base.m4f input3.m4
5830 with the varying input. The first call, containing the ‘-F’ option,
5831 only reads and executes file ‘base.m4’, defining various application
5832 macros and computing other initializations. Once the input file
5833 ‘base.m4’ has been completely processed, GNU ‘m4’ produces in ‘base.m4f’
5834 a “frozen” file, that is, a file which contains a kind of snapshot of
5835 the ‘m4’ internal state.
5837 Later calls, containing the ‘-R’ option, are able to reload the
5838 internal state of ‘m4’, from ‘base.m4f’, _prior_ to reading any other
5839 input files. This means instead of starting with a virgin copy of ‘m4’,
5840 input will be read after having effectively recovered the effect of a
5841 prior run. In our example, the effect is the same as if file ‘base.m4’
5842 has been read anew. However, this effect is achieved a lot faster.
5844 Only one frozen file may be created or read in any one ‘m4’
5845 invocation. It is not possible to recover two frozen files at once.
5846 However, frozen files may be updated incrementally, through using ‘-R’
5847 and ‘-F’ options simultaneously. For example, if some care is taken,
5850 $ m4 file1.m4 file2.m4 file3.m4 file4.m4
5852 could be broken down in the following sequence, accumulating the same
5855 $ m4 -F file1.m4f file1.m4
5856 $ m4 -R file1.m4f -F file2.m4f file2.m4
5857 $ m4 -R file2.m4f -F file3.m4f file3.m4
5858 $ m4 -R file3.m4f file4.m4
5860 Some care is necessary because not every effort has been made for
5861 this to work in all cases. In particular, the trace attribute of macros
5862 is not handled, nor the current setting of ‘changeword’. Currently,
5863 ‘m4wrap’ and ‘sysval’ also have problems. Also, interactions for some
5864 options of ‘m4’, being used in one call and not in the next, have not
5865 been fully analyzed yet. On the other end, you may be confident that
5866 stacks of ‘pushdef’ definitions are handled correctly, as well as
5867 undefined or renamed builtins, and changed strings for quotes or
5868 comments. And future releases of GNU M4 will improve on the utility of
5871 When an ‘m4’ run is to be frozen, the automatic undiversion which
5872 takes place at end of execution is inhibited. Instead, all positively
5873 numbered diversions are saved into the frozen file. The active
5874 diversion number is also transmitted.
5876 A frozen file to be reloaded need not reside in the current
5877 directory. It is looked up the same way as an ‘include’ file (*note
5880 If the frozen file was generated with a newer version of ‘m4’, and
5881 contains directives that an older ‘m4’ cannot parse, attempting to load
5882 the frozen file with option ‘-R’ will cause ‘m4’ to exit with status 63
5883 to indicate version mismatch.
5886 File: m4.info, Node: Frozen file format, Prev: Using frozen files, Up: Frozen files
5888 15.2 Frozen file format
5889 =======================
5891 Frozen files are sharable across architectures. It is safe to write a
5892 frozen file on one machine and read it on another, given that the second
5893 machine uses the same or newer version of GNU ‘m4’. It is conventional,
5894 but not required, to give a frozen file the suffix of ‘.m4f’.
5896 These are simple (editable) text files, made up of directives, each
5897 starting with a capital letter and ending with a newline (<NL>).
5898 Wherever a directive is expected, the character ‘#’ introduces a comment
5899 line; empty lines are also ignored if they are not part of an embedded
5900 string. In the following descriptions, each LEN refers to the length of
5901 the corresponding strings STR in the next line of input. Numbers are
5902 always expressed in decimal. There are no escape characters. The
5905 ‘C LEN1 , LEN2 <NL> STR1 STR2 <NL>’
5906 Uses STR1 and STR2 as the begin-comment and end-comment strings.
5907 If omitted, then ‘#’ and <NL> are the comment delimiters.
5909 ‘D NUMBER, LEN <NL> STR <NL>’
5910 Selects diversion NUMBER, making it current, then copy STR in the
5911 current diversion. NUMBER may be a negative number for a
5912 non-existing diversion. To merely specify an active selection, use
5913 this command with an empty STR. With 0 as the diversion NUMBER,
5914 STR will be issued on standard output at reload time. GNU ‘m4’
5915 will not produce the ‘D’ directive with non-zero length for
5916 diversion 0, but this can be done with manual edits. This
5917 directive may appear more than once for the same diversion, in
5918 which case the diversion is the concatenation of the various uses.
5919 If omitted, then diversion 0 is current.
5921 ‘F LEN1 , LEN2 <NL> STR1 STR2 <NL>’
5922 Defines, through ‘pushdef’, a definition for STR1 expanding to the
5923 function whose builtin name is STR2. If the builtin does not exist
5924 (for example, if the frozen file was produced by a copy of ‘m4’
5925 compiled with changeword support, but the version of ‘m4’ reloading
5926 was compiled without it), the reload is silent, but any subsequent
5927 use of the definition of STR1 will result in a warning. This
5928 directive may appear more than once for the same name, and its
5929 order, along with ‘T’, is important. If omitted, you will have no
5930 access to any builtins.
5932 ‘Q LEN1 , LEN2 <NL> STR1 STR2 <NL>’
5933 Uses STR1 and STR2 as the begin-quote and end-quote strings. If
5934 omitted, then ‘`’ and ‘'’ are the quote delimiters.
5936 ‘T LEN1 , LEN2 <NL> STR1 STR2 <NL>’
5937 Defines, though ‘pushdef’, a definition for STR1 expanding to the
5938 text given by STR2. This directive may appear more than once for
5939 the same name, and its order, along with ‘F’, is important.
5942 Confirms the format of the file. ‘m4’ 1.4.19 only creates and
5943 understands frozen files where NUMBER is 1. This directive must be
5944 the first non-comment in the file, and may not appear more than
5948 File: m4.info, Node: Compatibility, Next: Answers, Prev: Frozen files, Up: Top
5950 16 Compatibility with other versions of ‘m4’
5951 ********************************************
5953 This chapter describes the many of the differences between this
5954 implementation of ‘m4’, and of other implementations found under UNIX,
5955 such as System V Release 4, Solaris, and BSD flavors. In particular, it
5956 lists the known differences and extensions to POSIX. However, the list
5957 is not necessarily comprehensive.
5959 At the time of this writing, POSIX 2001 (also known as IEEE Std
5960 1003.1-2001) is the latest standard, although a new version of POSIX is
5961 under development and includes several proposals for modifying what ‘m4’
5962 is required to do. The requirements for ‘m4’ are shared between SUSv3
5963 and POSIX, and can be viewed at
5964 <https://www.opengroup.org/onlinepubs/000095399/utilities/m4.html>.
5968 * Extensions:: Extensions in GNU M4
5969 * Incompatibilities:: Facilities in System V m4 not in GNU M4
5970 * Other Incompatibilities:: Other incompatibilities
5973 File: m4.info, Node: Extensions, Next: Incompatibilities, Up: Compatibility
5975 16.1 Extensions in GNU M4
5976 =========================
5978 This version of ‘m4’ contains a few facilities that do not exist in
5979 System V ‘m4’. These extra facilities are all suppressed by using the
5980 ‘-G’ command line option (*note Invoking m4: Limits control.), unless
5981 overridden by other command line options.
5983 • In the ‘$N’ notation for macro arguments, N can contain several
5984 digits, while the System V ‘m4’ only accepts one digit. This
5985 allows macros in GNU ‘m4’ to take any number of arguments, and not
5986 only nine (*note Arguments::).
5988 This means that ‘define(`foo', `$11')’ is ambiguous between
5989 implementations. To portably choose between grabbing the first
5990 parameter and appending 1 to the expansion, or grabbing the
5991 eleventh parameter, you can do the following:
5995 dnl First argument, concatenated with 1
5996 define(`_1', `$1')define(`first1', `_1($@)1')
5998 dnl Eleventh argument, portable
5999 define(`_9', `$9')define(`eleventh', `_9(shift(shift($@)))')
6001 dnl Eleventh argument, GNU style
6002 define(`Eleventh', `$11')
6004 first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
6006 eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
6008 Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
6011 Also see the ‘argn’ macro (*note Shift::).
6013 • The ‘divert’ (*note Divert::) macro can manage more than 9
6014 diversions. GNU ‘m4’ treats all positive numbers as valid
6015 diversions, rather than discarding diversions greater than 9.
6017 • Files included with ‘include’ and ‘sinclude’ are sought in a user
6018 specified search path, if they are not found in the working
6019 directory. The search path is specified by the ‘-I’ option and the
6020 ‘M4PATH’ environment variable (*note Search Path::).
6022 • Arguments to ‘undivert’ can be non-numeric, in which case the named
6023 file will be included uninterpreted in the output (*note
6026 • Formatted output is supported through the ‘format’ builtin, which
6027 is modeled after the C library function ‘printf’ (*note Format::).
6029 • Searches and text substitution through basic regular expressions
6030 are supported by the ‘regexp’ (*note Regexp::) and ‘patsubst’
6031 (*note Patsubst::) builtins. Some BSD implementations use extended
6032 regular expressions instead.
6034 • The output of shell commands can be read into ‘m4’ with ‘esyscmd’
6037 • There is indirect access to any builtin macro with ‘builtin’ (*note
6040 • Macros can be called indirectly through ‘indir’ (*note Indir::).
6042 • The name of the program, the current input file, and the current
6043 input line number are accessible through the builtins
6044 ‘__program__’, ‘__file__’, and ‘__line__’ (*note Location::).
6046 • The format of the output from ‘dumpdef’ and macro tracing can be
6047 controlled with ‘debugmode’ (*note Debug Levels::).
6049 • The destination of trace and debug output can be controlled with
6050 ‘debugfile’ (*note Debug Output::).
6052 • The ‘maketemp’ (*note Mkstemp::) macro behaves like ‘mkstemp’,
6053 creating a new file with a unique name on every invocation, rather
6054 than following the insecure behavior of replacing the trailing ‘X’
6055 characters with the ‘m4’ process id.
6057 • POSIX only requires support for the command line options ‘-s’,
6058 ‘-D’, and ‘-U’, so all other options accepted by GNU M4 are
6059 extensions. *Note Invoking m4::, for a description of these
6062 The debugging and tracing facilities in GNU ‘m4’ are much more
6063 extensive than in most other versions of ‘m4’.
6066 File: m4.info, Node: Incompatibilities, Next: Other Incompatibilities, Prev: Extensions, Up: Compatibility
6068 16.2 Facilities in System V ‘m4’ not in GNU ‘m4’
6069 ================================================
6071 The version of ‘m4’ from System V contains a few facilities that have
6072 not been implemented in GNU ‘m4’ yet. Additionally, POSIX requires some
6073 behaviors that GNU ‘m4’ has not implemented yet. Relying on these
6074 behaviors is non-portable, as a future release of GNU ‘m4’ may change.
6076 • POSIX requires support for multiple arguments to ‘defn’, without
6077 any clarification on how ‘defn’ behaves when one of the multiple
6078 arguments names a builtin. System V ‘m4’ and some other
6079 implementations allow mixing builtins and text macros into a single
6080 macro. GNU ‘m4’ only supports joining multiple text arguments,
6081 although a future implementation may lift this restriction to
6082 behave more like System V. The only portable way to join text
6083 macros with builtins is via helper macros and implicit
6084 concatenation of macro results.
6086 • POSIX requires an application to exit with non-zero status if it
6087 wrote an error message to stderr. This has not yet been
6088 consistently implemented for the various builtins that are required
6089 to issue an error (such as ‘eval’ (*note Eval::) when an argument
6092 • Some traditional implementations only allow reading standard input
6093 once, but GNU ‘m4’ correctly handles multiple instances of ‘-’ on
6096 • POSIX requires ‘m4wrap’ (*note M4wrap::) to act in FIFO (first-in,
6097 first-out) order, but GNU ‘m4’ currently uses LIFO order.
6098 Furthermore, POSIX states that only the first argument to ‘m4wrap’
6099 is saved for later evaluation, but GNU ‘m4’ saves and processes all
6100 arguments, with output separated by spaces.
6102 • POSIX states that builtins that require arguments, but are called
6103 without arguments, have undefined behavior. Traditional
6104 implementations simply behave as though empty strings had been
6105 passed. For example, ‘a`'define`'b’ would expand to ‘ab’. But GNU
6106 ‘m4’ ignores certain builtins if they have missing arguments,
6107 giving ‘adefineb’ for the above example.
6109 • Traditional implementations handle ‘define(`f',`1')’ (*note
6110 Define::) by undefining the entire stack of previous definitions,
6111 and if doing ‘undefine(`f')’ first. GNU ‘m4’ replaces just the top
6112 definition on the stack, as if doing ‘popdef(`f')’ followed by
6113 ‘pushdef(`f',`1')’. POSIX allows either behavior.
6115 • POSIX 2001 requires ‘syscmd’ (*note Syscmd::) to evaluate command
6116 output for macro expansion, but this was a mistake that is
6117 anticipated to be corrected in the next version of POSIX. GNU ‘m4’
6118 follows traditional behavior in ‘syscmd’ where output is not
6119 rescanned, and provides the extension ‘esyscmd’ that does scan the
6122 • At one point, POSIX required ‘changequote(ARG)’ (*note
6123 Changequote::) to use newline as the close quote, but this was a
6124 bug, and the next version of POSIX is anticipated to state that
6125 using empty strings or just one argument is unspecified.
6126 Meanwhile, the GNU ‘m4’ behavior of treating an empty end-quote
6127 delimiter as ‘'’ is not portable, as Solaris treats it as repeating
6128 the start-quote delimiter, and BSD treats it as leaving the
6129 previous end-quote delimiter unchanged. For predictable results,
6130 never call changequote with just one argument, or with empty
6131 strings for arguments.
6133 • At one point, POSIX required ‘changecom(ARG,)’ (*note Changecom::)
6134 to make it impossible to end a comment, but this is a bug, and the
6135 next version of POSIX is anticipated to state that using empty
6136 strings is unspecified. Meanwhile, the GNU ‘m4’ behavior of
6137 treating an empty end-comment delimiter as newline is not portable,
6138 as BSD treats it as leaving the previous end-comment delimiter
6139 unchanged. It is also impossible in BSD implementations to disable
6140 comments, even though that is required by POSIX. For predictable
6141 results, never call changecom with empty strings for arguments.
6143 • Most implementations of ‘m4’ give macros a higher precedence than
6144 comments when parsing, meaning that if the start delimiter given to
6145 ‘changecom’ (*note Changecom::) starts with a macro name, comments
6146 are effectively disabled. POSIX does not specify what the
6147 precedence is, so this version of GNU ‘m4’ parser recognizes
6148 comments, then macros, then quoted strings.
6150 • Traditional implementations allow argument collection, but not
6151 string and comment processing, to span file boundaries. Thus, if
6152 ‘a.m4’ contains ‘len(’, and ‘b.m4’ contains ‘abc)’, ‘m4 a.m4 b.m4’
6153 outputs ‘3’ with traditional ‘m4’, but gives an error message that
6154 the end of file was encountered inside a macro with GNU ‘m4’. On
6155 the other hand, traditional implementations do end of file
6156 processing for files included with ‘include’ or ‘sinclude’ (*note
6157 Include::), while GNU ‘m4’ seamlessly integrates the content of
6158 those files. Thus ‘include(`a.m4')include(`b.m4')’ will output ‘3’
6159 instead of giving an error.
6161 • Traditional ‘m4’ treats ‘traceon’ (*note Trace::) without arguments
6162 as a global variable, independent of named macro tracing. Also,
6163 once a macro is undefined, named tracing of that macro is lost. On
6164 the other hand, when GNU ‘m4’ encounters ‘traceon’ without
6165 arguments, it turns tracing on for all existing definitions at the
6166 time, but does not trace future definitions; ‘traceoff’ without
6167 arguments turns tracing off for all definitions regardless of
6168 whether they were also traced by name; and tracing by name, such as
6169 with ‘-tfoo’ at the command line or ‘traceon(`foo')’ in the input,
6170 is an attribute that is preserved even if the macro is currently
6173 Additionally, while POSIX requires trace output, it makes no
6174 demands on the formatting of that output. Parsing trace output is
6175 not guaranteed to be reliable, even between different releases of
6176 GNU M4; however, the intent is that any future changes in trace
6177 output will only occur under the direction of additional
6178 ‘debugmode’ flags (*note Debug Levels::).
6180 • POSIX requires ‘eval’ (*note Eval::) to treat all operators with
6181 the same precedence as C. However, earlier versions of GNU ‘m4’
6182 followed the traditional behavior of other ‘m4’ implementations,
6183 where bitwise and logical negation (‘~’ and ‘!’) have lower
6184 precedence than equality operators; and where equality operators
6185 (‘==’ and ‘!=’) had the same precedence as relational operators
6186 (such as ‘<’). Use explicit parentheses to ensure proper
6187 precedence. As extensions to POSIX, GNU ‘m4’ gives well-defined
6188 semantics to operations that C leaves undefined, such as when
6189 overflow occurs, when shifting negative numbers, or when performing
6190 division by zero. POSIX also requires ‘=’ to cause an error, but
6191 many traditional implementations allowed it as an alias for ‘==’.
6193 • POSIX 2001 requires ‘translit’ (*note Translit::) to treat each
6194 character of the second and third arguments literally. However, it
6195 is anticipated that the next version of POSIX will allow the GNU
6196 ‘m4’ behavior of treating ‘-’ as a range operator.
6198 • POSIX requires ‘m4’ to honor the locale environment variables of
6199 ‘LANG’, ‘LC_ALL’, ‘LC_CTYPE’, ‘LC_MESSAGES’, and ‘NLSPATH’, but
6200 this has not yet been implemented in GNU ‘m4’.
6202 • POSIX states that only unquoted leading newlines and blanks (that
6203 is, space and tab) are ignored when collecting macro arguments.
6204 However, this appears to be a bug in POSIX, since most traditional
6205 implementations also ignore all whitespace (formfeed, carriage
6206 return, and vertical tab). GNU ‘m4’ follows tradition and ignores
6207 all leading unquoted whitespace.
6209 • A strictly-compliant POSIX client is not allowed to use
6210 command-line arguments not specified by POSIX. However, since this
6211 version of M4 ignores ‘POSIXLY_CORRECT’ and enables the option
6212 ‘--gnu’ by default (*note Invoking m4: Limits control.), a client
6213 desiring to be strictly compliant has no way to disable GNU
6214 extensions that conflict with POSIX when directly invoking the
6215 compiled ‘m4’. A future version of ‘GNU’ M4 will honor the
6216 environment variable ‘POSIXLY_CORRECT’, implicitly enabling
6217 ‘--traditional’ if it is set, in order to allow a
6218 strictly-compliant client. In the meantime, a client needing
6219 strict POSIX compliance can use the workaround of invoking a shell
6220 script wrapper, where the wrapper then adds ‘--traditional’ to the
6221 arguments passed to the compiled ‘m4’.
6224 File: m4.info, Node: Other Incompatibilities, Prev: Incompatibilities, Up: Compatibility
6226 16.3 Other incompatibilities
6227 ============================
6229 There are a few other incompatibilities between this implementation of
6230 ‘m4’, and the System V version.
6232 • GNU ‘m4’ implements sync lines differently from System V ‘m4’, when
6233 text is being diverted. GNU ‘m4’ outputs the sync lines when the
6234 text is being diverted, and System V ‘m4’ when the diverted text is
6237 The problem is which lines and file names should be attached to
6238 text that is being, or has been, diverted. System V ‘m4’ regards
6239 all the diverted text as being generated by the source line
6240 containing the ‘undivert’ call, whereas GNU ‘m4’ regards the
6241 diverted text as being generated at the time it is diverted.
6243 The sync line option is used mostly when using ‘m4’ as a front end
6244 to a compiler. If a diverted line causes a compiler error, the
6245 error messages should most probably refer to the place where the
6246 diversion was made, and not where it was inserted again.
6259 The current ‘m4’ implementation has a limitation that the syncline
6260 output at the start of each diversion occurs no matter what, even
6261 if the previous diversion did not end with a newline. This goes
6262 contrary to the claim that synclines appear on a line by
6263 themselves, so this limitation may be corrected in a future version
6264 of ‘m4’. In the meantime, when using ‘-s’, it is wisest to make
6265 sure all diversions end with newline.
6267 • GNU ‘m4’ makes no attempt at prohibiting self-referential
6275 There is nothing inherently wrong with defining ‘x’ to return ‘x’.
6276 The wrong thing is to expand ‘x’ unquoted, because that would cause
6277 an infinite rescan loop. In ‘m4’, one might use macros to hold
6278 strings, as we do for variables in other programming languages,
6279 further checking them with:
6281 ifelse(defn(`HOLDER'), `VALUE', ...)
6283 In cases like this one, an interdiction for a macro to hold its own
6284 name would be a useless limitation. Of course, this leaves more
6285 rope for the GNU ‘m4’ user to hang himself! Rescanning hangs may
6286 be avoided through careful programming, a little like for endless
6287 loops in traditional programming languages.
6290 File: m4.info, Node: Answers, Next: Copying This Package, Prev: Compatibility, Up: Top
6292 17 Correct version of some examples
6293 ***********************************
6295 Some of the examples in this manuals are buggy or not very robust, for
6296 demonstration purposes. Improved versions of these composite macros are
6301 * Improved exch:: Solution for ‘exch’
6302 * Improved forloop:: Solution for ‘forloop’
6303 * Improved foreach:: Solution for ‘foreach’
6304 * Improved copy:: Solution for ‘copy’
6305 * Improved m4wrap:: Solution for ‘m4wrap’
6306 * Improved cleardivert:: Solution for ‘cleardivert’
6307 * Improved capitalize:: Solution for ‘capitalize’
6308 * Improved fatal_error:: Solution for ‘fatal_error’
6311 File: m4.info, Node: Improved exch, Next: Improved forloop, Up: Answers
6313 17.1 Solution for ‘exch’
6314 ========================
6316 The ‘exch’ macro (*note Arguments::) as presented requires clients to
6317 double quote their arguments. A nicer definition, which lets clients
6318 follow the rule of thumb of one level of quoting per level of
6319 parentheses, involves adding quotes in the definition of ‘exch’, as
6322 define(`exch', ``$2', `$1'')
6324 define(exch(`expansion text', `macro'))
6330 File: m4.info, Node: Improved forloop, Next: Improved foreach, Prev: Improved exch, Up: Answers
6332 17.2 Solution for ‘forloop’
6333 ===========================
6335 The ‘forloop’ macro (*note Forloop::) as presented earlier can go into
6336 an infinite loop if given an iterator that is not parsed as a macro
6337 name. It does not do any sanity checking on its numeric bounds, and
6338 only permits decimal numbers for bounds. Here is an improved version,
6339 shipped as ‘m4-1.4.19/examples/forloop2.m4’; this version also optimizes
6340 overhead by calling four macros instead of six per iteration (excluding
6341 those in TEXT), by not dereferencing the ITERATOR in the helper
6345 undivert(`forloop2.m4')dnl
6347 ⇒# forloop(var, from, to, stmt) - improved version:
6348 ⇒# works even if VAR is not a strict macro name
6349 ⇒# performs sanity check that FROM is larger than TO
6350 ⇒# allows complex numerical expressions in TO and FROM
6351 ⇒define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
6352 ⇒ `pushdef(`$1')_$0(`$1', eval(`$2'),
6353 ⇒ eval(`$3'), `$4')popdef(`$1')')')
6355 ⇒ `define(`$1', `$2')$4`'ifelse(`$2', `$3', `',
6356 ⇒ `$0(`$1', incr(`$2'), `$3', `$4')')')
6358 include(`forloop2.m4')
6360 forloop(`i', `2', `1', `no iteration occurs')
6362 forloop(`', `1', `2', ` odd iterator name')
6363 ⇒ odd iterator name odd iterator name
6364 forloop(`i', `5 + 5', `0xc', ` 0x`'eval(i, `16')')
6366 forloop(`i', `a', `b', `non-numeric bounds')
6367 error→m4:stdin:6: bad expression in eval (bad input): (a) <= (b)
6370 One other change to notice is that the improved version used ‘_$0’
6371 rather than ‘_foreach’ to invoke the helper routine. In general, this
6372 is a good practice to follow, because then the set of macros can be
6373 uniformly transformed. The following example shows a transformation
6374 that doubles the current quoting and appends a suffix ‘2’ to each
6375 transformed macro. If ‘foreach’ refers to the literal ‘_foreach’, then
6376 ‘foreach2’ invokes ‘_foreach’ instead of the intended ‘_foreach2’, and
6377 the mixing of quoting paradigms leads to an infinite recursion loop in
6380 $ m4 -d -L 9 -I examples
6381 define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4')
6383 define(`double', `define(`$1'`2',
6384 arg1(patsubst(dquote(defn(`$1')), `[`']', `\&\&')))')
6386 double(`forloop')double(`_forloop')defn(`forloop2')
6387 ⇒ifelse(eval(``($2) <= ($3)''), ``1'',
6388 ⇒ ``pushdef(``$1'')_$0(``$1'', eval(``$2''),
6389 ⇒ eval(``$3''), ``$4'')popdef(``$1'')'')
6390 forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
6392 changequote(`[', `]')changequote([``], [''])
6394 forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
6396 changequote`'include(`forloop.m4')
6398 double(`forloop')double(`_forloop')defn(`forloop2')
6399 ⇒pushdef(``$1'', ``$2'')_forloop($@)popdef(``$1'')
6400 forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
6402 changequote(`[', `]')changequote([``], [''])
6404 forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
6405 error→m4:stdin:12: recursion limit of 9 exceeded, use -L<N> to change it
6407 One more optimization is still possible. Instead of repeatedly
6408 assigning a variable then invoking or dereferencing it, it is possible
6409 to pass the current iterator value as a single argument. Coupled with
6410 ‘curry’ if other arguments are needed (*note Composition::), or with
6411 helper macros if the argument is needed in more than one place in the
6412 expansion, the output can be generated with three, rather than four,
6413 macros of overhead per iteration. Notice how the file
6414 ‘m4-1.4.19/examples/forloop3.m4’ rearranges the arguments of the helper
6415 ‘_forloop’ to take two arguments that are placed around the current
6416 value. By splitting a balanced set of parantheses across multiple
6417 arguments, the helper macro can now be shared by ‘forloop’ and the new
6421 include(`forloop3.m4')
6423 undivert(`forloop3.m4')dnl
6425 ⇒# forloop_arg(from, to, macro) - invoke MACRO(value) for
6426 ⇒# each value between FROM and TO, without define overhead
6427 ⇒define(`forloop_arg', `ifelse(eval(`($1) <= ($2)'), `1',
6428 ⇒ `_forloop(`$1', eval(`$2'), `$3(', `)')')')
6429 ⇒# forloop(var, from, to, stmt) - refactored to share code
6430 ⇒define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
6431 ⇒ `pushdef(`$1')_forloop(eval(`$2'), eval(`$3'),
6432 ⇒ `define(`$1',', `)$4')popdef(`$1')')')
6434 ⇒ `$3`$1'$4`'ifelse(`$1', `$2', `',
6435 ⇒ `$0(incr(`$1'), `$2', `$3', `$4')')')
6437 forloop(`i', `1', `3', ` i')
6439 define(`echo', `$@')
6441 forloop_arg(`1', `3', ` echo')
6445 forloop_arg(`1', `3', `curry(`pushdef', `a')')
6456 Of course, it is possible to make even more improvements, such as
6457 adding an optional step argument, or allowing iteration through
6458 descending sequences. GNU Autoconf provides some of these additional
6459 bells and whistles in its ‘m4_for’ macro.
6462 File: m4.info, Node: Improved foreach, Next: Improved copy, Prev: Improved forloop, Up: Answers
6464 17.3 Solution for ‘foreach’
6465 ===========================
6467 The ‘foreach’ and ‘foreachq’ macros (*note Foreach::) as presented
6468 earlier each have flaws. First, we will examine and fix the quadratic
6469 behavior of ‘foreachq’:
6472 include(`foreachq.m4')
6474 traceon(`shift')debugmode(`aq')
6476 foreachq(`x', ``1', `2', `3', `4'', `x
6479 error→m4trace: -3- shift(`1', `2', `3', `4')
6480 error→m4trace: -2- shift(`1', `2', `3', `4')
6482 error→m4trace: -4- shift(`1', `2', `3', `4')
6483 error→m4trace: -3- shift(`2', `3', `4')
6484 error→m4trace: -3- shift(`1', `2', `3', `4')
6485 error→m4trace: -2- shift(`2', `3', `4')
6487 error→m4trace: -5- shift(`1', `2', `3', `4')
6488 error→m4trace: -4- shift(`2', `3', `4')
6489 error→m4trace: -3- shift(`3', `4')
6490 error→m4trace: -4- shift(`1', `2', `3', `4')
6491 error→m4trace: -3- shift(`2', `3', `4')
6492 error→m4trace: -2- shift(`3', `4')
6494 error→m4trace: -6- shift(`1', `2', `3', `4')
6495 error→m4trace: -5- shift(`2', `3', `4')
6496 error→m4trace: -4- shift(`3', `4')
6497 error→m4trace: -3- shift(`4')
6499 Each successive iteration was adding more quoted ‘shift’ invocations,
6500 and the entire list contents were passing through every iteration. In
6501 general, when recursing, it is a good idea to make the recursion use
6502 fewer arguments, rather than adding additional quoted uses of ‘shift’.
6503 By doing so, ‘m4’ uses less memory, invokes fewer macros, is less likely
6504 to run into machine limits, and most importantly, performs faster. The
6505 fixed version of ‘foreachq’ can be found in
6506 ‘m4-1.4.19/examples/foreachq2.m4’:
6509 include(`foreachq2.m4')
6511 undivert(`foreachq2.m4')dnl
6512 ⇒include(`quote.m4')dnl
6514 ⇒# foreachq(x, `item_1, item_2, ..., item_n', stmt)
6515 ⇒# quoted list, improved version
6516 ⇒define(`foreachq', `pushdef(`$1')_$0($@)popdef(`$1')')
6517 ⇒define(`_arg1q', ``$1'')
6518 ⇒define(`_rest', `ifelse(`$#', `1', `', `dquote(shift($@))')')
6519 ⇒define(`_foreachq', `ifelse(`$2', `', `',
6520 ⇒ `define(`$1', _arg1q($2))$3`'$0(`$1', _rest($2), `$3')')')
6522 traceon(`shift')debugmode(`aq')
6524 foreachq(`x', ``1', `2', `3', `4'', `x
6527 error→m4trace: -3- shift(`1', `2', `3', `4')
6529 error→m4trace: -3- shift(`2', `3', `4')
6531 error→m4trace: -3- shift(`3', `4')
6534 Note that the fixed version calls unquoted helper macros in
6535 ‘_foreachq’ to trim elements immediately; those helper macros in turn
6536 must re-supply the layer of quotes lost in the macro invocation.
6537 Contrast the use of ‘_arg1q’, which quotes the first list element, with
6538 ‘_arg1’ of the earlier implementation that returned the first list
6539 element directly. Additionally, by calling the helper method
6540 immediately, the ‘defn(`ITERATOR')’ no longer contains unexpanded
6543 The astute m4 programmer might notice that the solution above still
6544 uses more memory and macro invocations, and thus more time, than
6545 strictly necessary. Note that ‘$2’, which contains an arbitrarily long
6546 quoted list, is expanded and rescanned three times per iteration of
6547 ‘_foreachq’. Furthermore, every iteration of the algorithm effectively
6548 unboxes then reboxes the list, which costs a couple of macro
6549 invocations. It is possible to rewrite the algorithm for a bit more
6550 speed by swapping the order of the arguments to ‘_foreachq’ in order to
6551 operate on an unboxed list in the first place, and by using the
6552 fixed-length ‘$#’ instead of an arbitrary length list as the key to end
6553 recursion. The result is an overhead of six macro invocations per loop
6554 (excluding any macros in TEXT), instead of eight. This alternative
6555 approach is available as ‘m4-1.4.19/examples/foreach3.m4’:
6558 include(`foreachq3.m4')
6560 undivert(`foreachq3.m4')dnl
6562 ⇒# foreachq(x, `item_1, item_2, ..., item_n', stmt)
6563 ⇒# quoted list, alternate improved version
6564 ⇒define(`foreachq', `ifelse(`$2', `', `',
6565 ⇒ `pushdef(`$1')_$0(`$1', `$3', `', $2)popdef(`$1')')')
6566 ⇒define(`_foreachq', `ifelse(`$#', `3', `',
6567 ⇒ `define(`$1', `$4')$2`'$0(`$1', `$2',
6568 ⇒ shift(shift(shift($@))))')')
6570 traceon(`shift')debugmode(`aq')
6572 foreachq(`x', ``1', `2', `3', `4'', `x
6575 error→m4trace: -4- shift(`x', `x
6576 error→', `', `1', `2', `3', `4')
6577 error→m4trace: -3- shift(`x
6578 error→', `', `1', `2', `3', `4')
6579 error→m4trace: -2- shift(`', `1', `2', `3', `4')
6581 error→m4trace: -4- shift(`x', `x
6582 error→', `1', `2', `3', `4')
6583 error→m4trace: -3- shift(`x
6584 error→', `1', `2', `3', `4')
6585 error→m4trace: -2- shift(`1', `2', `3', `4')
6587 error→m4trace: -4- shift(`x', `x
6588 error→', `2', `3', `4')
6589 error→m4trace: -3- shift(`x
6590 error→', `2', `3', `4')
6591 error→m4trace: -2- shift(`2', `3', `4')
6593 error→m4trace: -4- shift(`x', `x
6595 error→m4trace: -3- shift(`x
6597 error→m4trace: -2- shift(`3', `4')
6599 In the current version of M4, every instance of ‘$@’ is rescanned as
6600 it is encountered. Thus, the ‘foreachq3.m4’ alternative uses much less
6601 memory than ‘foreachq2.m4’, and executes as much as 10% faster, since
6602 each iteration encounters fewer ‘$@’. However, the implementation of
6603 rescanning every byte in ‘$@’ is quadratic in the number of bytes
6604 scanned (for example, making the broken version in ‘foreachq.m4’ cubic,
6605 rather than quadratic, in behavior). A future release of M4 will
6606 improve the underlying implementation by reusing results of previous
6607 scans, so that both styles of ‘foreachq’ can become linear in the number
6608 of bytes scanned. Notice how the implementation injects an empty
6609 argument prior to expanding ‘$2’ within ‘foreachq’; the helper macro
6610 ‘_foreachq’ then ignores the third argument altogether, and ends
6611 recursion when there are three arguments left because there was nothing
6612 left to pass through ‘shift’. Thus, each iteration only needs one
6613 ‘ifelse’, rather than the two conditionals used in the version from
6616 So far, all of the implementations of ‘foreachq’ presented have been
6617 quadratic with M4 1.4.x. But ‘forloop’ is linear, because each
6618 iteration parses a constant amount of arguments. So, it is possible to
6619 design a variant that uses ‘forloop’ to do the iteration, then uses ‘$@’
6620 only once at the end, giving a linear result even with older M4
6621 implementations. This implementation relies on the GNU extension that
6622 ‘$10’ expands to the tenth argument rather than the first argument
6623 concatenated with ‘0’. The trick is to define an intermediate macro
6624 that repeats the text ‘m4_define(`$1', `$N')$2`'’, with ‘n’ set to
6625 successive integers corresponding to each argument. The helper macro
6626 ‘_foreachq_’ is needed in order to generate the literal sequences such
6627 as ‘$1’ into the intermediate macro, rather than expanding them as the
6628 arguments of ‘_foreachq’. With this approach, no ‘shift’ calls are even
6629 needed! Even though there are seven macros of overhead per iteration
6630 instead of six in ‘foreachq3.m4’, the linear scaling is apparent at
6631 relatively small list sizes. However, this approach will need
6632 adjustment when a future version of M4 follows POSIX by no longer
6633 treating ‘$10’ as the tenth argument; the anticipation is that ‘${10}’
6634 can be used instead, although that alternative syntax is not yet
6638 include(`foreachq4.m4')
6640 undivert(`foreachq4.m4')dnl
6641 ⇒include(`forloop2.m4')dnl
6643 ⇒# foreachq(x, `item_1, item_2, ..., item_n', stmt)
6644 ⇒# quoted list, version based on forloop
6646 ⇒`ifelse(`$2', `', `', `_$0(`$1', `$3', $2)')')
6647 ⇒define(`_foreachq',
6648 ⇒`pushdef(`$1', forloop(`$1', `3', `$#',
6649 ⇒ `$0_(`1', `2', indir(`$1'))')`popdef(
6650 ⇒ `$1')')indir(`$1', $@)')
6651 ⇒define(`_foreachq_',
6652 ⇒``define(`$$1', `$$3')$$2`''')
6654 traceon(`shift')debugmode(`aq')
6656 foreachq(`x', ``1', `2', `3', `4'', `x
6663 For yet another approach, the improved version of ‘foreach’,
6664 available in ‘m4-1.4.19/examples/foreach2.m4’, simply overquotes the
6665 arguments to ‘_foreach’ to begin with, using ‘dquote_elt’. Then
6666 ‘_foreach’ can just use ‘_arg1’ to remove the extra layer of quoting
6667 that was added up front:
6670 include(`foreach2.m4')
6672 undivert(`foreach2.m4')dnl
6673 ⇒include(`quote.m4')dnl
6675 ⇒# foreach(x, (item_1, item_2, ..., item_n), stmt)
6676 ⇒# parenthesized list, improved version
6677 ⇒define(`foreach', `pushdef(`$1')_$0(`$1',
6678 ⇒ (dquote(dquote_elt$2)), `$3')popdef(`$1')')
6679 ⇒define(`_arg1', `$1')
6680 ⇒define(`_foreach', `ifelse(`$2', `(`')', `',
6681 ⇒ `define(`$1', _arg1$2)$3`'$0(`$1', (dquote(shift$2)), `$3')')')
6683 traceon(`shift')debugmode(`aq')
6685 foreach(`x', `(`1', `2', `3', `4')', `x
6687 error→m4trace: -4- shift(`1', `2', `3', `4')
6688 error→m4trace: -4- shift(`2', `3', `4')
6689 error→m4trace: -4- shift(`3', `4')
6691 error→m4trace: -3- shift(``1'', ``2'', ``3'', ``4'')
6693 error→m4trace: -3- shift(``2'', ``3'', ``4'')
6695 error→m4trace: -3- shift(``3'', ``4'')
6697 error→m4trace: -3- shift(``4'')
6699 It is likewise possible to write a variant of ‘foreach’ that performs
6700 in linear time on M4 1.4.x; the easiest method is probably writing a
6701 version of ‘foreach’ that unboxes its list, then invokes ‘_foreachq’ as
6702 previously defined in ‘foreachq4.m4’.
6704 In summary, recursion over list elements is trickier than it appeared
6705 at first glance, but provides a powerful idiom within ‘m4’ processing.
6706 As a final demonstration, both list styles are now able to handle
6707 several scenarios that would wreak havoc on one or both of the original
6708 implementations. This points out one other difference between the list
6709 styles. ‘foreach’ evaluates unquoted list elements only once, in
6710 preparation for calling ‘_foreach’, similary for ‘foreachq’ as provided
6711 by ‘foreachq3.m4’ or ‘foreachq4.m4’. But ‘foreachq’, as provided by
6712 ‘foreachq2.m4’, evaluates unquoted list elements twice while visiting
6713 the first list element, once in ‘_arg1q’ and once in ‘_rest’. When
6714 deciding which list style to use, one must take into account whether
6715 repeating the side effects of unquoted list elements will have any
6716 detrimental effects.
6719 include(`foreach2.m4')
6721 include(`foreachq2.m4')
6724 foreach(`x', `', `<x>') / foreachq(`x', `', `<x>')
6726 dnl 1-element list of empty element
6727 foreach(`x', `()', `<x>') / foreachq(`x', ``'', `<x>')
6729 dnl 2-element list of empty elements
6730 foreach(`x', `(`',`')', `<x>') / foreachq(`x', ``',`'', `<x>')
6732 dnl 1-element list of a comma
6733 foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', `<x>')
6735 dnl 2-element list of unbalanced parentheses
6736 foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>')
6738 define(`ab', `oops')dnl using defn(`iterator')
6739 foreach(`x', `(`a', `b')', `defn(`x')') /dnl
6740 foreachq(`x', ``a', `b'', `defn(`x')')
6742 define(`active', `ACT, IVE')
6746 dnl list of unquoted macros; expansion occurs before recursion
6747 foreach(`x', `(active, active)', `<x>
6749 error→m4trace: -4- active -> `ACT, IVE'
6750 error→m4trace: -4- active -> `ACT, IVE'
6755 foreachq(`x', `active, active', `<x>
6757 error→m4trace: -3- active -> `ACT, IVE'
6758 error→m4trace: -3- active -> `ACT, IVE'
6760 error→m4trace: -3- active -> `ACT, IVE'
6761 error→m4trace: -3- active -> `ACT, IVE'
6765 dnl list of quoted macros; expansion occurs during recursion
6766 foreach(`x', `(`active', `active')', `<x>
6768 error→m4trace: -1- active -> `ACT, IVE'
6770 error→m4trace: -1- active -> `ACT, IVE'
6772 foreachq(`x', ``active', `active'', `<x>
6774 error→m4trace: -1- active -> `ACT, IVE'
6776 error→m4trace: -1- active -> `ACT, IVE'
6778 dnl list of double-quoted macro names; no expansion
6779 foreach(`x', `(``active'', ``active'')', `<x>
6783 foreachq(`x', ```active'', ``active''', `<x>
6789 File: m4.info, Node: Improved copy, Next: Improved m4wrap, Prev: Improved foreach, Up: Answers
6791 17.4 Solution for ‘copy’
6792 ========================
6794 The macro ‘copy’ presented above is unable to handle builtin tokens with
6795 M4 1.4.x, because it tries to pass the builtin token through the macro
6796 ‘curry’, where it is silently flattened to an empty string (*note
6797 Composition::). Rather than using the problematic ‘curry’ to work
6798 around the limitation that ‘stack_foreach’ expects to invoke a macro
6799 that takes exactly one argument, we can write a new macro that lets us
6800 form the exact two-argument ‘pushdef’ call sequence needed, so that we
6801 are no longer passing a builtin token through a text macro.
6803 -- Composite: stack_foreach_sep (MACRO, PRE, POST, SEP)
6804 -- Composite: stack_foreach_sep_lifo (MACRO, PRE, POST, SEP)
6805 For each of the ‘pushdef’ definitions associated with MACRO, expand
6806 the sequence ‘PRE`'definition`'POST’. Additionally, expand SEP
6807 between definitions. ‘stack_foreach_sep’ visits the oldest
6808 definition first, while ‘stack_foreach_sep_lifo’ visits the current
6809 definition first. The expansion may dereference MACRO, but should
6810 not modify it. There are a few special macros, such as ‘defn’,
6811 which cannot be used as the MACRO parameter.
6813 Note that ‘stack_foreach(`MACRO', `ACTION')’ is equivalent to
6814 ‘stack_foreach_sep(`MACRO', `ACTION(', `)')’. By supplying explicit
6815 parentheses, split among the PRE and POST arguments to
6816 ‘stack_foreach_sep’, it is now possible to construct macro calls with
6817 more than one argument, without passing builtin tokens through a macro
6818 call. It is likewise possible to directly reference the stack
6819 definitions without a macro call, by leaving PRE and POST empty. Thus,
6820 in addition to fixing ‘copy’ on builtin tokens, it also executes with
6821 fewer macro invocations.
6823 The new macro also adds a separator that is only output after the
6824 first iteration of the helper ‘_stack_reverse_sep’, implemented by
6825 prepending the original SEP to PRE and omitting a SEP argument in
6826 subsequent iterations. Note that the empty string that separates SEP
6827 from PRE is provided as part of the fourth argument when originally
6828 calling ‘_stack_reverse_sep’, and not by writing ‘$4`'$3’ as the third
6829 argument in the recursive call; while the other approach would give the
6830 same output, it does so at the expense of increasing the argument size
6831 on each iteration of ‘_stack_reverse_sep’, which results in quadratic
6832 instead of linear execution time. The improved stack walking macros are
6833 available in ‘m4-1.4.19/examples/stack_sep.m4’:
6836 include(`stack_sep.m4')
6838 define(`copy', `ifdef(`$2', `errprint(`$2 already defined
6840 `stack_foreach_sep(`$1', `pushdef(`$2',', `)')')')dnl
6841 pushdef(`a', `1')pushdef(`a', defn(`divnum'))
6851 pushdef(`c', `1')pushdef(`c', `2')
6853 stack_foreach_sep_lifo(`c', `', `', `, ')
6855 undivert(`stack_sep.m4')dnl
6857 ⇒# stack_foreach_sep(macro, pre, post, sep)
6858 ⇒# Invoke PRE`'defn`'POST with a single argument of each definition
6859 ⇒# from the definition stack of MACRO, starting with the oldest, and
6860 ⇒# separated by SEP between definitions.
6861 ⇒define(`stack_foreach_sep',
6862 ⇒`_stack_reverse_sep(`$1', `tmp-$1')'dnl
6863 ⇒`_stack_reverse_sep(`tmp-$1', `$1', `$2`'defn(`$1')$3', `$4`'')')
6864 ⇒# stack_foreach_sep_lifo(macro, pre, post, sep)
6865 ⇒# Like stack_foreach_sep, but starting with the newest definition.
6866 ⇒define(`stack_foreach_sep_lifo',
6867 ⇒`_stack_reverse_sep(`$1', `tmp-$1', `$2`'defn(`$1')$3', `$4`'')'dnl
6868 ⇒`_stack_reverse_sep(`tmp-$1', `$1')')
6869 ⇒define(`_stack_reverse_sep',
6870 ⇒`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0(
6871 ⇒ `$1', `$2', `$4$3')')')
6875 File: m4.info, Node: Improved m4wrap, Next: Improved cleardivert, Prev: Improved copy, Up: Answers
6877 17.5 Solution for ‘m4wrap’
6878 ==========================
6880 The replacement ‘m4wrap’ versions presented above, designed to guarantee
6881 FIFO or LIFO order regardless of the underlying M4 implementation, share
6882 a bug when dealing with wrapped text that looks like parameter
6883 expansion. Note how the invocation of ‘m4wrapN’ interprets these
6884 parameters, while using the builtin preserves them for their intended
6888 include(`wraplifo.m4')
6890 m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
6893 builtin(`m4wrap', ``'define(`bar', ``$0:'-$1-$*-$#-')bar(`a', `b')
6900 Additionally, the computation of ‘_m4wrap_level’ and creation of
6901 multiple ‘m4wrapN’ placeholders in the original examples is more
6902 expensive in time and memory than strictly necessary. Notice how the
6903 improved version grabs the wrapped text via ‘defn’ to avoid parameter
6904 expansion, then undefines ‘_m4wrap_text’, before stripping a level of
6905 quotes with ‘_arg1’ to expand the text. That way, each level of
6906 wrapping reuses the single placeholder, which starts each nesting level
6907 in an undefined state.
6909 Finally, it is worth emulating the GNU M4 extension of saving all
6910 arguments to ‘m4wrap’, separated by a space, rather than saving just the
6911 first argument. This is done with the ‘join’ macro documented
6912 previously (*note Shift::). The improved LIFO example is shipped as
6913 ‘m4-1.4.19/examples/wraplifo2.m4’, and can easily be converted to a FIFO
6914 solution by swapping the adjacent invocations of ‘joinall’ and ‘defn’.
6917 include(`wraplifo2.m4')
6919 undivert(`wraplifo2.m4')dnl
6920 ⇒dnl Redefine m4wrap to have LIFO semantics, improved example.
6921 ⇒include(`join.m4')dnl
6922 ⇒define(`_m4wrap', defn(`m4wrap'))dnl
6923 ⇒define(`_arg1', `$1')dnl
6926 ⇒ `define(`_$0_text', joinall(` ', $@)defn(`_$0_text'))',
6927 ⇒ `_$0(`_arg1(defn(`_$0_text')undefine(`_$0_text'))')dnl
6928 ⇒define(`_$0_text', joinall(` ', $@))')')dnl
6929 m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
6933 m4wrap(`nested', `', `$@
6942 File: m4.info, Node: Improved cleardivert, Next: Improved capitalize, Prev: Improved m4wrap, Up: Answers
6944 17.6 Solution for ‘cleardivert’
6945 ===============================
6947 The ‘cleardivert’ macro (*note Cleardivert::) cannot, as it stands, be
6948 called without arguments to clear all pending diversions. That is
6949 because using undivert with an empty string for an argument is different
6950 than using it with no arguments at all. Compare the earlier definition
6951 with one that takes the number of arguments into account:
6953 define(`cleardivert',
6954 `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
6964 define(`cleardivert',
6965 `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0',
6966 `undivert`'', `undivert($@)')divert(_num)popdef(`_num')')
6977 File: m4.info, Node: Improved capitalize, Next: Improved fatal_error, Prev: Improved cleardivert, Up: Answers
6979 17.7 Solution for ‘capitalize’
6980 ==============================
6982 The ‘capitalize’ macro (*note Patsubst::) as presented earlier does not
6983 allow clients to follow the quoting rule of thumb. Consider the three
6984 macros ‘active’, ‘Active’, and ‘ACTIVE’, and the difference between
6985 calling ‘capitalize’ with the expansion of a macro, expanding the result
6986 of a case change, and changing the case of a double-quoted string:
6989 include(`capitalize.m4')dnl
6990 define(`active', `act1, ive')dnl
6991 define(`Active', `Act2, Ive')dnl
6992 define(`ACTIVE', `ACT3, IVE')dnl
7003 downcase(``ACTIVE'')
7007 capitalize(`active')
7009 capitalize(``active'')
7010 ⇒_capitalize(`active')
7015 capitalize(`active')
7018 First, when ‘capitalize’ is called with more than one argument, it
7019 was throwing away later arguments, whereas ‘upcase’ and ‘downcase’ used
7020 ‘$*’ to collect them all. The fix is simple: use ‘$*’ consistently.
7022 Next, with single-quoting, ‘capitalize’ outputs a single character, a
7023 set of quotes, then the rest of the characters, making it impossible to
7024 invoke ‘Active’ after the fact, and allowing the alternate macro ‘A’ to
7025 interfere. Here, the solution is to use additional quoting in the
7026 helper macros, then pass the final over-quoted output string through
7027 ‘_arg1’ to remove the extra quoting and finally invoke the concatenated
7028 portions as a single string.
7030 Finally, when passed a double-quoted string, the nested macro
7031 ‘_capitalize’ is never invoked because it ended up nested inside quotes.
7032 This one is the toughest to fix. In short, we have no idea how many
7033 levels of quotes are in effect on the substring being altered by
7034 ‘patsubst’. If the replacement string cannot be expressed entirely in
7035 terms of literal text and backslash substitutions, then we need a
7036 mechanism to guarantee that the helper macros are invoked outside of
7037 quotes. In other words, this sounds like a job for ‘changequote’ (*note
7038 Changequote::). By changing the active quoting characters, we can
7039 guarantee that replacement text injected by ‘patsubst’ always occurs in
7040 the middle of a string that has exactly one level of over-quoting using
7041 alternate quotes; so the replacement text closes the quoted string,
7042 invokes the helper macros, then reopens the quoted string. In turn,
7043 that means the replacement text has unbalanced quotes, necessitating
7044 another round of ‘changequote’.
7046 In the fixed version below, (also shipped as
7047 ‘m4-1.4.19/examples/capitalize2.m4’), ‘capitalize’ uses the alternate
7048 quotes of ‘<<[’ and ‘]>>’ (the longer strings are chosen so as to be
7049 less likely to appear in the text being converted). The helpers
7050 ‘_to_alt’ and ‘_from_alt’ merely reduce the number of characters
7051 required to perform a ‘changequote’, since the definition changes twice.
7052 The outermost pair means that ‘patsubst’ and ‘_capitalize_alt’ are
7053 invoked with alternate quoting; the innermost pair is used so that the
7054 third argument to ‘patsubst’ can contain an unbalanced ‘]>>’/‘<<[’ pair.
7055 Note that ‘upcase’ and ‘downcase’ must be redefined as ‘_upcase_alt’ and
7056 ‘_downcase_alt’, since they contain nested quotes but are invoked with
7057 the alternate quoting scheme in effect.
7060 include(`capitalize2.m4')dnl
7061 define(`active', `act1, ive')dnl
7062 define(`Active', `Act2, Ive')dnl
7063 define(`ACTIVE', `ACT3, IVE')dnl
7064 define(`A', `OOPS')dnl
7065 capitalize(active; `active'; ``active''; ```actIVE''')
7066 ⇒Act1,Ive; Act2, Ive; Active; `Active'
7067 undivert(`capitalize2.m4')dnl
7072 ⇒# change case of text, improved version
7073 ⇒define(`upcase', `translit(`$*', `a-z', `A-Z')')
7074 ⇒define(`downcase', `translit(`$*', `A-Z', `a-z')')
7075 ⇒define(`_arg1', `$1')
7076 ⇒define(`_to_alt', `changequote(`<<[', `]>>')')
7077 ⇒define(`_from_alt', `changequote(<<[`]>>, <<[']>>)')
7078 ⇒define(`_upcase_alt', `translit(<<[$*]>>, <<[a-z]>>, <<[A-Z]>>)')
7079 ⇒define(`_downcase_alt', `translit(<<[$*]>>, <<[A-Z]>>, <<[a-z]>>)')
7080 ⇒define(`_capitalize_alt',
7081 ⇒ `regexp(<<[$1]>>, <<[^\(\w\)\(\w*\)]>>,
7082 ⇒ <<[_upcase_alt(<<[<<[\1]>>]>>)_downcase_alt(<<[<<[\2]>>]>>)]>>)')
7083 ⇒define(`capitalize',
7084 ⇒ `_arg1(_to_alt()patsubst(<<[<<[$*]>>]>>, <<[\w+]>>,
7085 ⇒ _from_alt()`]>>_$0_alt(<<[\&]>>)<<['_to_alt())_from_alt())')
7089 File: m4.info, Node: Improved fatal_error, Prev: Improved capitalize, Up: Answers
7091 17.8 Solution for ‘fatal_error’
7092 ===============================
7094 The ‘fatal_error’ macro (*note M4exit::) is not robust to versions of
7095 GNU M4 earlier than 1.4.8, where invoking ‘__file__’ (*note Location::)
7096 inside ‘m4wrap’ would result in an empty string, and ‘__line__’ resulted
7097 in ‘0’ even though all files start at line 1. Furthermore, versions
7098 earlier than 1.4.6 did not support the ‘__program__’ macro. If you want
7099 ‘fatal_error’ to work across the entire 1.4.x release series, a better
7100 implementation would be:
7102 define(`fatal_error',
7103 `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl
7104 `:ifelse(__line__, `0', `',
7105 `__file__:__line__:')` fatal error: $*
7108 m4wrap(`divnum(`demo of internal message')
7109 fatal_error(`inside wrapped text')')
7112 error→m4:stdin:6: Warning: excess arguments to builtin `divnum' ignored
7114 error→m4:stdin:6: fatal error: inside wrapped text
7117 File: m4.info, Node: Copying This Package, Next: Copying This Manual, Prev: Answers, Up: Top
7119 Appendix A How to make copies of the overall M4 package
7120 *******************************************************
7122 This appendix covers the license for copying the source code of the
7123 overall M4 package. This manual is under a different set of
7124 restrictions, covered later (*note Copying This Manual::).
7128 * GNU General Public License:: License for copying the M4 package
7131 File: m4.info, Node: GNU General Public License, Up: Copying This Package
7133 A.1 License for copying the M4 package
7134 ======================================
7136 Version 3, 29 June 2007
7138 Copyright © 2007 Free Software Foundation, Inc. <https://fsf.org/>
7140 Everyone is permitted to copy and distribute verbatim copies of this
7141 license document, but changing it is not allowed.
7146 The GNU General Public License is a free, copyleft license for software
7147 and other kinds of works.
7149 The licenses for most software and other practical works are designed
7150 to take away your freedom to share and change the works. By contrast,
7151 the GNU General Public License is intended to guarantee your freedom to
7152 share and change all versions of a program—to make sure it remains free
7153 software for all its users. We, the Free Software Foundation, use the
7154 GNU General Public License for most of our software; it applies also to
7155 any other work released this way by its authors. You can apply it to
7158 When we speak of free software, we are referring to freedom, not
7159 price. Our General Public Licenses are designed to make sure that you
7160 have the freedom to distribute copies of free software (and charge for
7161 them if you wish), that you receive source code or can get it if you
7162 want it, that you can change the software or use pieces of it in new
7163 free programs, and that you know you can do these things.
7165 To protect your rights, we need to prevent others from denying you
7166 these rights or asking you to surrender the rights. Therefore, you have
7167 certain responsibilities if you distribute copies of the software, or if
7168 you modify it: responsibilities to respect the freedom of others.
7170 For example, if you distribute copies of such a program, whether
7171 gratis or for a fee, you must pass on to the recipients the same
7172 freedoms that you received. You must make sure that they, too, receive
7173 or can get the source code. And you must show them these terms so they
7176 Developers that use the GNU GPL protect your rights with two steps:
7177 (1) assert copyright on the software, and (2) offer you this License
7178 giving you legal permission to copy, distribute and/or modify it.
7180 For the developers’ and authors’ protection, the GPL clearly explains
7181 that there is no warranty for this free software. For both users’ and
7182 authors’ sake, the GPL requires that modified versions be marked as
7183 changed, so that their problems will not be attributed erroneously to
7184 authors of previous versions.
7186 Some devices are designed to deny users access to install or run
7187 modified versions of the software inside them, although the manufacturer
7188 can do so. This is fundamentally incompatible with the aim of
7189 protecting users’ freedom to change the software. The systematic
7190 pattern of such abuse occurs in the area of products for individuals to
7191 use, which is precisely where it is most unacceptable. Therefore, we
7192 have designed this version of the GPL to prohibit the practice for those
7193 products. If such problems arise substantially in other domains, we
7194 stand ready to extend this provision to those domains in future versions
7195 of the GPL, as needed to protect the freedom of users.
7197 Finally, every program is threatened constantly by software patents.
7198 States should not allow patents to restrict development and use of
7199 software on general-purpose computers, but in those that do, we wish to
7200 avoid the special danger that patents applied to a free program could
7201 make it effectively proprietary. To prevent this, the GPL assures that
7202 patents cannot be used to render the program non-free.
7204 The precise terms and conditions for copying, distribution and
7205 modification follow.
7207 TERMS AND CONDITIONS
7208 ====================
7212 “This License” refers to version 3 of the GNU General Public
7215 “Copyright” also means copyright-like laws that apply to other
7216 kinds of works, such as semiconductor masks.
7218 “The Program” refers to any copyrightable work licensed under this
7219 License. Each licensee is addressed as “you”. “Licensees” and
7220 “recipients” may be individuals or organizations.
7222 To “modify” a work means to copy from or adapt all or part of the
7223 work in a fashion requiring copyright permission, other than the
7224 making of an exact copy. The resulting work is called a “modified
7225 version” of the earlier work or a work “based on” the earlier work.
7227 A “covered work” means either the unmodified Program or a work
7228 based on the Program.
7230 To “propagate” a work means to do anything with it that, without
7231 permission, would make you directly or secondarily liable for
7232 infringement under applicable copyright law, except executing it on
7233 a computer or modifying a private copy. Propagation includes
7234 copying, distribution (with or without modification), making
7235 available to the public, and in some countries other activities as
7238 To “convey” a work means any kind of propagation that enables other
7239 parties to make or receive copies. Mere interaction with a user
7240 through a computer network, with no transfer of a copy, is not
7243 An interactive user interface displays “Appropriate Legal Notices”
7244 to the extent that it includes a convenient and prominently visible
7245 feature that (1) displays an appropriate copyright notice, and (2)
7246 tells the user that there is no warranty for the work (except to
7247 the extent that warranties are provided), that licensees may convey
7248 the work under this License, and how to view a copy of this
7249 License. If the interface presents a list of user commands or
7250 options, such as a menu, a prominent item in the list meets this
7255 The “source code” for a work means the preferred form of the work
7256 for making modifications to it. “Object code” means any non-source
7259 A “Standard Interface” means an interface that either is an
7260 official standard defined by a recognized standards body, or, in
7261 the case of interfaces specified for a particular programming
7262 language, one that is widely used among developers working in that
7265 The “System Libraries” of an executable work include anything,
7266 other than the work as a whole, that (a) is included in the normal
7267 form of packaging a Major Component, but which is not part of that
7268 Major Component, and (b) serves only to enable use of the work with
7269 that Major Component, or to implement a Standard Interface for
7270 which an implementation is available to the public in source code
7271 form. A “Major Component”, in this context, means a major
7272 essential component (kernel, window system, and so on) of the
7273 specific operating system (if any) on which the executable work
7274 runs, or a compiler used to produce the work, or an object code
7275 interpreter used to run it.
7277 The “Corresponding Source” for a work in object code form means all
7278 the source code needed to generate, install, and (for an executable
7279 work) run the object code and to modify the work, including scripts
7280 to control those activities. However, it does not include the
7281 work’s System Libraries, or general-purpose tools or generally
7282 available free programs which are used unmodified in performing
7283 those activities but which are not part of the work. For example,
7284 Corresponding Source includes interface definition files associated
7285 with source files for the work, and the source code for shared
7286 libraries and dynamically linked subprograms that the work is
7287 specifically designed to require, such as by intimate data
7288 communication or control flow between those subprograms and other
7291 The Corresponding Source need not include anything that users can
7292 regenerate automatically from other parts of the Corresponding
7295 The Corresponding Source for a work in source code form is that
7298 2. Basic Permissions.
7300 All rights granted under this License are granted for the term of
7301 copyright on the Program, and are irrevocable provided the stated
7302 conditions are met. This License explicitly affirms your unlimited
7303 permission to run the unmodified Program. The output from running
7304 a covered work is covered by this License only if the output, given
7305 its content, constitutes a covered work. This License acknowledges
7306 your rights of fair use or other equivalent, as provided by
7309 You may make, run and propagate covered works that you do not
7310 convey, without conditions so long as your license otherwise
7311 remains in force. You may convey covered works to others for the
7312 sole purpose of having them make modifications exclusively for you,
7313 or provide you with facilities for running those works, provided
7314 that you comply with the terms of this License in conveying all
7315 material for which you do not control copyright. Those thus making
7316 or running the covered works for you must do so exclusively on your
7317 behalf, under your direction and control, on terms that prohibit
7318 them from making any copies of your copyrighted material outside
7319 their relationship with you.
7321 Conveying under any other circumstances is permitted solely under
7322 the conditions stated below. Sublicensing is not allowed; section
7323 10 makes it unnecessary.
7325 3. Protecting Users’ Legal Rights From Anti-Circumvention Law.
7327 No covered work shall be deemed part of an effective technological
7328 measure under any applicable law fulfilling obligations under
7329 article 11 of the WIPO copyright treaty adopted on 20 December
7330 1996, or similar laws prohibiting or restricting circumvention of
7333 When you convey a covered work, you waive any legal power to forbid
7334 circumvention of technological measures to the extent such
7335 circumvention is effected by exercising rights under this License
7336 with respect to the covered work, and you disclaim any intention to
7337 limit operation or modification of the work as a means of
7338 enforcing, against the work’s users, your or third parties’ legal
7339 rights to forbid circumvention of technological measures.
7341 4. Conveying Verbatim Copies.
7343 You may convey verbatim copies of the Program’s source code as you
7344 receive it, in any medium, provided that you conspicuously and
7345 appropriately publish on each copy an appropriate copyright notice;
7346 keep intact all notices stating that this License and any
7347 non-permissive terms added in accord with section 7 apply to the
7348 code; keep intact all notices of the absence of any warranty; and
7349 give all recipients a copy of this License along with the Program.
7351 You may charge any price or no price for each copy that you convey,
7352 and you may offer support or warranty protection for a fee.
7354 5. Conveying Modified Source Versions.
7356 You may convey a work based on the Program, or the modifications to
7357 produce it from the Program, in the form of source code under the
7358 terms of section 4, provided that you also meet all of these
7361 a. The work must carry prominent notices stating that you
7362 modified it, and giving a relevant date.
7364 b. The work must carry prominent notices stating that it is
7365 released under this License and any conditions added under
7366 section 7. This requirement modifies the requirement in
7367 section 4 to “keep intact all notices”.
7369 c. You must license the entire work, as a whole, under this
7370 License to anyone who comes into possession of a copy. This
7371 License will therefore apply, along with any applicable
7372 section 7 additional terms, to the whole of the work, and all
7373 its parts, regardless of how they are packaged. This License
7374 gives no permission to license the work in any other way, but
7375 it does not invalidate such permission if you have separately
7378 d. If the work has interactive user interfaces, each must display
7379 Appropriate Legal Notices; however, if the Program has
7380 interactive interfaces that do not display Appropriate Legal
7381 Notices, your work need not make them do so.
7383 A compilation of a covered work with other separate and independent
7384 works, which are not by their nature extensions of the covered
7385 work, and which are not combined with it such as to form a larger
7386 program, in or on a volume of a storage or distribution medium, is
7387 called an “aggregate” if the compilation and its resulting
7388 copyright are not used to limit the access or legal rights of the
7389 compilation’s users beyond what the individual works permit.
7390 Inclusion of a covered work in an aggregate does not cause this
7391 License to apply to the other parts of the aggregate.
7393 6. Conveying Non-Source Forms.
7395 You may convey a covered work in object code form under the terms
7396 of sections 4 and 5, provided that you also convey the
7397 machine-readable Corresponding Source under the terms of this
7398 License, in one of these ways:
7400 a. Convey the object code in, or embodied in, a physical product
7401 (including a physical distribution medium), accompanied by the
7402 Corresponding Source fixed on a durable physical medium
7403 customarily used for software interchange.
7405 b. Convey the object code in, or embodied in, a physical product
7406 (including a physical distribution medium), accompanied by a
7407 written offer, valid for at least three years and valid for as
7408 long as you offer spare parts or customer support for that
7409 product model, to give anyone who possesses the object code
7410 either (1) a copy of the Corresponding Source for all the
7411 software in the product that is covered by this License, on a
7412 durable physical medium customarily used for software
7413 interchange, for a price no more than your reasonable cost of
7414 physically performing this conveying of source, or (2) access
7415 to copy the Corresponding Source from a network server at no
7418 c. Convey individual copies of the object code with a copy of the
7419 written offer to provide the Corresponding Source. This
7420 alternative is allowed only occasionally and noncommercially,
7421 and only if you received the object code with such an offer,
7422 in accord with subsection 6b.
7424 d. Convey the object code by offering access from a designated
7425 place (gratis or for a charge), and offer equivalent access to
7426 the Corresponding Source in the same way through the same
7427 place at no further charge. You need not require recipients
7428 to copy the Corresponding Source along with the object code.
7429 If the place to copy the object code is a network server, the
7430 Corresponding Source may be on a different server (operated by
7431 you or a third party) that supports equivalent copying
7432 facilities, provided you maintain clear directions next to the
7433 object code saying where to find the Corresponding Source.
7434 Regardless of what server hosts the Corresponding Source, you
7435 remain obligated to ensure that it is available for as long as
7436 needed to satisfy these requirements.
7438 e. Convey the object code using peer-to-peer transmission,
7439 provided you inform other peers where the object code and
7440 Corresponding Source of the work are being offered to the
7441 general public at no charge under subsection 6d.
7443 A separable portion of the object code, whose source code is
7444 excluded from the Corresponding Source as a System Library, need
7445 not be included in conveying the object code work.
7447 A “User Product” is either (1) a “consumer product”, which means
7448 any tangible personal property which is normally used for personal,
7449 family, or household purposes, or (2) anything designed or sold for
7450 incorporation into a dwelling. In determining whether a product is
7451 a consumer product, doubtful cases shall be resolved in favor of
7452 coverage. For a particular product received by a particular user,
7453 “normally used” refers to a typical or common use of that class of
7454 product, regardless of the status of the particular user or of the
7455 way in which the particular user actually uses, or expects or is
7456 expected to use, the product. A product is a consumer product
7457 regardless of whether the product has substantial commercial,
7458 industrial or non-consumer uses, unless such uses represent the
7459 only significant mode of use of the product.
7461 “Installation Information” for a User Product means any methods,
7462 procedures, authorization keys, or other information required to
7463 install and execute modified versions of a covered work in that
7464 User Product from a modified version of its Corresponding Source.
7465 The information must suffice to ensure that the continued
7466 functioning of the modified object code is in no case prevented or
7467 interfered with solely because modification has been made.
7469 If you convey an object code work under this section in, or with,
7470 or specifically for use in, a User Product, and the conveying
7471 occurs as part of a transaction in which the right of possession
7472 and use of the User Product is transferred to the recipient in
7473 perpetuity or for a fixed term (regardless of how the transaction
7474 is characterized), the Corresponding Source conveyed under this
7475 section must be accompanied by the Installation Information. But
7476 this requirement does not apply if neither you nor any third party
7477 retains the ability to install modified object code on the User
7478 Product (for example, the work has been installed in ROM).
7480 The requirement to provide Installation Information does not
7481 include a requirement to continue to provide support service,
7482 warranty, or updates for a work that has been modified or installed
7483 by the recipient, or for the User Product in which it has been
7484 modified or installed. Access to a network may be denied when the
7485 modification itself materially and adversely affects the operation
7486 of the network or violates the rules and protocols for
7487 communication across the network.
7489 Corresponding Source conveyed, and Installation Information
7490 provided, in accord with this section must be in a format that is
7491 publicly documented (and with an implementation available to the
7492 public in source code form), and must require no special password
7493 or key for unpacking, reading or copying.
7495 7. Additional Terms.
7497 “Additional permissions” are terms that supplement the terms of
7498 this License by making exceptions from one or more of its
7499 conditions. Additional permissions that are applicable to the
7500 entire Program shall be treated as though they were included in
7501 this License, to the extent that they are valid under applicable
7502 law. If additional permissions apply only to part of the Program,
7503 that part may be used separately under those permissions, but the
7504 entire Program remains governed by this License without regard to
7505 the additional permissions.
7507 When you convey a copy of a covered work, you may at your option
7508 remove any additional permissions from that copy, or from any part
7509 of it. (Additional permissions may be written to require their own
7510 removal in certain cases when you modify the work.) You may place
7511 additional permissions on material, added by you to a covered work,
7512 for which you have or can give appropriate copyright permission.
7514 Notwithstanding any other provision of this License, for material
7515 you add to a covered work, you may (if authorized by the copyright
7516 holders of that material) supplement the terms of this License with
7519 a. Disclaiming warranty or limiting liability differently from
7520 the terms of sections 15 and 16 of this License; or
7522 b. Requiring preservation of specified reasonable legal notices
7523 or author attributions in that material or in the Appropriate
7524 Legal Notices displayed by works containing it; or
7526 c. Prohibiting misrepresentation of the origin of that material,
7527 or requiring that modified versions of such material be marked
7528 in reasonable ways as different from the original version; or
7530 d. Limiting the use for publicity purposes of names of licensors
7531 or authors of the material; or
7533 e. Declining to grant rights under trademark law for use of some
7534 trade names, trademarks, or service marks; or
7536 f. Requiring indemnification of licensors and authors of that
7537 material by anyone who conveys the material (or modified
7538 versions of it) with contractual assumptions of liability to
7539 the recipient, for any liability that these contractual
7540 assumptions directly impose on those licensors and authors.
7542 All other non-permissive additional terms are considered “further
7543 restrictions” within the meaning of section 10. If the Program as
7544 you received it, or any part of it, contains a notice stating that
7545 it is governed by this License along with a term that is a further
7546 restriction, you may remove that term. If a license document
7547 contains a further restriction but permits relicensing or conveying
7548 under this License, you may add to a covered work material governed
7549 by the terms of that license document, provided that the further
7550 restriction does not survive such relicensing or conveying.
7552 If you add terms to a covered work in accord with this section, you
7553 must place, in the relevant source files, a statement of the
7554 additional terms that apply to those files, or a notice indicating
7555 where to find the applicable terms.
7557 Additional terms, permissive or non-permissive, may be stated in
7558 the form of a separately written license, or stated as exceptions;
7559 the above requirements apply either way.
7563 You may not propagate or modify a covered work except as expressly
7564 provided under this License. Any attempt otherwise to propagate or
7565 modify it is void, and will automatically terminate your rights
7566 under this License (including any patent licenses granted under the
7567 third paragraph of section 11).
7569 However, if you cease all violation of this License, then your
7570 license from a particular copyright holder is reinstated (a)
7571 provisionally, unless and until the copyright holder explicitly and
7572 finally terminates your license, and (b) permanently, if the
7573 copyright holder fails to notify you of the violation by some
7574 reasonable means prior to 60 days after the cessation.
7576 Moreover, your license from a particular copyright holder is
7577 reinstated permanently if the copyright holder notifies you of the
7578 violation by some reasonable means, this is the first time you have
7579 received notice of violation of this License (for any work) from
7580 that copyright holder, and you cure the violation prior to 30 days
7581 after your receipt of the notice.
7583 Termination of your rights under this section does not terminate
7584 the licenses of parties who have received copies or rights from you
7585 under this License. If your rights have been terminated and not
7586 permanently reinstated, you do not qualify to receive new licenses
7587 for the same material under section 10.
7589 9. Acceptance Not Required for Having Copies.
7591 You are not required to accept this License in order to receive or
7592 run a copy of the Program. Ancillary propagation of a covered work
7593 occurring solely as a consequence of using peer-to-peer
7594 transmission to receive a copy likewise does not require
7595 acceptance. However, nothing other than this License grants you
7596 permission to propagate or modify any covered work. These actions
7597 infringe copyright if you do not accept this License. Therefore,
7598 by modifying or propagating a covered work, you indicate your
7599 acceptance of this License to do so.
7601 10. Automatic Licensing of Downstream Recipients.
7603 Each time you convey a covered work, the recipient automatically
7604 receives a license from the original licensors, to run, modify and
7605 propagate that work, subject to this License. You are not
7606 responsible for enforcing compliance by third parties with this
7609 An “entity transaction” is a transaction transferring control of an
7610 organization, or substantially all assets of one, or subdividing an
7611 organization, or merging organizations. If propagation of a
7612 covered work results from an entity transaction, each party to that
7613 transaction who receives a copy of the work also receives whatever
7614 licenses to the work the party’s predecessor in interest had or
7615 could give under the previous paragraph, plus a right to possession
7616 of the Corresponding Source of the work from the predecessor in
7617 interest, if the predecessor has it or can get it with reasonable
7620 You may not impose any further restrictions on the exercise of the
7621 rights granted or affirmed under this License. For example, you
7622 may not impose a license fee, royalty, or other charge for exercise
7623 of rights granted under this License, and you may not initiate
7624 litigation (including a cross-claim or counterclaim in a lawsuit)
7625 alleging that any patent claim is infringed by making, using,
7626 selling, offering for sale, or importing the Program or any portion
7631 A “contributor” is a copyright holder who authorizes use under this
7632 License of the Program or a work on which the Program is based.
7633 The work thus licensed is called the contributor’s “contributor
7636 A contributor’s “essential patent claims” are all patent claims
7637 owned or controlled by the contributor, whether already acquired or
7638 hereafter acquired, that would be infringed by some manner,
7639 permitted by this License, of making, using, or selling its
7640 contributor version, but do not include claims that would be
7641 infringed only as a consequence of further modification of the
7642 contributor version. For purposes of this definition, “control”
7643 includes the right to grant patent sublicenses in a manner
7644 consistent with the requirements of this License.
7646 Each contributor grants you a non-exclusive, worldwide,
7647 royalty-free patent license under the contributor’s essential
7648 patent claims, to make, use, sell, offer for sale, import and
7649 otherwise run, modify and propagate the contents of its contributor
7652 In the following three paragraphs, a “patent license” is any
7653 express agreement or commitment, however denominated, not to
7654 enforce a patent (such as an express permission to practice a
7655 patent or covenant not to sue for patent infringement). To “grant”
7656 such a patent license to a party means to make such an agreement or
7657 commitment not to enforce a patent against the party.
7659 If you convey a covered work, knowingly relying on a patent
7660 license, and the Corresponding Source of the work is not available
7661 for anyone to copy, free of charge and under the terms of this
7662 License, through a publicly available network server or other
7663 readily accessible means, then you must either (1) cause the
7664 Corresponding Source to be so available, or (2) arrange to deprive
7665 yourself of the benefit of the patent license for this particular
7666 work, or (3) arrange, in a manner consistent with the requirements
7667 of this License, to extend the patent license to downstream
7668 recipients. “Knowingly relying” means you have actual knowledge
7669 that, but for the patent license, your conveying the covered work
7670 in a country, or your recipient’s use of the covered work in a
7671 country, would infringe one or more identifiable patents in that
7672 country that you have reason to believe are valid.
7674 If, pursuant to or in connection with a single transaction or
7675 arrangement, you convey, or propagate by procuring conveyance of, a
7676 covered work, and grant a patent license to some of the parties
7677 receiving the covered work authorizing them to use, propagate,
7678 modify or convey a specific copy of the covered work, then the
7679 patent license you grant is automatically extended to all
7680 recipients of the covered work and works based on it.
7682 A patent license is “discriminatory” if it does not include within
7683 the scope of its coverage, prohibits the exercise of, or is
7684 conditioned on the non-exercise of one or more of the rights that
7685 are specifically granted under this License. You may not convey a
7686 covered work if you are a party to an arrangement with a third
7687 party that is in the business of distributing software, under which
7688 you make payment to the third party based on the extent of your
7689 activity of conveying the work, and under which the third party
7690 grants, to any of the parties who would receive the covered work
7691 from you, a discriminatory patent license (a) in connection with
7692 copies of the covered work conveyed by you (or copies made from
7693 those copies), or (b) primarily for and in connection with specific
7694 products or compilations that contain the covered work, unless you
7695 entered into that arrangement, or that patent license was granted,
7696 prior to 28 March 2007.
7698 Nothing in this License shall be construed as excluding or limiting
7699 any implied license or other defenses to infringement that may
7700 otherwise be available to you under applicable patent law.
7702 12. No Surrender of Others’ Freedom.
7704 If conditions are imposed on you (whether by court order, agreement
7705 or otherwise) that contradict the conditions of this License, they
7706 do not excuse you from the conditions of this License. If you
7707 cannot convey a covered work so as to satisfy simultaneously your
7708 obligations under this License and any other pertinent obligations,
7709 then as a consequence you may not convey it at all. For example,
7710 if you agree to terms that obligate you to collect a royalty for
7711 further conveying from those to whom you convey the Program, the
7712 only way you could satisfy both those terms and this License would
7713 be to refrain entirely from conveying the Program.
7715 13. Use with the GNU Affero General Public License.
7717 Notwithstanding any other provision of this License, you have
7718 permission to link or combine any covered work with a work licensed
7719 under version 3 of the GNU Affero General Public License into a
7720 single combined work, and to convey the resulting work. The terms
7721 of this License will continue to apply to the part which is the
7722 covered work, but the special requirements of the GNU Affero
7723 General Public License, section 13, concerning interaction through
7724 a network will apply to the combination as such.
7726 14. Revised Versions of this License.
7728 The Free Software Foundation may publish revised and/or new
7729 versions of the GNU General Public License from time to time. Such
7730 new versions will be similar in spirit to the present version, but
7731 may differ in detail to address new problems or concerns.
7733 Each version is given a distinguishing version number. If the
7734 Program specifies that a certain numbered version of the GNU
7735 General Public License “or any later version” applies to it, you
7736 have the option of following the terms and conditions either of
7737 that numbered version or of any later version published by the Free
7738 Software Foundation. If the Program does not specify a version
7739 number of the GNU General Public License, you may choose any
7740 version ever published by the Free Software Foundation.
7742 If the Program specifies that a proxy can decide which future
7743 versions of the GNU General Public License can be used, that
7744 proxy’s public statement of acceptance of a version permanently
7745 authorizes you to choose that version for the Program.
7747 Later license versions may give you additional or different
7748 permissions. However, no additional obligations are imposed on any
7749 author or copyright holder as a result of your choosing to follow a
7752 15. Disclaimer of Warranty.
7754 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
7755 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
7756 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS”
7757 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
7758 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
7759 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
7760 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
7761 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
7762 NECESSARY SERVICING, REPAIR OR CORRECTION.
7764 16. Limitation of Liability.
7766 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
7767 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
7768 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
7769 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
7770 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
7771 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
7772 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
7773 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
7774 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
7775 THE POSSIBILITY OF SUCH DAMAGES.
7777 17. Interpretation of Sections 15 and 16.
7779 If the disclaimer of warranty and limitation of liability provided
7780 above cannot be given local legal effect according to their terms,
7781 reviewing courts shall apply local law that most closely
7782 approximates an absolute waiver of all civil liability in
7783 connection with the Program, unless a warranty or assumption of
7784 liability accompanies a copy of the Program in return for a fee.
7786 END OF TERMS AND CONDITIONS
7787 ===========================
7789 How to Apply These Terms to Your New Programs
7790 =============================================
7792 If you develop a new program, and you want it to be of the greatest
7793 possible use to the public, the best way to achieve this is to make it
7794 free software which everyone can redistribute and change under these
7797 To do so, attach the following notices to the program. It is safest
7798 to attach them to the start of each source file to most effectively
7799 state the exclusion of warranty; and each file should have at least the
7800 “copyright” line and a pointer to where the full notice is found.
7802 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
7803 Copyright (C) YEAR NAME OF AUTHOR
7805 This program is free software: you can redistribute it and/or modify
7806 it under the terms of the GNU General Public License as published by
7807 the Free Software Foundation, either version 3 of the License, or (at
7808 your option) any later version.
7810 This program is distributed in the hope that it will be useful, but
7811 WITHOUT ANY WARRANTY; without even the implied warranty of
7812 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7813 General Public License for more details.
7815 You should have received a copy of the GNU General Public License
7816 along with this program. If not, see <https://www.gnu.org/licenses/>.
7818 Also add information on how to contact you by electronic and paper
7821 If the program does terminal interaction, make it output a short
7822 notice like this when it starts in an interactive mode:
7824 PROGRAM Copyright (C) YEAR NAME OF AUTHOR
7825 This program comes with ABSOLUTELY NO WARRANTY; for details type ‘show w’.
7826 This is free software, and you are welcome to redistribute it
7827 under certain conditions; type ‘show c’ for details.
7829 The hypothetical commands ‘show w’ and ‘show c’ should show the
7830 appropriate parts of the General Public License. Of course, your
7831 program’s commands might be different; for a GUI interface, you would
7834 You should also get your employer (if you work as a programmer) or
7835 school, if any, to sign a “copyright disclaimer” for the program, if
7836 necessary. For more information on this, and how to apply and follow
7837 the GNU GPL, see <https://www.gnu.org/licenses/>.
7839 The GNU General Public License does not permit incorporating your
7840 program into proprietary programs. If your program is a subroutine
7841 library, you may consider it more useful to permit linking proprietary
7842 applications with the library. If this is what you want to do, use the
7843 GNU Lesser General Public License instead of this License. But first,
7844 please read <https://www.gnu.org/licenses/why-not-lgpl.html>.