Imported Upstream version 1.4.18
[platform/upstream/m4.git] / doc / m4.info-1
1 This is m4.info, produced by makeinfo version 6.1 from m4.texi.
2
3 This manual (31 December 2016) is for GNU M4 (version 1.4.18), a package
4 containing an implementation of the m4 macro language.
5
6    Copyright (C) 1989-1994, 2004-2014, 2016 Free Software Foundation,
7 Inc.
8
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
16 START-INFO-DIR-ENTRY
17 * M4: (m4).                     A powerful macro processor.
18 END-INFO-DIR-ENTRY
19
20 \1f
21 File: m4.info,  Node: Top,  Next: Preliminaries,  Up: (dir)
22
23 GNU M4
24 ******
25
26 This manual (31 December 2016) is for GNU M4 (version 1.4.18), a package
27 containing an implementation of the m4 macro language.
28
29    Copyright (C) 1989-1994, 2004-2014, 2016 Free Software Foundation,
30 Inc.
31
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."
38
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.
45
46    GNU 'm4' was originally written by Rene' Seindal, with subsequent
47 changes by Franc,ois Pinard and other volunteers on the Internet.  All
48 names and email addresses can be found in the files 'm4-1.4.18/AUTHORS'
49 and 'm4-1.4.18/THANKS' from the GNU M4 distribution.
50
51    This is release 1.4.18.  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...
54
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_.
63
64 * Menu:
65
66 * Preliminaries::               Introduction and preliminaries
67 * Invoking m4::                 Invoking 'm4'
68 * Syntax::                      Lexical and syntactic conventions
69
70 * Macros::                      How to invoke macros
71 * Definitions::                 How to define new macros
72 * Conditionals::                Conditionals, loops, and recursion
73
74 * Debugging::                   How to debug macros and input
75
76 * Input Control::               Input control
77 * File Inclusion::              File inclusion
78 * Diversions::                  Diverting and undiverting output
79
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
85
86 * Compatibility::               Compatibility with other versions of 'm4'
87 * Answers::                     Correct version of some examples
88
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
92
93  -- The Detailed Node Listing --
94
95 Introduction and preliminaries
96
97 * Intro::                       Introduction to 'm4'
98 * History::                     Historical references
99 * Bugs::                        Problems and bugs
100 * Manual::                      Using this manual
101
102 Invoking 'm4'
103
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
110
111 Lexical and syntactic conventions
112
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
118
119 How to invoke macros
120
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
126
127 How to define new macros
128
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
135
136 * Indir::                       Indirect call of macros
137 * Builtin::                     Indirect call of builtins
138
139 Conditionals, loops, and recursion
140
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
148
149 How to debug macros and input
150
151 * Dumpdef::                     Displaying macro definitions
152 * Trace::                       Tracing macro calls
153 * Debug Levels::                Controlling debugging output
154 * Debug Output::                Saving debugging output
155
156 Input control
157
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
163
164 File inclusion
165
166 * Include::                     Including named files
167 * Search Path::                 Searching for include files
168
169 Diverting and undiverting output
170
171 * Divert::                      Diverting output
172 * Undivert::                    Undiverting output
173 * Divnum::                      Diversion numbers
174 * Cleardivert::                 Discarding diverted text
175
176 Macros for text handling
177
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)
185
186 Macros for doing arithmetic
187
188 * Incr::                        Decrement and increment operators
189 * Eval::                        Evaluating integer expressions
190
191 Macros for running shell commands
192
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
198
199 Miscellaneous builtin macros
200
201 * Errprint::                    Printing error messages
202 * Location::                    Printing current location
203 * M4exit::                      Exiting from 'm4'
204
205 Fast loading of frozen state
206
207 * Using frozen files::          Using frozen files
208 * Frozen file format::          Frozen file format
209
210 Compatibility with other versions of 'm4'
211
212 * Extensions::                  Extensions in GNU M4
213 * Incompatibilities::           Facilities in System V m4 not in GNU M4
214 * Other Incompatibilities::     Other incompatibilities
215
216 Correct version of some examples
217
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'
226
227 How to make copies of the overall M4 package
228
229 * GNU General Public License::  License for copying the M4 package
230
231 How to make copies of this manual
232
233 * GNU Free Documentation License::  License for copying this manual
234
235 Indices of concepts and macros
236
237 * Macro index::                 Index for all 'm4' macros
238 * Concept index::               Index for many concepts
239
240
241 \1f
242 File: m4.info,  Node: Preliminaries,  Next: Invoking m4,  Prev: Top,  Up: Top
243
244 1 Introduction and preliminaries
245 ********************************
246
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.
251
252    The following chapters then detail all the features of the 'm4'
253 language.
254
255 * Menu:
256
257 * Intro::                       Introduction to 'm4'
258 * History::                     Historical references
259 * Bugs::                        Problems and bugs
260 * Manual::                      Using this manual
261
262 \1f
263 File: m4.info,  Node: Intro,  Next: History,  Up: Preliminaries
264
265 1.1 Introduction to 'm4'
266 ========================
267
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.
275
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.
284
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.
292
293 \1f
294 File: m4.info,  Node: History,  Next: Bugs,  Prev: Intro,  Up: Preliminaries
295
296 1.2 Historical references
297 =========================
298
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 <http://dx.doi.org/10.1145/367177.367223>.
306
307    An important precursor of 'm4' was GPM; see C. Strachey, "A general
308 purpose macrogenerator", _Computer Journal_ 8, 3 (1965), 225-41,
309 <http://dx.doi.org/10.1093/comjnl/8.3.225>.  GPM is also succinctly
310 described in David Gries's book _Compiler Construction for Digital
311 Computers_, Wiley (1971).  Strachey was a brilliant programmer: GPM fit
312 into 250 machine instructions!
313
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'
323 line.
324
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.
329
330    Kernighan and Ritchie then joined forces to develop the original
331 'm4', described in "The M4 Macro Processor", Bell Laboratories (1977),
332 <http://wolfram.schneider.org/bsd/7thEdManVol2/m4/m4.pdf>.  It had only
333 21 builtin macros.
334
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.
339
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'.
344
345    Rene' 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.
349
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
353 newsgroup (1992).
354
355    Franc,ois Pinard took over maintenance of GNU 'm4' in 1992, until
356 1994 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.
360
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
367 as 1.4.18 in 2016.
368
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.
372
373 \1f
374 File: m4.info,  Node: Bugs,  Next: Manual,  Prev: History,  Up: Preliminaries
375
376 1.3 Problems and bugs
377 =====================
378
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
384 the documentation!
385
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.
391
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.
396
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.
400
401 \1f
402 File: m4.info,  Node: Manual,  Prev: Bugs,  Up: Preliminaries
403
404 1.4 Using this manual
405 =====================
406
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
411
412      This is an example of an example!
413
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:
419
420      $ command line to invoke m4
421      Example of input line
422      =>Output line from m4
423      error->and an error message
424
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:
433
434      $ cd m4-1.4.18
435
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
438 arguments, e.g.,
439
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
456      ignoring them.
457
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.
466
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'.
470
471 \1f
472 File: m4.info,  Node: Invoking m4,  Next: Syntax,  Prev: Preliminaries,  Up: Top
473
474 2 Invoking 'm4'
475 ***************
476
477 The format of the 'm4' command is:
478
479      m4 [OPTION...] [FILE...]
480
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.
489
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.
497
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').
505
506    'm4' understands the following options, grouped by functionality.
507
508 * Menu:
509
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
516
517 \1f
518 File: m4.info,  Node: Operation modes,  Next: Preprocessor features,  Up: Invoking m4
519
520 2.1 Command line options for operation modes
521 ============================================
522
523 Several options control the overall operation of 'm4':
524
525 '--help'
526      Print a help summary on standard output, then immediately exit 'm4'
527      without reading any input files or performing any other actions.
528
529 '--version'
530      Print the version number of the program on standard output, then
531      immediately exit 'm4' without reading any input files or performing
532      any other actions.
533
534 '-E'
535 '--fatal-warnings'
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.
544
545 '-i'
546 '--interactive'
547 '-e'
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.
553
554 '-P'
555 '--prefix-builtins'
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.
560
561 '-Q'
562 '--quiet'
563 '--silent'
564      Suppress warnings, such as missing or superfluous arguments in
565      macro calls, or treating the empty string as zero.
566
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.
580
581 '-W REGEXP'
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::).
586
587 \1f
588 File: m4.info,  Node: Preprocessor features,  Next: Limits control,  Prev: Operation modes,  Up: Invoking m4
589
590 2.2 Command line options for preprocessor features
591 ==================================================
592
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:
597
598 '-D NAME[=VALUE]'
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.
606
607 '-I DIRECTORY'
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.
612
613 '-s'
614 '--synclines'
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.
625
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.
631
632           define(`twoline', `1
633           2')
634           =>#line 2 "stdin"
635           =>
636           changecom(`/*', `*/')
637           =>
638           define(`comment', `/*1
639           2*/')
640           =>#line 5
641           =>
642           dnl no line
643           hello
644           =>#line 7
645           =>hello
646           twoline
647           =>1
648           =>#line 8
649           =>2
650           comment
651           =>/*1
652           =>2*/
653           one comment `two
654           three'
655           =>#line 10
656           =>one /*1
657           =>2*/ two
658           =>three
659           goodbye
660           =>#line 12
661           =>goodbye
662
663 '-U NAME'
664 '--undefine=NAME'
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
669      to file names.
670
671 \1f
672 File: m4.info,  Node: Limits control,  Next: Frozen state,  Prev: Preprocessor features,  Up: Invoking m4
673
674 2.3 Command line options for limits control
675 ===========================================
676
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'.
681
682 '-g'
683 '--gnu'
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.
697
698 '-G'
699 '--traditional'
700      Suppress all the extensions made in this implementation, compared
701      to the System V version.  *Note Compatibility::, for a list of
702      these.
703
704 '-H NUM'
705 '--hashsize=NUM'
706      Make the internal hash table for symbol lookup be NUM entries big.
707      For better performance, the number should be prime, but this is not
708      checked.  The default is 509 entries.  It should not be necessary
709      to increase this value, unless you define an excessive number of
710      macros.
711
712 '-L NUM'
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.
720
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.
726
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!
737
738 '-B NUM'
739 '-S NUM'
740 '-T NUM'
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.
744
745 '-N NUM'
746 '--diversions=NUM'
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.
752
753 \1f
754 File: m4.info,  Node: Frozen state,  Next: Debugging options,  Prev: Limits control,  Up: Invoking m4
755
756 2.4 Command line options for frozen state
757 =========================================
758
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.
762
763 '-F FILE'
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
767      end in '.m4f'.
768
769 '-R FILE'
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
774      read.
775
776 \1f
777 File: m4.info,  Node: Debugging options,  Next: Command line files,  Prev: Frozen state,  Up: Invoking m4
778
779 2.5 Command line options for debugging
780 ======================================
781
782 Finally, there are several options for aiding in debugging 'm4' scripts.
783
784 '-d[FLAGS]'
785 '--debug[=FLAGS]'
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'.
790
791 '--debugfile[=FILE]'
792 '-o FILE'
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.
806
807 '-l NUM'
808 '--arglength=NUM'
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.
812
813 '-t NAME'
814 '--trace=NAME'
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.
819
820 \1f
821 File: m4.info,  Node: Command line files,  Prev: Debugging options,  Up: Invoking m4
822
823 2.6 Specifying input files on the command line
824 ==============================================
825
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'.
830
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
836 string.
837
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:
842
843      $ cat foo
844      bar
845
846    The text 'bar' can then be redefined over multiple uses of 'foo':
847
848      $ m4 -Dbar=hello foo -Dbar=world foo
849      =>hello
850      =>world
851
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::).
856
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.
859
860 \1f
861 File: m4.info,  Node: Syntax,  Next: Macros,  Prev: Invoking m4,  Up: Top
862
863 3 Lexical and syntactic conventions
864 ***********************************
865
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'').
876
877 * Menu:
878
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
884
885 \1f
886 File: m4.info,  Node: Names,  Next: Quoted strings,  Up: Syntax
887
888 3.1 Macro names
889 ===============
890
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.
896
897    Examples of legal names are: 'foo', '_tmp', and 'name01'.
898
899 \1f
900 File: m4.info,  Node: Quoted strings,  Next: Comments,  Prev: Names,  Up: Syntax
901
902 3.2 Quoting input to 'm4'
903 =========================
904
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
909
910      `'
911      =>
912
913 is the empty string, and double-quoting turns into single-quoting.
914
915      ``quoted''
916      =>`quoted'
917
918    The quote characters can be changed at any time, using the builtin
919 macro 'changequote'.  *Note Changequote::, for more information.
920
921 \1f
922 File: m4.info,  Node: Comments,  Next: Other tokens,  Prev: Quoted strings,  Up: Syntax
923
924 3.3 Comments in 'm4' input
925 ==========================
926
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'.
931
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.
935
936      $ m4
937      `quoted text' # `commented text'
938      =>quoted text # `commented text'
939      `quoting inhibits' `#' `comments'
940      =>quoting inhibits # comments
941
942    The comment delimiters can be changed to any string at any time,
943 using the builtin macro 'changecom'.  *Note Changecom::, for more
944 information.
945
946 \1f
947 File: m4.info,  Node: Other tokens,  Next: Input processing,  Prev: Comments,  Up: Syntax
948
949 3.4 Other kinds of input tokens
950 ===============================
951
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.
958
959 \1f
960 File: m4.info,  Node: Input processing,  Prev: Other tokens,  Up: Syntax
961
962 3.5 How 'm4' copies input to output
963 ===================================
964
965 As 'm4' reads the input token by token, it will copy each token directly
966 to the output immediately.
967
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.
973
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.
978
979    For a running example, examine how 'm4' handles this input:
980
981      format(`Result is %d', eval(`2**15'))
982
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:
991
992      format(`Result is %d', 32768)
993
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
997
998      =>Result is 32768
999
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:
1006
1007      changequote([,])dnl
1008      define([gl_STRING_MODULE_INDICATOR],
1009        [
1010          dnl comment
1011          GNULIB_]translit([$1],[a-z],[A-Z])[=1
1012        ])dnl
1013        gl_STRING_MODULE_INDICATOR([strcase])
1014      =>  
1015      =>        GNULIB_strcase=1
1016      =>  
1017
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.
1029
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.
1040
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'.
1047
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.
1054
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.
1067
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.
1076
1077      changequote([,])dnl
1078      define([gl_STRING_MODULE_INDICATOR],
1079        [dnl comment
1080        GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl
1081      ])dnl
1082        gl_STRING_MODULE_INDICATOR([strcase])
1083      =>    GNULIB_STRCASE=1
1084
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.
1092
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.
1101
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.
1111
1112    The order in which 'm4' expands the macros can be further explored
1113 using the trace facilities of GNU 'm4' (*note Trace::).
1114
1115    ---------- Footnotes ----------
1116
1117    (1) Derived from a patch in
1118 <http://lists.gnu.org/archive/html/bug-gnulib/2007-01/msg00389.html>,
1119 and a followup patch in
1120 <http://lists.gnu.org/archive/html/bug-gnulib/2007-02/msg00000.html>
1121
1122 \1f
1123 File: m4.info,  Node: Macros,  Next: Definitions,  Prev: Syntax,  Up: Top
1124
1125 4 How to invoke macros
1126 **********************
1127
1128 This chapter covers macro invocation, macro arguments and how macro
1129 expansion is treated.
1130
1131 * Menu:
1132
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
1138
1139 \1f
1140 File: m4.info,  Node: Invocation,  Next: Inhibiting Invocation,  Up: Macros
1141
1142 4.1 Macro invocation
1143 ====================
1144
1145 Macro invocations has one of the forms
1146
1147      name
1148
1149 which is a macro invocation without any arguments, or
1150
1151      name(arg1, arg2, ..., argN)
1152
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.
1156
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
1159 arguments at all.
1160
1161    For a macro call to have no arguments, the parentheses _must_ be left
1162 out.  The macro call
1163
1164      name()
1165
1166 is a macro call with one argument, which is the empty string, not a call
1167 with no arguments.
1168
1169 \1f
1170 File: m4.info,  Node: Inhibiting Invocation,  Next: Macro Arguments,  Prev: Invocation,  Up: Macros
1171
1172 4.2 Preventing macro invocation
1173 ===============================
1174
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.
1181
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.
1193
1194      $ m4
1195      eval
1196      =>eval
1197      eval(`1')
1198      =>1
1199
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.
1206
1207      $ m4 -P
1208      eval
1209      =>eval
1210      eval(`1')
1211      =>eval(1)
1212      m4_eval
1213      =>m4_eval
1214      m4_eval(`1')
1215      =>1
1216
1217    Another alternative is to redefine problematic macros to a name less
1218 likely to cause conflicts, using *note Definitions::.
1219
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.
1224
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.
1229
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
1234 name.  For example:
1235
1236      `divert'
1237      =>divert
1238      `d'ivert
1239      =>divert
1240      di`ver't
1241      =>divert
1242      div`'ert
1243      =>divert
1244
1245 all yield the string 'divert'.  While in both:
1246
1247      `'divert
1248      =>
1249      divert`'
1250      =>
1251
1252 the 'divert' builtin macro will be called, which expands to the empty
1253 string.
1254
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:
1258
1259      define(`cde', `CDE')
1260      =>
1261      define(`x', `substr(ab')
1262      =>
1263      define(`y', `cde, `1', `3')')
1264      =>
1265      x`'y
1266      =>bCD
1267
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:
1271
1272      define(`macro', `m')
1273      =>
1274      macro(`m')macro
1275      =>mmacro
1276      macro(`m')`'macro
1277      =>mm
1278
1279    Quoting may prevent recognizing as a macro name the concatenation of
1280 a macro expansion with the surrounding characters.  In this example:
1281
1282      define(`macro', `di$1')
1283      =>
1284      macro(`v')`ert'
1285      =>divert
1286      macro(`v')ert
1287      =>
1288
1289 the input will produce the string 'divert'.  When the quotes were
1290 removed, the 'divert' builtin was called instead.
1291
1292 \1f
1293 File: m4.info,  Node: Macro Arguments,  Next: Quoting Arguments,  Prev: Inhibiting Invocation,  Up: Macros
1294
1295 4.3 Macro arguments
1296 ===================
1297
1298 When a name is seen, and it has a macro definition, it will be expanded
1299 as a macro.
1300
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.
1311
1312      define(`macro', `$1')
1313      =>
1314      macro( unquoted leading space lost)
1315      =>unquoted leading space lost
1316      macro(` quoted leading space kept')
1317      => quoted leading space kept
1318      macro(
1319       divert `unquoted space kept after expansion')
1320      => unquoted space kept after expansion
1321      macro(macro(`
1322      ')`whitespace from expansion kept')
1323      =>
1324      =>whitespace from expansion kept
1325      macro(`unquoted trailing whitespace kept'
1326      )
1327      =>unquoted trailing whitespace kept
1328      =>
1329
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.
1335
1336      $ m4
1337      index(`abc')
1338      error->m4:stdin:1: Warning: too few arguments to builtin `index'
1339      =>0
1340      index(`abc',)
1341      =>0
1342      index(`abc', `b', `ignored')
1343      error->m4:stdin:3: Warning: excess arguments to builtin `index' ignored
1344      =>1
1345
1346      $ m4 -Q
1347      index(`abc')
1348      =>0
1349      index(`abc',)
1350      =>0
1351      index(`abc', `b', `ignored')
1352      =>1
1353
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
1358
1359      bar(a foo, d)
1360
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.
1365
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.
1369
1370      define(`f', `1')
1371      =>
1372      f(define(`f', `2'))
1373      =>1
1374      f
1375      =>2
1376
1377    It is an error if the end of file occurs while collecting arguments.
1378
1379      hello world
1380      =>hello world
1381      define(
1382      ^D
1383      error->m4:stdin:2: ERROR: end of file in argument list
1384
1385 \1f
1386 File: m4.info,  Node: Quoting Arguments,  Next: Macro expansion,  Prev: Macro Arguments,  Up: Macros
1387
1388 4.4 On Quoting Arguments to macros
1389 ==================================
1390
1391 Each argument has unquoted leading whitespace removed.  Within each
1392 argument, all unquoted parentheses must match.  For example, if FOO is a
1393 macro,
1394
1395      foo(() (`(') `(')
1396
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.
1400
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:
1404
1405      foo(`() (() (')
1406
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::).
1417
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.
1425
1426      define(`active', `ACT, IVE')
1427      =>
1428      define(`show', `$1 $1')
1429      =>
1430      show(active)
1431      =>ACT ACT
1432      show(`active')
1433      =>ACT, IVE ACT, IVE
1434      show(``active'')
1435      =>active active
1436
1437 \1f
1438 File: m4.info,  Node: Macro expansion,  Prev: Quoting Arguments,  Up: Macros
1439
1440 4.5 Macro expansion
1441 ===================
1442
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.
1448
1449    Taking a very simple example, if FOO expands to 'bar', and BAR
1450 expands to 'Hello', the input
1451
1452      $ m4 -Dbar=Hello -Dfoo=bar
1453      foo
1454      =>Hello
1455
1456 will expand first to 'bar', and when this is reread and expanded, into
1457 'Hello'.
1458
1459 \1f
1460 File: m4.info,  Node: Definitions,  Next: Conditionals,  Prev: Macros,  Up: Top
1461
1462 5 How to define new macros
1463 **************************
1464
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.
1468
1469 * Menu:
1470
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
1477
1478 * Indir::                       Indirect call of macros
1479 * Builtin::                     Indirect call of builtins
1480
1481 \1f
1482 File: m4.info,  Node: Define,  Next: Arguments,  Up: Definitions
1483
1484 5.1 Defining a macro
1485 ====================
1486
1487 The normal way to define or redefine macros is to use the builtin
1488 'define':
1489
1490  -- Builtin: define (NAME, [EXPANSION])
1491      Defines NAME to expand to EXPANSION.  If EXPANSION is not given, it
1492      is taken to be empty.
1493
1494      The expansion of 'define' is void.  The macro 'define' is
1495      recognized only with parameters.
1496
1497    The following example defines the macro FOO to expand to the text
1498 'Hello World.'.
1499
1500      define(`foo', `Hello world.')
1501      =>
1502      foo
1503      =>Hello world.
1504
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::,
1508 for details.
1509
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
1513 redefine 'one':
1514
1515      define(foo, one)
1516      =>
1517      define(foo, two)
1518      =>
1519      one
1520      =>two
1521
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.
1526
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::).
1532
1533    Arrays and associative arrays can be simulated by using non-standard
1534 macro names.
1535
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.
1540
1541      define(`array', `defn(format(``array[%d]'', `$1'))')
1542      =>
1543      define(`array_set', `define(format(``array[%d]'', `$1'), `$2')')
1544      =>
1545      array_set(`4', `array element no. 4')
1546      =>
1547      array_set(`17', `array element no. 17')
1548      =>
1549      array(`4')
1550      =>array element no. 4
1551      array(eval(`10 + 7'))
1552      =>array element no. 17
1553
1554    Change the '%d' to '%s' and it is an associative array.
1555
1556 \1f
1557 File: m4.info,  Node: Arguments,  Next: Pseudo Arguments,  Prev: Define,  Up: Definitions
1558
1559 5.2 Arguments to macros
1560 =======================
1561
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.
1567
1568  -- Composite: exch (ARG1, ARG2)
1569      Expands to ARG2 followed by ARG1, effectively exchanging their
1570      order.
1571
1572      define(`exch', `$2, $1')
1573      =>
1574      exch(`arg1', `arg2')
1575      =>arg2, arg1
1576
1577    This can be used, for example, if you like the arguments to 'define'
1578 to be reversed.
1579
1580      define(`exch', `$2, $1')
1581      =>
1582      define(exch(``expansion text'', ``macro''))
1583      =>
1584      macro
1585      =>expansion text
1586
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.).
1590
1591    As a special case, the zeroth argument, '$0', is always the name of
1592 the macro being expanded.
1593
1594      define(`test', ``Macro name: $0'')
1595      =>
1596      test
1597      =>Macro name: test
1598
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
1601
1602      define(`foo', `This is macro `foo'.')
1603      =>
1604      foo
1605      =>This is macro foo.
1606
1607 The 'foo' in the expansion text is _not_ expanded, since it is a quoted
1608 string, and not a name.
1609
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::).
1617
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:
1626
1627      define(`foo', `single quoted $`'{1} output')
1628      =>
1629      define(`bar', ``double quoted $'`{2} output'')
1630      =>
1631      foo(`a', `b')
1632      =>single quoted ${1} output
1633      bar(`a', `b')
1634      =>double quoted ${2} output
1635
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.
1645
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}'
1650      =>
1651      foo(`bar')
1652      =>bar ${1} bar
1653
1654 \1f
1655 File: m4.info,  Node: Pseudo Arguments,  Next: Undefine,  Prev: Arguments,  Up: Definitions
1656
1657 5.3 Special arguments to macros
1658 ===============================
1659
1660 There is a special notation for the number of actual arguments supplied,
1661 and for all the actual arguments.
1662
1663    The number of actual arguments in a macro call is denoted by '$#' in
1664 the expansion text.
1665
1666  -- Composite: nargs (...)
1667      Expands to a count of the number of arguments supplied.
1668
1669      define(`nargs', `$#')
1670      =>
1671      nargs
1672      =>0
1673      nargs()
1674      =>1
1675      nargs(`arg1', `arg2', `arg3')
1676      =>3
1677      nargs(`commas can be quoted, like this')
1678      =>1
1679      nargs(arg1#inside comments, commas do not separate arguments
1680      still arg1)
1681      =>1
1682      nargs((unquoted parentheses, like this, group arguments))
1683      =>1
1684
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.
1688
1689      dnl Attempt to define a macro to just `$#'
1690      define(underquoted, $#)
1691      oops)
1692      =>
1693      underquoted
1694      =>0)
1695      =>oops
1696
1697    The notation '$*' can be used in the expansion text to denote all the
1698 actual arguments, unquoted, with commas in between.  For example
1699
1700      define(`echo', `$*')
1701      =>
1702      echo(arg1,    arg2, arg3 , arg4)
1703      =>arg1,arg2,arg3 ,arg4
1704
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:
1708
1709      define(`echo', `$@')
1710      =>
1711      echo(arg1,    arg2, arg3 , arg4)
1712      =>arg1,arg2,arg3 ,arg4
1713
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
1716
1717      define(`echo1', `$*')
1718      =>
1719      define(`echo2', `$@')
1720      =>
1721      define(`foo', `This is macro `foo'.')
1722      =>
1723      echo1(foo)
1724      =>This is macro This is macro foo..
1725      echo1(`foo')
1726      =>This is macro foo.
1727      echo2(foo)
1728      =>This is macro foo.
1729      echo2(`foo')
1730      =>foo
1731
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.
1735
1736      define(`echo1', `$*')
1737      =>
1738      define(`echo2', `$@')
1739      =>
1740      define(`foo', `bar')
1741      =>
1742      echo1(#foo'foo
1743      foo)
1744      =>#foo'foo
1745      =>bar
1746      echo2(#foo'foo
1747      foo)
1748      =>#foobar
1749      =>bar'
1750
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
1753 text is.
1754
1755      define(`foo', `$$$ hello $$$')
1756      =>
1757      foo
1758      =>$$$ hello $$$
1759
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
1764 an argument.
1765
1766      define(`foo', `no nested quote: $1')
1767      =>
1768      foo(`arg')
1769      =>no nested quote: arg
1770      define(`foo', `nested quote around $: `$'1')
1771      =>
1772      foo(`arg')
1773      =>nested quote around $: $1
1774      define(`foo', `nested empty quote after $: $`'1')
1775      =>
1776      foo(`arg')
1777      =>nested empty quote after $: $1
1778      define(`foo', `nested quote around next character: $`1'')
1779      =>
1780      foo(`arg')
1781      =>nested quote around next character: $1
1782      define(`foo', `nested quote around both: `$1'')
1783      =>
1784      foo(`arg')
1785      =>nested quote around both: arg
1786
1787 \1f
1788 File: m4.info,  Node: Undefine,  Next: Defn,  Prev: Pseudo Arguments,  Up: Definitions
1789
1790 5.4 Deleting a macro
1791 ====================
1792
1793 A macro definition can be removed with 'undefine':
1794
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.
1798
1799      The expansion of 'undefine' is void.  The macro 'undefine' is
1800      recognized only with parameters.
1801
1802      foo bar blah
1803      =>foo bar blah
1804      define(`foo', `some')define(`bar', `other')define(`blah', `text')
1805      =>
1806      foo bar blah
1807      =>some other text
1808      undefine(`foo')
1809      =>
1810      foo bar blah
1811      =>foo other text
1812      undefine(`bar', `blah')
1813      =>
1814      foo bar blah
1815      =>foo bar blah
1816
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 '('.
1819
1820      define(`f', ``$0':$1')
1821      =>
1822      f(f(f(undefine(`f')`hello world')))
1823      =>f:f:f:hello world
1824      f(`bye')
1825      =>f(bye)
1826
1827    It is not an error for NAME to have no macro definition.  In that
1828 case, 'undefine' does nothing.
1829
1830 \1f
1831 File: m4.info,  Node: Defn,  Next: Pushdef,  Prev: Undefine,  Up: Definitions
1832
1833 5.5 Renaming macros
1834 ===================
1835
1836 It is possible to rename an already defined macro.  To do this, you need
1837 the builtin 'defn':
1838
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.
1842
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.
1851
1852      The macro 'defn' is recognized only with parameters.
1853
1854    Its normal use is best understood through an example, which shows how
1855 to rename 'undefine' to 'zap':
1856
1857      define(`zap', defn(`undefine'))
1858      =>
1859      zap(`undefine')
1860      =>
1861      undefine(`zap')
1862      =>undefine(zap)
1863
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.
1867
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
1870 definition:
1871
1872      define(`foo', `This is `$0'')
1873      =>
1874      define(`bar', defn(`foo'))
1875      =>
1876      bar
1877      =>This is bar
1878
1879    Macros used as string variables should be referred through 'defn', to
1880 avoid unwanted expansion of the text:
1881
1882      define(`string', `The macro dnl is very useful
1883      ')
1884      =>
1885      string
1886      =>The macro 
1887      defn(`string')
1888      =>The macro dnl is very useful
1889      =>
1890
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.
1897
1898      define(`foo', a'a)
1899      =>
1900      define(`a', `A')
1901      =>
1902      define(`echo', `$@')
1903      =>
1904      foo
1905      =>A'A
1906      defn(`foo')
1907      =>aA'
1908      echo(foo)
1909      =>AA'
1910
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
1918 in nested quoting.
1919
1920      define(`l', `<[>')define(`r', `<]>')
1921      =>
1922      changequote(`[', `]')
1923      =>
1924      defn([l])defn([r])
1925      ])
1926      =><[>]defn([r])
1927      =>)
1928      defn([l], [r])
1929      =><[>][<]>
1930
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.
1934
1935      $ m4 -d
1936      defn(`defn')
1937      =>
1938      define(defn(`divnum'), `cannot redefine a builtin token')
1939      error->m4:stdin:2: Warning: define: invalid macro name ignored
1940      =>
1941      divnum
1942      =>0
1943      len(defn(`divnum'))
1944      =>0
1945
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
1948 restriction.
1949
1950      $ m4 -d
1951      define(`a', `A')define(`AA', `b')
1952      =>
1953      traceon(`defn', `define')
1954      =>
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''
1958      =>AA
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', `')
1964      =>
1965      traceoff(`defn', `define')
1966      =>
1967
1968 \1f
1969 File: m4.info,  Node: Pushdef,  Next: Indir,  Prev: Defn,  Up: Definitions
1970
1971 5.6 Temporarily redefining macros
1972 =================================
1973
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':
1977
1978  -- Builtin: pushdef (NAME, [EXPANSION])
1979  -- Builtin: popdef (NAME...)
1980      Analogous to 'define' and 'undefine'.
1981
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'.
1987
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
1991      'undefine'.
1992
1993      The expansion of both 'pushdef' and 'popdef' is void.  The macros
1994      'pushdef' and 'popdef' are recognized only with parameters.
1995
1996      define(`foo', `Expansion one.')
1997      =>
1998      foo
1999      =>Expansion one.
2000      pushdef(`foo', `Expansion two.')
2001      =>
2002      foo
2003      =>Expansion two.
2004      pushdef(`foo', `Expansion three.')
2005      =>
2006      pushdef(`foo', `Expansion four.')
2007      =>
2008      popdef(`foo')
2009      =>
2010      foo
2011      =>Expansion three.
2012      popdef(`foo', `foo')
2013      =>
2014      foo
2015      =>Expansion one.
2016      popdef(`foo')
2017      =>
2018      foo
2019      =>foo
2020
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'.
2029
2030      define(`foo', `Expansion one.')
2031      =>
2032      foo
2033      =>Expansion one.
2034      pushdef(`foo', `Expansion two.')
2035      =>
2036      foo
2037      =>Expansion two.
2038      define(`foo', `Second expansion two.')
2039      =>
2040      foo
2041      =>Second expansion two.
2042      undefine(`foo')
2043      =>
2044      foo
2045      =>foo
2046
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
2050 definition.
2051
2052    It is possible to temporarily redefine a builtin with 'pushdef' and
2053 'defn'.
2054
2055 \1f
2056 File: m4.info,  Node: Indir,  Next: Builtin,  Prev: Pushdef,  Up: Definitions
2057
2058 5.7 Indirect call of macros
2059 ===========================
2060
2061 Any macro can be called indirectly with 'indir':
2062
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.
2067
2068      The macro 'indir' is recognized only with parameters.
2069
2070    This can be used to call macros with computed or "invalid" names
2071 ('define' allows such names to be defined):
2072
2073      define(`$$internal$macro', `Internal macro (name `$0')')
2074      =>
2075      $$internal$macro
2076      =>$$internal$macro
2077      indir(`$$internal$macro')
2078      =>Internal macro (name $$internal$macro)
2079
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'.
2083
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.
2089
2090      $ m4 -d
2091      define(`f', `1')
2092      =>
2093      f(define(`f', `2'))
2094      =>1
2095      indir(`f', define(`f', `3'))
2096      =>3
2097      indir(`f', undefine(`f'))
2098      error->m4:stdin:4: undefined macro `f'
2099      =>
2100
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.
2104
2105      $ m4 -d
2106      indir(defn(`defn'), `divnum')
2107      error->m4:stdin:1: Warning: indir: invalid macro name ignored
2108      =>
2109      indir(`define', defn(`defn'), `divnum')
2110      error->m4:stdin:2: Warning: define: invalid macro name ignored
2111      =>
2112      indir(`define', `foo', defn(`divnum'))
2113      =>
2114      foo
2115      =>0
2116      indir(`divert', defn(`foo'))
2117      error->m4:stdin:5: empty string treated as 0 in builtin `divert'
2118      =>
2119
2120 \1f
2121 File: m4.info,  Node: Builtin,  Prev: Indir,  Up: Definitions
2122
2123 5.8 Indirect call of builtins
2124 =============================
2125
2126 Builtin macros can be called indirectly with 'builtin':
2127
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.
2132
2133      The macro 'builtin' is recognized only with parameters.
2134
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
2137 builtin.
2138
2139      pushdef(`define', `hidden')
2140      =>
2141      undefine(`undefine')
2142      =>
2143      define(`foo', `bar')
2144      =>hidden
2145      foo
2146      =>foo
2147      builtin(`define', `foo', defn(`divnum'))
2148      =>
2149      foo
2150      =>0
2151      builtin(`define', `foo', `BAR')
2152      =>
2153      foo
2154      =>BAR
2155      undefine(`foo')
2156      =>undefine(foo)
2157      foo
2158      =>BAR
2159      builtin(`undefine', `foo')
2160      =>
2161      foo
2162      =>foo
2163
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.
2168
2169      $ m4 -P
2170      m4_builtin(`divnum')
2171      =>0
2172      m4_builtin(`m4_divnum')
2173      error->m4:stdin:2: undefined builtin `m4_divnum'
2174      =>
2175      m4_indir(`divnum')
2176      error->m4:stdin:3: undefined macro `divnum'
2177      =>
2178      m4_indir(`m4_divnum')
2179      =>0
2180
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
2184 expansion.
2185
2186      builtin
2187      =>builtin
2188      builtin()
2189      error->m4:stdin:2: undefined builtin `'
2190      =>
2191      builtin(`builtin')
2192      error->m4:stdin:3: Warning: too few arguments to builtin `builtin'
2193      =>
2194      builtin(`builtin',)
2195      error->m4:stdin:4: undefined builtin `'
2196      =>
2197      builtin(`builtin', ``'
2198      ')
2199      error->m4:stdin:5: undefined builtin ``'
2200      error->'
2201      =>
2202      indir(`index')
2203      error->m4:stdin:7: Warning: too few arguments to builtin `index'
2204      =>
2205
2206 \1f
2207 File: m4.info,  Node: Conditionals,  Next: Debugging,  Prev: Definitions,  Up: Top
2208
2209 6 Conditionals, loops, and recursion
2210 ************************************
2211
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
2217 true.
2218
2219 * Menu:
2220
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
2228
2229 \1f
2230 File: m4.info,  Node: Ifdef,  Next: Ifelse,  Up: Conditionals
2231
2232 6.1 Testing if a macro is defined
2233 =================================
2234
2235 There are two different builtin conditionals in 'm4'.  The first is
2236 'ifdef':
2237
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).
2242
2243      The macro 'ifdef' is recognized only with parameters.
2244
2245      ifdef(`foo', ``foo' is defined', ``foo' is not defined')
2246      =>foo is not defined
2247      define(`foo', `')
2248      =>
2249      ifdef(`foo', ``foo' is defined', ``foo' is not defined')
2250      =>foo is defined
2251      ifdef(`no_such_macro', `yes', `no', `extra argument')
2252      error->m4:stdin:4: Warning: excess arguments to builtin `ifdef' ignored
2253      =>no
2254
2255 \1f
2256 File: m4.info,  Node: Ifelse,  Next: Shift,  Prev: Ifdef,  Up: Conditionals
2257
2258 6.2 If-else construct, or multibranch
2259 =====================================
2260
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:
2264
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
2270      produces no output.
2271
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.
2276
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.
2280
2281      The macro 'ifelse' is recognized only with parameters.
2282
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.
2287
2288      ifelse(`some comments')
2289      =>
2290      ifelse(`foo', `bar')
2291      error->m4:stdin:2: Warning: too few arguments to builtin `ifelse'
2292      =>
2293
2294    Using three or four arguments provides decision points.
2295
2296      ifelse(`foo', `bar', `true')
2297      =>
2298      ifelse(`foo', `foo', `true')
2299      =>true
2300      define(`foo', `bar')
2301      =>
2302      ifelse(foo, `bar', `true', `false')
2303      =>true
2304      ifelse(foo, `foo', `true', `false')
2305      =>false
2306
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.
2311
2312      define(`foo', `ifelse(`$#', `0', ``$0'', `arguments:$#')')
2313      =>
2314      foo
2315      =>foo
2316      foo()
2317      =>arguments:1
2318      foo(`a', `b', `c')
2319      =>arguments:3
2320
2321    For an example of a way to make defining blind macros easier, see
2322 *note Composition::.
2323
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
2329 example:
2330
2331      ifelse(`foo', `bar', `third', `gnu', `gnats')
2332      error->m4:stdin:1: Warning: excess arguments to builtin `ifelse' ignored
2333      =>gnu
2334      ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth')
2335      =>
2336      ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth', `seventh')
2337      =>seventh
2338      ifelse(`foo', `bar', `3', `gnu', `gnats', `6', `7', `8')
2339      error->m4:stdin:4: Warning: excess arguments to builtin `ifelse' ignored
2340      =>7
2341
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
2344 various kinds.
2345
2346 \1f
2347 File: m4.info,  Node: Shift,  Next: Forloop,  Prev: Ifelse,  Up: Conditionals
2348
2349 6.3 Recursion in 'm4'
2350 =====================
2351
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.
2355
2356    Loops can be programmed using recursion and the conditionals
2357 described previously.
2358
2359    There is a builtin macro, 'shift', which can, among other things, be
2360 used for iterating through the actual arguments to a macro:
2361
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.
2365
2366      The macro 'shift' is recognized only with parameters.
2367
2368      shift
2369      =>shift
2370      shift(`bar')
2371      =>
2372      shift(`foo', `bar', `baz')
2373      =>bar,baz
2374
2375    An example of the use of 'shift' is this macro:
2376
2377  -- Composite: reverse (...)
2378      Takes any number of arguments, and reverses their order.
2379
2380    It is implemented as:
2381
2382      define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
2383                                `reverse(shift($@)), `$1'')')
2384      =>
2385      reverse
2386      =>
2387      reverse(`foo')
2388      =>foo
2389      reverse(`foo', `bar', `gnats', `and gnus')
2390      =>and gnus, gnats, bar, foo
2391
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.
2396
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'.
2405
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'.
2410
2411      define(`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
2416      define(`example1',
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
2422      define(`example2',
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
2428      example1(`yes')
2429      =>one comparison: 3
2430      example1(`no')
2431      =>two comparisons: 3
2432      example1(`maybe')
2433      =>three comparisons: 3
2434      example1(`feeling rather indecisive today')
2435      =>default answer: 4
2436      example2(`yes')
2437      =>one comparison: 1
2438      example2(`no')
2439      =>two comparisons: 2
2440      example2(`maybe')
2441      =>three comparisons: 3
2442      example2(`feeling rather indecisive today')
2443      =>default answer: 4
2444
2445    Another common task that requires iteration is joining a list of
2446 arguments into a single string.
2447
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.
2453
2454    Here are some examples of its usage, based on the implementation
2455 'm4-1.4.18/examples/join.m4' distributed in this package:
2456
2457      $ m4 -I examples
2458      include(`join.m4')
2459      =>
2460      join,join(`-'),join(`-', `'),join(`-', `', `')
2461      =>,,,
2462      joinall,joinall(`-'),joinall(`-', `'),joinall(`-', `', `')
2463      =>,,,-
2464      join(`-', `1')
2465      =>1
2466      join(`-', `1', `2', `3')
2467      =>1-2-3
2468      join(`', `1', `2', `3')
2469      =>123
2470      join(`-', `', `1', `', `', `2', `')
2471      =>1-2
2472      joinall(`-', `', `1', `', `', `2', `')
2473      =>-1---2-
2474      join(`,', `1', `2', `3')
2475      =>1,2,3
2476      define(`nargs', `$#')dnl
2477      nargs(join(`,', `1', `2', `3'))
2478      =>1
2479
2480    Examining the implementation shows some interesting points about
2481 several m4 programming idioms.
2482
2483      $ m4 -I examples
2484      undivert(`join.m4')dnl
2485      =>divert(`-1')
2486      =># join(sep, args) - join each non-empty ARG into a single
2487      =># string, with each element separated by SEP
2488      =>define(`join',
2489      =>`ifelse(`$#', `2', ``$2'',
2490      =>  `ifelse(`$2', `', `', ``$2'_')$0(`$1', shift(shift($@)))')')
2491      =>define(`_join',
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($@))')
2497      =>define(`_joinall',
2498      =>`ifelse(`$#', `2', `', ``$1$3'$0(`$1', shift(shift($@)))')')
2499      =>divert`'dnl
2500
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.
2507
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
2514 '_joinall'.
2515
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($@)))'.
2520
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.
2526
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
2534 arguments.
2535
2536    Sometimes, a recursive algorithm requires adding quotes to each
2537 element, or treating multiple arguments as a single element:
2538
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.
2548
2549    An actual implementation of these three macros is distributed as
2550 'm4-1.4.18/examples/quote.m4' in this package.  First, let's examine
2551 their usage:
2552
2553      $ m4 -I examples
2554      include(`quote.m4')
2555      =>
2556      -quote-dquote-dquote_elt-
2557      =>----
2558      -quote()-dquote()-dquote_elt()-
2559      =>--`'-`'-
2560      -quote(`1')-dquote(`1')-dquote_elt(`1')-
2561      =>-1-`1'-`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'))-
2566      =>-1-1-2-
2567      dquote(dquote_elt(`1', `2'))
2568      =>``1'',``2''
2569      dquote_elt(dquote(`1', `2'))
2570      =>``1',`2''
2571
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.
2581
2582      $ m4 -I examples
2583      undivert(`quote.m4')dnl
2584      =>divert(`-1')
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($@))')')
2592      =>divert`'dnl
2593
2594    It is worth pointing out that 'quote(ARGS)' is more efficient than
2595 'joinall(`,', ARGS)' for producing the same output.
2596
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
2600 Arguments::).
2601
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',$@)'.
2605
2606    It is implemented as:
2607
2608      define(`argn', `ifelse(`$1', 1, ``$2'',
2609        `argn(decr(`$1'), shift(shift($@)))')')
2610      =>
2611      argn(`1', `a')
2612      =>a
2613      define(`foo', `argn(`11', $@)')
2614      =>
2615      foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l')
2616      =>k
2617
2618 \1f
2619 File: m4.info,  Node: Forloop,  Next: Foreach,  Prev: Shift,  Up: Conditionals
2620
2621 6.4 Iteration by counting
2622 =========================
2623
2624 Here is an example of a loop macro that implements a simple for loop.
2625
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.
2632
2633    It can, for example, be used for simple counting:
2634
2635      $ m4 -I examples
2636      include(`forloop.m4')
2637      =>
2638      forloop(`i', `1', `8', `i ')
2639      =>1 2 3 4 5 6 7 8 
2640
2641    For-loops can be nested, like:
2642
2643      $ m4 -I examples
2644      include(`forloop.m4')
2645      =>
2646      forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)')
2647      ')
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)
2652      =>
2653
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.
2658
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.
2663
2664    Here is an actual implementation of 'forloop', distributed as
2665 'm4-1.4.18/examples/forloop.m4' in this package:
2666
2667      $ m4 -I examples
2668      undivert(`forloop.m4')dnl
2669      =>divert(`-1')
2670      =># forloop(var, from, to, stmt) - simple version
2671      =>define(`forloop', `pushdef(`$1', `$2')_forloop($@)popdef(`$1')')
2672      =>define(`_forloop',
2673      =>       `$4`'ifelse($1, `$3', `', `define(`$1', incr($1))$0($@)')')
2674      =>divert`'dnl
2675
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.).
2683
2684 \1f
2685 File: m4.info,  Node: Foreach,  Next: Stacks,  Prev: Forloop,  Up: Conditionals
2686
2687 6.5 Iteration by list contents
2688 ==============================
2689
2690 Here is an example of a loop macro that implements list iteration.
2691
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.
2702
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.18/examples/foreach.m4', and 'foreachq' in
2706 'm4-1.4.18/examples/foreachq.m4'.
2707
2708      $ m4 -I examples
2709      include(`foreach.m4')
2710      =>
2711      foreach(`x', (foo, bar, foobar), `Word was: x
2712      ')dnl
2713      =>Word was: foo
2714      =>Word was: bar
2715      =>Word was: foobar
2716      include(`foreachq.m4')
2717      =>
2718      foreachq(`x', `foo, bar, foobar', `Word was: x
2719      ')dnl
2720      =>Word was: foo
2721      =>Word was: bar
2722      =>Word was: foobar
2723
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:
2727
2728      $ m4 -I examples
2729      include(`foreach.m4')
2730      =>
2731      define(`_case', `  $1)
2732          $2=" $1";;
2733      ')dnl
2734      define(`_cat', `$1$2')dnl
2735      case $`'1 in
2736      =>case $1 in
2737      foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')',
2738              `_cat(`_case', x)')dnl
2739      =>  a)
2740      =>    vara=" a";;
2741      =>  b)
2742      =>    varb=" b";;
2743      =>  c)
2744      =>    varc=" c";;
2745      esac
2746      =>esac
2747
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':
2753
2754      $ m4 -I examples
2755      undivert(`foreach.m4')dnl
2756      =>divert(`-1')
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')')')
2763      =>divert`'dnl
2764
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:
2776
2777      $ m4 -I examples
2778      define(`a', `1')define(`b', `2')define(`c', `3')
2779      =>
2780      include(`foreach.m4')
2781      =>
2782      include(`foreachq.m4')
2783      =>
2784      foreach(`x', `(``a'', ``(b'', ``c)'')', `x
2785      ')
2786      =>1
2787      =>(2)1
2788      =>
2789      =>, x
2790      =>)
2791      foreachq(`x', ```a'', ``(b'', ``c)''', `x
2792      ')dnl
2793      =>a
2794      =>(b
2795      =>c)
2796
2797    Obviously, 'foreachq' did a better job; here is its implementation:
2798
2799      $ m4 -I examples
2800      undivert(`foreachq.m4')dnl
2801      =>include(`quote.m4')dnl
2802      =>divert(`-1')
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')')')
2809      =>divert`'dnl
2810
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'.
2820
2821      $ m4 -I examples
2822      include(`foreach.m4')include(`foreachq.m4')
2823      =>
2824      foreach(`name', `(`a', `b')', ` defn(`name')')
2825      => a b
2826      foreachq(`name', ``a', `b'', ` defn(`name')')
2827      => _arg1(`a', `b') _arg1(shift(`a', `b'))
2828
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.).
2833
2834 \1f
2835 File: m4.info,  Node: Stacks,  Next: Composition,  Prev: Foreach,  Up: Conditionals
2836
2837 6.6 Working with definition stacks
2838 ==================================
2839
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
2843 stack.
2844
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
2853      parameter.
2854
2855    A sample implementation of these macros is distributed in the file
2856 'm4-1.4.18/examples/stack.m4'.
2857
2858      $ m4 -I examples
2859      include(`stack.m4')
2860      =>
2861      pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
2862      =>
2863      define(`show', ``$1'
2864      ')
2865      =>
2866      stack_foreach(`a', `show')dnl
2867      =>1
2868      =>2
2869      =>3
2870      stack_foreach_lifo(`a', `show')dnl
2871      =>3
2872      =>2
2873      =>1
2874
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
2888 the algorithm.
2889
2890      $ m4 -I examples
2891      undivert(`stack.m4')dnl
2892      =>divert(`-1')
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($@)')')
2907      =>divert`'dnl
2908
2909 \1f
2910 File: m4.info,  Node: Composition,  Prev: Stacks,  Up: Conditionals
2911
2912 6.7 Building macros with macros
2913 ===============================
2914
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
2917 of blind macros.
2918
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.
2924
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.
2935
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.
2944
2945    With that explanation, here's the definition, and some sample usage.
2946 Notice that 'define_blind' is itself a blind macro.
2947
2948      $ m4 -d
2949      define(`define_blind', `ifelse(`$#', `0', ``$0'',
2950      `_$0(`$1', `$2', `$'`#', `$'`0')')')
2951      =>
2952      define(`_define_blind', `define(`$1',
2953      `ifelse(`$3', `0', ``$4'', `$2')')')
2954      =>
2955      define_blind
2956      =>define_blind
2957      define_blind(`foo', `arguments were $*')
2958      =>
2959      foo
2960      =>foo
2961      foo(`bar')
2962      =>arguments were bar
2963      define(`blah', defn(`foo'))
2964      =>
2965      blah
2966      =>blah
2967      blah(`a', `b')
2968      =>arguments were a,b
2969      defn(`blah')
2970      =>ifelse(`$#', `0', ``$0'', `arguments were $*')
2971
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.
2975
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.
2980
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.18/examples/curry.m4' included in the distribution.
2987
2988      $ m4 -I examples
2989      include(`curry.m4')include(`stack.m4')
2990      =>
2991      define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
2992                                `reverse(shift($@)), `$1'')')
2993      =>
2994      pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3')
2995      =>
2996      stack_foreach(`a', `:curry(`reverse', `4')')
2997      =>:1, 4:2, 4:3, 4
2998      curry(`curry', `reverse', `1')(`2')(`3')
2999      =>3, 2, 1
3000
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'.
3009
3010      $ m4 -I examples
3011      undivert(`curry.m4')dnl
3012      =>divert(`-1')
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')')
3018      =>divert`'dnl
3019
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
3023 release of M4.
3024
3025    Putting the last few concepts together, it is possible to copy or
3026 rename an entire stack of macro definitions.
3027
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.
3034
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
3039 copy.).
3040
3041      $ m4 -I examples
3042      include(`curry.m4')include(`stack.m4')
3043      =>
3044      define(`rename', `copy($@)undefine(`$1')')dnl
3045      define(`copy', `ifdef(`$2', `errprint(`$2 already defined
3046      ')m4exit(`1')',
3047         `stack_foreach(`$1', `curry(`pushdef', `$2')')')')dnl
3048      pushdef(`a', `1')pushdef(`a', defn(`divnum'))pushdef(`a', `2')
3049      =>
3050      copy(`a', `b')
3051      =>
3052      rename(`b', `c')
3053      =>
3054      a b c
3055      =>2 b 2
3056      popdef(`a', `c')c a
3057      => 0
3058      popdef(`a', `c')a c
3059      =>1 1
3060
3061 \1f
3062 File: m4.info,  Node: Debugging,  Next: Input Control,  Prev: Conditionals,  Up: Top
3063
3064 7 How to debug macros and input
3065 *******************************
3066
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'.
3070
3071 * Menu:
3072
3073 * Dumpdef::                     Displaying macro definitions
3074 * Trace::                       Tracing macro calls
3075 * Debug Levels::                Controlling debugging output
3076 * Debug Output::                Saving debugging output
3077
3078 \1f
3079 File: m4.info,  Node: Dumpdef,  Next: Trace,  Up: Debugging
3080
3081 7.1 Displaying macro definitions
3082 ================================
3083
3084 If you want to see what a name expands into, you can use the builtin
3085 'dumpdef':
3086
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.
3093
3094      The expansion of 'dumpdef' is void.
3095
3096      $ m4 -d
3097      define(`foo', `Hello world.')
3098      =>
3099      dumpdef(`foo')
3100      error->foo: =>
3101      dumpdef(`define')
3102      error->define: =>
3103
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.
3108
3109      $ m4 -d
3110      pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
3111      =>
3112      f(popdef(`f')dumpdef(`f'))
3113      error->f: =>f2
3114      f(popdef(`f')dumpdef(`f'))
3115      error->m4:stdin:3: undefined macro `f'
3116      =>f1
3117
3118    *Note Debug Levels::, for information on controlling the details of
3119 the display.
3120
3121 \1f
3122 File: m4.info,  Node: Trace,  Next: Debug Levels,  Prev: Dumpdef,  Up: Debugging
3123
3124 7.2 Tracing macro calls
3125 =======================
3126
3127 It is possible to trace macro calls and expansions through the builtins
3128 'traceon' and 'traceoff':
3129
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
3134      macros.
3135
3136      When called with arguments, only the macros listed in NAMES are
3137      affected, whether or not they are currently defined.
3138
3139      The expansion of 'traceon' and 'traceoff' is void.
3140
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
3145 Debug Output::).
3146
3147      $ m4 -d
3148      define(`foo', `Hello World.')
3149      =>
3150      define(`echo', `$@')
3151      =>
3152      traceon(`foo', `echo')
3153      =>
3154      foo
3155      error->m4trace: -1- foo -> `Hello World.'
3156      =>Hello World.
3157      echo(`gnus', `and gnats')
3158      error->m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats''
3159      =>gnus,and gnats
3160
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.
3168
3169      $ m4 -L 3 -t ifelse
3170      ifelse(`one level')
3171      error->m4trace: -1- ifelse
3172      =>
3173      ifelse(ifelse(ifelse(`three levels')))
3174      error->m4trace: -3- ifelse
3175      error->m4trace: -2- ifelse
3176      error->m4trace: -1- ifelse
3177      =>
3178      ifelse(ifelse(ifelse(ifelse(`four levels'))))
3179      error->m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it
3180
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.
3184
3185      $ m4 -d
3186      traceoff(`foo')
3187      =>
3188      traceon(`foo')
3189      =>
3190      foo
3191      =>foo
3192      defn(`foo')
3193      =>
3194      define(`foo', `bar')
3195      =>
3196      foo
3197      error->m4trace: -1- foo -> `bar'
3198      =>bar
3199      undefine(`foo')
3200      =>
3201      ifdef(`foo', `yes', `no')
3202      =>no
3203      indir(`foo')
3204      error->m4:stdin:9: undefined macro `foo'
3205      =>
3206      define(`foo', `blah')
3207      =>
3208      foo
3209      error->m4trace: -1- foo -> `blah'
3210      =>blah
3211      traceoff
3212      =>
3213      foo
3214      =>blah
3215
3216    Tracing even works on builtins.  However, 'defn' (*note Defn::) does
3217 not transfer tracing status.
3218
3219      $ m4 -d
3220      traceon(`traceon')
3221      =>
3222      traceon(`traceoff')
3223      error->m4trace: -1- traceon(`traceoff')
3224      =>
3225      traceoff(`traceoff')
3226      error->m4trace: -1- traceoff(`traceoff')
3227      =>
3228      traceoff(`traceon')
3229      =>
3230      traceon(`eval', `m4_divnum')
3231      =>
3232      define(`m4_eval', defn(`eval'))
3233      =>
3234      define(`m4_divnum', defn(`divnum'))
3235      =>
3236      eval(divnum)
3237      error->m4trace: -1- eval(`0') -> `0'
3238      =>0
3239      m4_eval(m4_divnum)
3240      error->m4trace: -2- m4_divnum -> `0'
3241      =>0
3242
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'.
3246
3247 \1f
3248 File: m4.info,  Node: Debug Levels,  Next: Debug Output,  Prev: Trace,  Up: Debugging
3249
3250 7.3 Controlling debugging output
3251 ================================
3252
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
3260 lines.
3261
3262    The FLAGS following the option can be one or more of the following:
3263
3264 'a'
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').
3270
3271 'c'
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.
3276
3277 'e'
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').
3283
3284 'f'
3285      In debug and trace output, include the name of the current input
3286      file in the output line.
3287
3288 'i'
3289      In debug output, print a message each time the current input file
3290      is changed.
3291
3292 'l'
3293      In debug and trace output, include the current input line number in
3294      the output line.
3295
3296 'p'
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
3299      file name used.
3300
3301 'q'
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.
3305
3306 't'
3307      In trace output, trace all macro calls made in this invocation of
3308      'm4', regardless of the settings of 'traceon'.
3309
3310 'x'
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
3313      above.
3314
3315 'V'
3316      A shorthand for all of the above flags.
3317
3318    If no flags are specified with the '-d' option, the default is 'aeq'.
3319 The examples throughout this manual assume the default flags.
3320
3321    There is a builtin macro 'debugmode', which allows on-the-fly control
3322 of the debugging output format:
3323
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'.
3331
3332      The expansion of 'debugmode' is void.
3333
3334      $ m4
3335      define(`foo', `FOO')
3336      =>
3337      traceon(`foo')
3338      =>
3339      debugmode()
3340      =>
3341      foo
3342      error->m4trace: -1- foo -> `FOO'
3343      =>FOO
3344      debugmode
3345      =>
3346      foo
3347      error->m4trace: -1- foo
3348      =>FOO
3349      debugmode(`+l')
3350      =>
3351      foo
3352      error->m4trace:8: -1- foo
3353      =>FOO
3354
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.
3359
3360      $ m4 -d -l 6
3361      define(`echo', `$@')debugmode(`+t')
3362      =>
3363      echo(`1', `long string')
3364      error->m4trace: -1- echo(`1', `long s...') -> ``1',`l...'
3365      =>1,long string
3366      indir(`echo', defn(`changequote'))
3367      error->m4trace: -2- defn(`change...')
3368      error->m4trace: -1- indir(`echo', <changequote>) -> ``''
3369      =>
3370
3371    This example shows the effects of the debug flags that are not
3372 related to macro tracing.
3373
3374      $ m4 -dip -I examples
3375      error->m4debug: input read from stdin
3376      include(`foo')dnl
3377      error->m4debug: path search for `foo' found `examples/foo'
3378      error->m4debug: input read from examples/foo
3379      =>bar
3380      error->m4debug: input reverted to stdin, line 1
3381      ^D
3382      error->m4debug: input exhausted
3383
3384 \1f
3385 File: m4.info,  Node: Debug Output,  Prev: Debug Levels,  Up: Debugging
3386
3387 7.4 Saving debugging output
3388 ===========================
3389
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':
3393
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.
3402
3403      The expansion of 'debugfile' is void.
3404
3405      $ m4 -d
3406      traceon(`divnum')
3407      =>
3408      divnum(`extra')
3409      error->m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored
3410      error->m4trace: -1- divnum(`extra') -> `0'
3411      =>0
3412      debugfile()
3413      =>
3414      divnum(`extra')
3415      error->m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored
3416      =>0
3417      debugfile
3418      =>
3419      divnum
3420      error->m4trace: -1- divnum -> `0'
3421      =>0
3422
3423 \1f
3424 File: m4.info,  Node: Input Control,  Next: File Inclusion,  Prev: Debugging,  Up: Top
3425
3426 8 Input control
3427 ***************
3428
3429 This chapter describes various builtin macros for controlling the input
3430 to 'm4'.
3431
3432 * Menu:
3433
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
3439
3440 \1f
3441 File: m4.info,  Node: Dnl,  Next: Changequote,  Up: Input Control
3442
3443 8.1 Deleting whitespace in input
3444 ================================
3445
3446 The builtin 'dnl' stands for "Discard to Next Line":
3447
3448  -- Builtin: dnl
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.
3452
3453      The expansion of 'dnl' is void.
3454
3455    It is often used in connection with 'define', to remove the newline
3456 that follows the call to 'define'.  Thus
3457
3458      define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
3459      foo
3460      =>Macro foo.
3461
3462    The input up to and including the next newline is discarded, as
3463 opposed to the way comments are treated (*note Comments::).
3464
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.
3473
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?
3479
3480    If the end of file is encountered without a newline character, a
3481 warning is issued and dnl stops consuming input.
3482
3483      m4wrap(`m4wrap(`2 hi
3484      ')0 hi dnl 1 hi')
3485      =>
3486      define(`hi', `HI')
3487      =>
3488      ^D
3489      error->m4:stdin:1: Warning: end of file treated as newline
3490      =>0 HI 2 HI
3491
3492 \1f
3493 File: m4.info,  Node: Changequote,  Next: Changecom,  Prev: Dnl,  Up: Input Control
3494
3495 8.2 Changing the quote characters
3496 =================================
3497
3498 The default quote delimiters can be changed with the builtin
3499 'changequote':
3500
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
3507      any length.
3508
3509      The expansion of 'changequote' is void.
3510
3511      changequote(`[', `]')
3512      =>
3513      define([foo], [Macro [foo].])
3514      =>
3515      foo
3516      =>Macro foo.
3517
3518    The quotation strings can safely contain eight-bit characters.  If no
3519 single character is appropriate, START and END can be of any length.
3520 Other implementations cap the delimiter length to five characters, but
3521 GNU has no inherent limit.
3522
3523      changequote(`[[[', `]]]')
3524      =>
3525      define([[[foo]]], [[[Macro [[[[[foo]]]]].]]])
3526      =>
3527      foo
3528      =>Macro [[foo]].
3529
3530    Calling 'changequote' with START as the empty string will effectively
3531 disable the quoting mechanism, leaving no way to quote text.  However,
3532 using an empty string is not portable, as some other implementations of
3533 'm4' revert to the default quoting, while others preserve the prior
3534 non-empty delimiter.  If START is not empty, then an empty END will use
3535 the default end-quote delimiter of ''', as otherwise, it would be
3536 impossible to end a quoted string.  Again, this is not portable, as some
3537 other 'm4' implementations reuse START as the end-quote delimiter, while
3538 others preserve the previous non-empty value.  Omitting both arguments
3539 restores the default begin-quote and end-quote delimiters; fortunately
3540 this behavior is portable to all implementations of 'm4'.
3541
3542      define(`foo', `Macro `FOO'.')
3543      =>
3544      changequote(`', `')
3545      =>
3546      foo
3547      =>Macro `FOO'.
3548      `foo'
3549      =>`Macro `FOO'.'
3550      changequote(`,)
3551      =>
3552      foo
3553      =>Macro FOO.
3554
3555    There is no way in 'm4' to quote a string containing an unmatched
3556 begin-quote, except using 'changequote' to change the current quotes.
3557
3558    If the quotes should be changed from, say, '[' to '[[', temporary
3559 quote characters have to be defined.  To achieve this, two calls of
3560 'changequote' must be made, one for the temporary quotes and one for the
3561 new quotes.
3562
3563    Macros are recognized in preference to the begin-quote string, so if
3564 a prefix of START can be recognized as part of a potential macro name,
3565 the quoting mechanism is effectively disabled.  Unless you use
3566 'changeword' (*note Changeword::), this means that START should not
3567 begin with a letter, digit, or '_' (underscore).  However, even though
3568 quoted strings are not recognized, the quote characters can still be
3569 discerned in macro expansion and in trace output.
3570
3571      define(`echo', `$@')
3572      =>
3573      define(`hi', `HI')
3574      =>
3575      changequote(`q', `Q')
3576      =>
3577      q hi Q hi
3578      =>q HI Q HI
3579      echo(hi)
3580      =>qHIQ
3581      changequote
3582      =>
3583      changequote(`-', `EOF')
3584      =>
3585      - hi EOF hi
3586      => hi  HI
3587      changequote
3588      =>
3589      changequote(`1', `2')
3590      =>
3591      hi1hi2
3592      =>hi1hi2
3593      hi 1hi2
3594      =>HI hi
3595
3596    Quotes are recognized in preference to argument collection.  In
3597 particular, if START is a single '(', then argument collection is
3598 effectively disabled.  For portability with other implementations, it is
3599 a good idea to avoid '(', ',', and ')' as the first character in START.
3600
3601      define(`echo', `$#:$@:')
3602      =>
3603      define(`hi', `HI')
3604      =>
3605      changequote(`(',`)')
3606      =>
3607      echo(hi)
3608      =>0::hi
3609      changequote
3610      =>
3611      changequote(`((', `))')
3612      =>
3613      echo(hi)
3614      =>1:HI:
3615      echo((hi))
3616      =>0::hi
3617      changequote
3618      =>
3619      changequote(`,', `)')
3620      =>
3621      echo(hi,hi)bye)
3622      =>1:HIhibye:
3623
3624    However, if you are not worried about portability, using '(' and ')'
3625 as quoting characters has an interesting property--you can use it to
3626 compute a quoted string containing the expansion of any quoted text, as
3627 long as the expansion results in both balanced quotes and balanced
3628 parentheses.  The trick is realizing 'expand' uses '$1' unquoted, to
3629 trigger its expansion using the normal quoting characters, but uses
3630 extra parentheses to group unquoted commas that occur in the expansion
3631 without consuming whitespace following those commas.  Then '_expand'
3632 uses 'changequote' to convert the extra parentheses back into quoting
3633 characters.  Note that it takes two more 'changequote' invocations to
3634 restore the original quotes.  Contrast the behavior on whitespace when
3635 using '$*', via 'quote', to attempt the same task.
3636
3637      changequote(`[', `]')dnl
3638      define([a], [1, (b)])dnl
3639      define([b], [2])dnl
3640      define([quote], [[$*]])dnl
3641      define([expand], [_$0(($1))])dnl
3642      define([_expand],
3643        [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl
3644      expand([a, a, [a, a], [[a, a]]])
3645      =>1, (2), 1, (2), a, a, [a, a]
3646      quote(a, a, [a, a], [[a, a]])
3647      =>1,(2),1,(2),a, a,[a, a]
3648
3649    If END is a prefix of START, the end-quote will be recognized in
3650 preference to a nested begin-quote.  In particular, changing the quotes
3651 to have the same string for START and END disables nesting of quotes.
3652 When quote nesting is disabled, it is impossible to double-quote strings
3653 across macro expansions, so using the same string is not done very
3654 often.
3655
3656      define(`hi', `HI')
3657      =>
3658      changequote(`""', `"')
3659      =>
3660      ""hi"""hi"
3661      =>hihi
3662      ""hi" ""hi"
3663      =>hi hi
3664      ""hi"" "hi"
3665      =>hi" "HI"
3666      changequote
3667      =>
3668      `hi`hi'hi'
3669      =>hi`hi'hi
3670      changequote(`"', `"')
3671      =>
3672      "hi"hi"hi"
3673      =>hiHIhi
3674
3675    It is an error if the end of file occurs within a quoted string.
3676
3677      `hello world'
3678      =>hello world
3679      `dangling quote
3680      ^D
3681      error->m4:stdin:2: ERROR: end of file in string
3682
3683      ifelse(`dangling quote
3684      ^D
3685      error->m4:stdin:1: ERROR: end of file in string
3686
3687 \1f
3688 File: m4.info,  Node: Changecom,  Next: Changeword,  Prev: Changequote,  Up: Input Control
3689
3690 8.3 Changing the comment delimiters
3691 ===================================
3692
3693 The default comment delimiters can be changed with the builtin macro
3694 'changecom':
3695
3696  -- Builtin: changecom ([START], [END = '<NL>'])
3697      This sets START as the new begin-comment delimiter and END as the
3698      new end-comment delimiter.  If both arguments are missing, or START
3699      is void, then comments are disabled.  Otherwise, if END is missing
3700      or void, the default end-comment delimiter of newline is used.  The
3701      comment delimiters can be of any length.
3702
3703      The expansion of 'changecom' is void.
3704
3705      define(`comment', `COMMENT')
3706      =>
3707      # A normal comment
3708      =># A normal comment
3709      changecom(`/*', `*/')
3710      =>
3711      # Not a comment anymore
3712      =># Not a COMMENT anymore
3713      But: /* this is a comment now */ while this is not a comment
3714      =>But: /* this is a comment now */ while this is not a COMMENT
3715
3716    Note how comments are copied to the output, much as if they were
3717 quoted strings.  If you want the text inside a comment expanded, quote
3718 the begin-comment delimiter.
3719
3720    Calling 'changecom' without any arguments, or with START as the empty
3721 string, will effectively disable the commenting mechanism.  To restore
3722 the original comment start of '#', you must explicitly ask for it.  If
3723 START is not empty, then an empty END will use the default end-comment
3724 delimiter of newline, as otherwise, it would be impossible to end a
3725 comment.  However, this is not portable, as some other 'm4'
3726 implementations preserve the previous non-empty delimiters instead.
3727
3728      define(`comment', `COMMENT')
3729      =>
3730      changecom
3731      =>
3732      # Not a comment anymore
3733      =># Not a COMMENT anymore
3734      changecom(`#', `')
3735      =>
3736      # comment again
3737      =># comment again
3738
3739    The comment strings can safely contain eight-bit characters.  If no
3740 single character is appropriate, START and END can be of any length.
3741 Other implementations cap the delimiter length to five characters, but
3742 GNU has no inherent limit.
3743
3744    Comments are recognized in preference to macros.  However, this is
3745 not compatible with other implementations, where macros and even quoting
3746 takes precedence over comments, so it may change in a future release.
3747 For portability, this means that START should not begin with a letter,
3748 digit, or '_' (underscore), and that neither the start-quote nor the
3749 start-comment string should be a prefix of the other.
3750
3751      define(`hi', `HI')
3752      =>
3753      define(`hi1hi2', `hello')
3754      =>
3755      changecom(`q', `Q')
3756      =>
3757      q hi Q hi
3758      =>q hi Q HI
3759      changecom(`1', `2')
3760      =>
3761      hi1hi2
3762      =>hello
3763      hi 1hi2
3764      =>HI 1hi2
3765
3766    Comments are recognized in preference to argument collection.  In
3767 particular, if START is a single '(', then argument collection is
3768 effectively disabled.  For portability with other implementations, it is
3769 a good idea to avoid '(', ',', and ')' as the first character in START.
3770
3771      define(`echo', `$#:$*:$@:')
3772      =>
3773      define(`hi', `HI')
3774      =>
3775      changecom(`(',`)')
3776      =>
3777      echo(hi)
3778      =>0:::(hi)
3779      changecom
3780      =>
3781      changecom(`((', `))')
3782      =>
3783      echo(hi)
3784      =>1:HI:HI:
3785      echo((hi))
3786      =>0:::((hi))
3787      changecom(`,', `)')
3788      =>
3789      echo(hi,hi)bye)
3790      =>1:HI,hi)bye:HI,hi)bye:
3791      changecom
3792      =>
3793      echo(hi,`,`'hi',hi)
3794      =>3:HI,,HI,HI:HI,,`'hi,HI:
3795      echo(hi,`,`'hi',hi`'changecom(`,,', `hi'))
3796      =>3:HI,,`'hi,HI:HI,,`'hi,HI:
3797
3798    It is an error if the end of file occurs within a comment.
3799
3800      changecom(`/*', `*/')
3801      =>
3802      /*dangling comment
3803      ^D
3804      error->m4:stdin:2: ERROR: end of file in comment
3805
3806 \1f
3807 File: m4.info,  Node: Changeword,  Next: M4wrap,  Prev: Changecom,  Up: Input Control
3808
3809 8.4 Changing the lexical structure of words
3810 ===========================================
3811
3812      The macro 'changeword' and all associated functionality is
3813      experimental.  It is only available if the '--enable-changeword'
3814      option was given to 'configure', at GNU 'm4' installation time.
3815      The functionality will go away in the future, to be replaced by
3816      other new features that are more efficient at providing the same
3817      capabilities.  _Do not rely on it_.  Please direct your comments
3818      about it the same way you would do for bugs.
3819
3820    A file being processed by 'm4' is split into quoted strings, words
3821 (potential macro names) and simple tokens (any other single character).
3822 Initially a word is defined by the following regular expression:
3823
3824      [_a-zA-Z][_a-zA-Z0-9]*
3825
3826    Using 'changeword', you can change this regular expression:
3827
3828  -- Optional builtin: changeword (REGEX)
3829      Changes the regular expression for recognizing macro names to be
3830      REGEX.  If REGEX is empty, use '[_a-zA-Z][_a-zA-Z0-9]*'.  REGEX
3831      must obey the constraint that every prefix of the desired final
3832      pattern is also accepted by the regular expression.  If REGEX
3833      contains grouping parentheses, the macro invoked is the portion
3834      that matched the first group, rather than the entire matching
3835      string.
3836
3837      The expansion of 'changeword' is void.  The macro 'changeword' is
3838      recognized only with parameters.
3839
3840    Relaxing the lexical rules of 'm4' might be useful (for example) if
3841 you wanted to apply translations to a file of numbers:
3842
3843      ifdef(`changeword', `', `errprint(` skipping: no changeword support
3844      ')m4exit(`77')')dnl
3845      changeword(`[_a-zA-Z0-9]+')
3846      =>
3847      define(`1', `0')1
3848      =>0
3849
3850    Tightening the lexical rules is less useful, because it will
3851 generally make some of the builtins unavailable.  You could use it to
3852 prevent accidental call of builtins, for example:
3853
3854      ifdef(`changeword', `', `errprint(` skipping: no changeword support
3855      ')m4exit(`77')')dnl
3856      define(`_indir', defn(`indir'))
3857      =>
3858      changeword(`_[_a-zA-Z0-9]*')
3859      =>
3860      esyscmd(`foo')
3861      =>esyscmd(foo)
3862      _indir(`esyscmd', `echo hi')
3863      =>hi
3864      =>
3865
3866    Because 'm4' constructs its words a character at a time, there is a
3867 restriction on the regular expressions that may be passed to
3868 'changeword'.  This is that if your regular expression accepts 'foo', it
3869 must also accept 'f' and 'fo'.
3870
3871      ifdef(`changeword', `', `errprint(` skipping: no changeword support
3872      ')m4exit(`77')')dnl
3873      define(`foo
3874      ', `bar
3875      ')
3876      =>
3877      dnl This example wants to recognize changeword, dnl, and `foo\n'.
3878      dnl First, we check that our regexp will match.
3879      regexp(`changeword', `[cd][a-z]*\|foo[
3880      ]')
3881      =>0
3882      regexp(`foo
3883      ', `[cd][a-z]*\|foo[
3884      ]')
3885      =>0
3886      regexp(`f', `[cd][a-z]*\|foo[
3887      ]')
3888      =>-1
3889      foo
3890      =>foo
3891      changeword(`[cd][a-z]*\|foo[
3892      ]')
3893      =>
3894      dnl Even though `foo\n' matches, we forgot to allow `f'.
3895      foo
3896      =>foo
3897      changeword(`[cd][a-z]*\|fo*[
3898      ]?')
3899      =>
3900      dnl Now we can call `foo\n'.
3901      foo
3902      =>bar
3903
3904    'changeword' has another function.  If the regular expression
3905 supplied contains any grouped subexpressions, then text outside the
3906 first of these is discarded before symbol lookup.  So:
3907
3908      ifdef(`changeword', `', `errprint(` skipping: no changeword support
3909      ')m4exit(`77')')dnl
3910      ifdef(`__unix__', ,
3911            `errprint(` skipping: syscmd does not have unix semantics
3912      ')m4exit(`77')')dnl
3913      changecom(`/*', `*/')dnl
3914      define(`foo', `bar')dnl
3915      changeword(`#\([_a-zA-Z0-9]*\)')
3916      =>
3917      #esyscmd(`echo foo \#foo')
3918      =>foo bar
3919      =>
3920
3921    'm4' now requires a '#' mark at the beginning of every macro
3922 invocation, so one can use 'm4' to preprocess plain text without losing
3923 various words like 'divert'.
3924
3925    In 'm4', macro substitution is based on text, while in TeX, it is
3926 based on tokens.  'changeword' can throw this difference into relief.
3927 For example, here is the same idea represented in TeX and 'm4'.  First,
3928 the TeX version:
3929
3930      \def\a{\message{Hello}}
3931      \catcode`\@=0
3932      \catcode`\\=12
3933      @a
3934      @bye
3935      =>Hello
3936
3937 Then, the 'm4' version:
3938
3939      ifdef(`changeword', `', `errprint(` skipping: no changeword support
3940      ')m4exit(`77')')dnl
3941      define(`a', `errprint(`Hello')')dnl
3942      changeword(`@\([_a-zA-Z0-9]*\)')
3943      =>
3944      @a
3945      =>errprint(Hello)
3946
3947    In the TeX example, the first line defines a macro 'a' to print the
3948 message 'Hello'.  The second line defines <@> to be usable instead of
3949 <\> as an escape character.  The third line defines <\> to be a normal
3950 printing character, not an escape.  The fourth line invokes the macro
3951 'a'.  So, when TeX is run on this file, it displays the message 'Hello'.
3952
3953    When the 'm4' example is passed through 'm4', it outputs
3954 'errprint(Hello)'.  The reason for this is that TeX does lexical
3955 analysis of macro definition when the macro is _defined_.  'm4' just
3956 stores the text, postponing the lexical analysis until the macro is
3957 _used_.
3958
3959    You should note that using 'changeword' will slow 'm4' down by a
3960 factor of about seven, once it is changed to something other than the
3961 default regular expression.  You can invoke 'changeword' with the empty
3962 string to restore the default word definition, and regain the parsing
3963 speed.
3964
3965 \1f
3966 File: m4.info,  Node: M4wrap,  Prev: Changeword,  Up: Input Control
3967
3968 8.5 Saving text until end of input
3969 ==================================
3970
3971 It is possible to 'save' some text until the end of the normal input has
3972 been seen.  Text can be saved, to be read again by 'm4' when the normal
3973 input has been exhausted.  This feature is normally used to initiate
3974 cleanup actions before normal exit, e.g., deleting temporary files.
3975
3976    To save input text, use the builtin 'm4wrap':
3977
3978  -- Builtin: m4wrap (STRING, ...)
3979      Stores STRING in a safe place, to be reread when end of input is
3980      reached.  As a GNU extension, additional arguments are concatenated
3981      with a space to the STRING.
3982
3983      The expansion of 'm4wrap' is void.  The macro 'm4wrap' is
3984      recognized only with parameters.
3985
3986      define(`cleanup', `This is the `cleanup' action.
3987      ')
3988      =>
3989      m4wrap(`cleanup')
3990      =>
3991      This is the first and last normal input line.
3992      =>This is the first and last normal input line.
3993      ^D
3994      =>This is the cleanup action.
3995
3996    The saved input is only reread when the end of normal input is seen,
3997 and not if 'm4exit' is used to exit 'm4'.
3998
3999    It is safe to call 'm4wrap' from saved text, but then the order in
4000 which the saved text is reread is undefined.  If 'm4wrap' is not used
4001 recursively, the saved pieces of text are reread in the opposite order
4002 in which they were saved (LIFO--last in, first out).  However, this
4003 behavior is likely to change in a future release, to match POSIX, so you
4004 should not depend on this order.
4005
4006    It is possible to emulate POSIX behavior even with older versions of
4007 GNU M4 by including the file 'm4-1.4.18/examples/wrapfifo.m4' from the
4008 distribution:
4009
4010      $ m4 -I examples
4011      undivert(`wrapfifo.m4')dnl
4012      =>dnl Redefine m4wrap to have FIFO semantics.
4013      =>define(`_m4wrap_level', `0')dnl
4014      =>define(`m4wrap',
4015      =>`ifdef(`m4wrap'_m4wrap_level,
4016      =>       `define(`m4wrap'_m4wrap_level,
4017      =>               defn(`m4wrap'_m4wrap_level)`$1')',
4018      =>       `builtin(`m4wrap', `define(`_m4wrap_level',
4019      =>                                  incr(_m4wrap_level))dnl
4020      =>m4wrap'_m4wrap_level)dnl
4021      =>define(`m4wrap'_m4wrap_level, `$1')')')dnl
4022      include(`wrapfifo.m4')
4023      =>
4024      m4wrap(`a`'m4wrap(`c
4025      ', `d')')m4wrap(`b')
4026      =>
4027      ^D
4028      =>abc
4029
4030    It is likewise possible to emulate LIFO behavior without resorting to
4031 the GNU M4 extension of 'builtin', by including the file
4032 'm4-1.4.18/examples/wraplifo.m4' from the distribution.  (Unfortunately,
4033 both examples shown here share some subtle bugs.  See if you can find
4034 and correct them; or *note Answers: Improved m4wrap.).
4035
4036      $ m4 -I examples
4037      undivert(`wraplifo.m4')dnl
4038      =>dnl Redefine m4wrap to have LIFO semantics.
4039      =>define(`_m4wrap_level', `0')dnl
4040      =>define(`_m4wrap', defn(`m4wrap'))dnl
4041      =>define(`m4wrap',
4042      =>`ifdef(`m4wrap'_m4wrap_level,
4043      =>       `define(`m4wrap'_m4wrap_level,
4044      =>               `$1'defn(`m4wrap'_m4wrap_level))',
4045      =>       `_m4wrap(`define(`_m4wrap_level', incr(_m4wrap_level))dnl
4046      =>m4wrap'_m4wrap_level)dnl
4047      =>define(`m4wrap'_m4wrap_level, `$1')')')dnl
4048      include(`wraplifo.m4')
4049      =>
4050      m4wrap(`a`'m4wrap(`c
4051      ', `d')')m4wrap(`b')
4052      =>
4053      ^D
4054      =>bac
4055
4056    Here is an example of implementing a factorial function using
4057 'm4wrap':
4058
4059      define(`f', `ifelse(`$1', `0', `Answer: 0!=1
4060      ', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1')
4061      ', `m4wrap(`f(decr(`$1'), `$2$1*')')')')
4062      =>
4063      f(`10')
4064      =>
4065      ^D
4066      =>Answer: 10*9*8*7*6*5*4*3*2*1=3628800
4067
4068    Invocations of 'm4wrap' at the same recursion level are concatenated
4069 and rescanned as usual:
4070
4071      define(`aa', `AA
4072      ')
4073      =>
4074      m4wrap(`a')m4wrap(`a')
4075      =>
4076      ^D
4077      =>AA
4078
4079 however, the transition between recursion levels behaves like an end of
4080 file condition between two input files.
4081
4082      m4wrap(`m4wrap(`)')len(abc')
4083      =>
4084      ^D
4085      error->m4:stdin:1: ERROR: end of file in argument list
4086
4087 \1f
4088 File: m4.info,  Node: File Inclusion,  Next: Diversions,  Prev: Input Control,  Up: Top
4089
4090 9 File inclusion
4091 ****************
4092
4093 'm4' allows you to include named files at any point in the input.
4094
4095 * Menu:
4096
4097 * Include::                     Including named files
4098 * Search Path::                 Searching for include files
4099
4100 \1f
4101 File: m4.info,  Node: Include,  Next: Search Path,  Up: File Inclusion
4102
4103 9.1 Including named files
4104 =========================
4105
4106 There are two builtin macros in 'm4' for including files:
4107
4108  -- Builtin: include (FILE)
4109  -- Builtin: sinclude (FILE)
4110      Both macros cause the file named FILE to be read by 'm4'.  When the
4111      end of the file is reached, input is resumed from the previous
4112      input file.
4113
4114      The expansion of 'include' and 'sinclude' is therefore the contents
4115      of FILE.
4116
4117      If FILE does not exist, is a directory, or cannot otherwise be
4118      read, the expansion is void, and 'include' will fail with an error
4119      while 'sinclude' is silent.  The empty string counts as a file that
4120      does not exist.
4121
4122      The macros 'include' and 'sinclude' are recognized only with
4123      parameters.
4124
4125      include(`none')
4126      error->m4:stdin:1: cannot open `none': No such file or directory
4127      =>
4128      include()
4129      error->m4:stdin:2: cannot open `': No such file or directory
4130      =>
4131      sinclude(`none')
4132      =>
4133      sinclude()
4134      =>
4135
4136    The rest of this section assumes that 'm4' is invoked with the '-I'
4137 option (*note Invoking m4: Preprocessor features.) pointing to the
4138 'm4-1.4.18/examples' directory shipped as part of the GNU 'm4' package.
4139 The file 'm4-1.4.18/examples/incl.m4' in the distribution contains the
4140 lines:
4141
4142      $ cat examples/incl.m4
4143      =>Include file start
4144      =>foo
4145      =>Include file end
4146
4147    Normally file inclusion is used to insert the contents of a file into
4148 the input stream.  The contents of the file will be read by 'm4' and
4149 macro calls in the file will be expanded:
4150
4151      $ m4 -I examples
4152      define(`foo', `FOO')
4153      =>
4154      include(`incl.m4')
4155      =>Include file start
4156      =>FOO
4157      =>Include file end
4158      =>
4159
4160    The fact that 'include' and 'sinclude' expand to the contents of the
4161 file can be used to define macros that operate on entire files.  Here is
4162 an example, which defines 'bar' to expand to the contents of 'incl.m4':
4163
4164      $ m4 -I examples
4165      define(`bar', include(`incl.m4'))
4166      =>
4167      This is `bar':  >>bar<<
4168      =>This is bar:  >>Include file start
4169      =>foo
4170      =>Include file end
4171      =><<
4172
4173    This use of 'include' is not trivial, though, as files can contain
4174 quotes, commas, and parentheses, which can interfere with the way the
4175 'm4' parser works.  GNU 'm4' seamlessly concatenates the file contents
4176 with the next character, even if the included file ended in the middle
4177 of a comment, string, or macro call.  These conditions are only treated
4178 as end of file errors if specified as input files on the command line.
4179
4180    In GNU 'm4', an alternative method of reading files is using
4181 'undivert' (*note Undivert::) on a named file.
4182
4183 \1f
4184 File: m4.info,  Node: Search Path,  Prev: Include,  Up: File Inclusion
4185
4186 9.2 Searching for include files
4187 ===============================
4188
4189 GNU 'm4' allows included files to be found in other directories than the
4190 current working directory.
4191
4192    If the '--prepend-include' or '-B' command-line option was provided
4193 (*note Invoking m4: Preprocessor features.), those directories are
4194 searched first, in reverse order that those options were listed on the
4195 command line.  Then 'm4' looks in the current working directory.  Next
4196 comes the directories specified with the '--include' or '-I' option, in
4197 the order found on the command line.  Finally, if the 'M4PATH'
4198 environment variable is set, it is expected to contain a colon-separated
4199 list of directories, which will be searched in order.
4200
4201    If the automatic search for include-files causes trouble, the 'p'
4202 debug flag (*note Debug Levels::) can help isolate the problem.
4203
4204 \1f
4205 File: m4.info,  Node: Diversions,  Next: Text handling,  Prev: File Inclusion,  Up: Top
4206
4207 10 Diverting and undiverting output
4208 ***********************************
4209
4210 Diversions are a way of temporarily saving output.  The output of 'm4'
4211 can at any time be diverted to a temporary file, and be reinserted into
4212 the output stream, "undiverted", again at a later time.
4213
4214    Numbered diversions are counted from 0 upwards, diversion number 0
4215 being the normal output stream.  GNU 'm4' tries to keep diversions in
4216 memory.  However, there is a limit to the overall memory usable by all
4217 diversions taken together (512K, currently).  When this maximum is about
4218 to be exceeded, a temporary file is opened to receive the contents of
4219 the biggest diversion still in memory, freeing this memory for other
4220 diversions.  When creating the temporary file, 'm4' honors the value of
4221 the environment variable 'TMPDIR', and falls back to '/tmp'.  Thus, the
4222 amount of available disk space provides the only real limit on the
4223 number and aggregate size of diversions.
4224
4225    Diversions make it possible to generate output in a different order
4226 than the input was read.  It is possible to implement topological
4227 sorting dependencies.  For example, GNU Autoconf makes use of diversions
4228 under the hood to ensure that the expansion of a prerequisite macro
4229 appears in the output prior to the expansion of a dependent macro,
4230 regardless of which order the two macros were invoked in the user's
4231 input file.
4232
4233 * Menu:
4234
4235 * Divert::                      Diverting output
4236 * Undivert::                    Undiverting output
4237 * Divnum::                      Diversion numbers
4238 * Cleardivert::                 Discarding diverted text
4239
4240 \1f
4241 File: m4.info,  Node: Divert,  Next: Undivert,  Up: Diversions
4242
4243 10.1 Diverting output
4244 =====================
4245
4246 Output is diverted using 'divert':
4247
4248  -- Builtin: divert ([NUMBER = '0'])
4249      The current diversion is changed to NUMBER.  If NUMBER is left out
4250      or empty, it is assumed to be zero.  If NUMBER cannot be parsed,
4251      the diversion is unchanged.
4252
4253      The expansion of 'divert' is void.
4254
4255    When all the 'm4' input will have been processed, all existing
4256 diversions are automatically undiverted, in numerical order.
4257
4258      divert(`1')
4259      This text is diverted.
4260      divert
4261      =>
4262      This text is not diverted.
4263      =>This text is not diverted.
4264      ^D
4265      =>
4266      =>This text is diverted.
4267
4268    Several calls of 'divert' with the same argument do not overwrite the
4269 previous diverted text, but append to it.  Diversions are printed after
4270 any wrapped text is expanded.
4271
4272      define(`text', `TEXT')
4273      =>
4274      divert(`1')`diverted text.'
4275      divert
4276      =>
4277      m4wrap(`Wrapped text precedes ')
4278      =>
4279      ^D
4280      =>Wrapped TEXT precedes diverted text.
4281
4282    If output is diverted to a negative diversion, it is simply
4283 discarded.  This can be used to suppress unwanted output.  A common
4284 example of unwanted output is the trailing newlines after macro
4285 definitions.  Here is a common programming idiom in 'm4' for avoiding
4286 them.
4287
4288      divert(`-1')
4289      define(`foo', `Macro `foo'.')
4290      define(`bar', `Macro `bar'.')
4291      divert
4292      =>
4293
4294    Traditional implementations only supported ten diversions.  But as a
4295 GNU extension, diversion numbers can be as large as positive integers
4296 will allow, rather than treating a multi-digit diversion number as a
4297 request to discard text.
4298
4299      divert(eval(`1<<28'))world
4300      divert(`2')hello
4301      ^D
4302      =>hello
4303      =>world
4304
4305    Note that 'divert' is an English word, but also an active macro
4306 without arguments.  When processing plain text, the word might appear in
4307 normal text and be unintentionally swallowed as a macro invocation.  One
4308 way to avoid this is to use the '-P' option to rename all builtins
4309 (*note Invoking m4: Operation modes.).  Another is to write a wrapper
4310 that requires a parameter to be recognized.
4311
4312      We decided to divert the stream for irrigation.
4313      =>We decided to  the stream for irrigation.
4314      define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@)')')
4315      =>
4316      divert(`-1')
4317      Ignored text.
4318      divert(`0')
4319      =>
4320      We decided to divert the stream for irrigation.
4321      =>We decided to divert the stream for irrigation.
4322
4323 \1f
4324 File: m4.info,  Node: Undivert,  Next: Divnum,  Prev: Divert,  Up: Diversions
4325
4326 10.2 Undiverting output
4327 =======================
4328
4329 Diverted text can be undiverted explicitly using the builtin 'undivert':
4330
4331  -- Builtin: undivert ([DIVERSIONS...])
4332      Undiverts the numeric DIVERSIONS given by the arguments, in the
4333      order given.  If no arguments are supplied, all diversions are
4334      undiverted, in numerical order.
4335
4336      As a GNU extension, DIVERSIONS may contain non-numeric strings,
4337      which are treated as the names of files to copy into the output
4338      without expansion.  A warning is issued if a file could not be
4339      opened.
4340
4341      The expansion of 'undivert' is void.
4342
4343      divert(`1')
4344      This text is diverted.
4345      divert
4346      =>
4347      This text is not diverted.
4348      =>This text is not diverted.
4349      undivert(`1')
4350      =>
4351      =>This text is diverted.
4352      =>
4353
4354    Notice the last two blank lines.  One of them comes from the newline
4355 following 'undivert', the other from the newline that followed the
4356 'divert'!  A diversion often starts with a blank line like this.
4357
4358    When diverted text is undiverted, it is _not_ reread by 'm4', but
4359 rather copied directly to the current output, and it is therefore not an
4360 error to undivert into a diversion.  Undiverting the empty string is the
4361 same as specifying diversion 0; in either case nothing happens since the
4362 output has already been flushed.
4363
4364      divert(`1')diverted text
4365      divert
4366      =>
4367      undivert()
4368      =>
4369      undivert(`0')
4370      =>
4371      undivert
4372      =>diverted text
4373      =>
4374      divert(`1')more
4375      divert(`2')undivert(`1')diverted text`'divert
4376      =>
4377      undivert(`1')
4378      =>
4379      undivert(`2')
4380      =>more
4381      =>diverted text
4382
4383    When a diversion has been undiverted, the diverted text is discarded,
4384 and it is not possible to bring back diverted text more than once.
4385
4386      divert(`1')
4387      This text is diverted first.
4388      divert(`0')undivert(`1')dnl
4389      =>
4390      =>This text is diverted first.
4391      undivert(`1')
4392      =>
4393      divert(`1')
4394      This text is also diverted but not appended.
4395      divert(`0')undivert(`1')dnl
4396      =>
4397      =>This text is also diverted but not appended.
4398
4399    Attempts to undivert the current diversion are silently ignored.
4400 Thus, when the current diversion is not 0, the current diversion does
4401 not get rearranged among the other diversions.
4402
4403      divert(`1')one
4404      divert(`2')two
4405      divert(`3')three
4406      divert(`2')undivert`'dnl
4407      divert`'undivert`'dnl
4408      =>two
4409      =>one
4410      =>three
4411
4412    GNU 'm4' allows named files to be undiverted.  Given a non-numeric
4413 argument, the contents of the file named will be copied, uninterpreted,
4414 to the current output.  This complements the builtin 'include' (*note
4415 Include::).  To illustrate the difference, assume the file 'foo'
4416 contains:
4417
4418      $ cat foo
4419      bar
4420
4421 then
4422
4423      define(`bar', `BAR')
4424      =>
4425      undivert(`foo')
4426      =>bar
4427      =>
4428      include(`foo')
4429      =>BAR
4430      =>
4431
4432    If the file is not found (or cannot be read), an error message is
4433 issued, and the expansion is void.  It is possible to intermix files and
4434 diversion numbers.
4435
4436      divert(`1')diversion one
4437      divert(`2')undivert(`foo')dnl
4438      divert(`3')diversion three
4439      divert`'dnl
4440      undivert(`1', `2', `foo', `3')dnl
4441      =>diversion one
4442      =>bar
4443      =>bar
4444      =>diversion three
4445
4446 \1f
4447 File: m4.info,  Node: Divnum,  Next: Cleardivert,  Prev: Undivert,  Up: Diversions
4448
4449 10.3 Diversion numbers
4450 ======================
4451
4452 The current diversion is tracked by the builtin 'divnum':
4453
4454  -- Builtin: divnum
4455      Expands to the number of the current diversion.
4456
4457      Initial divnum
4458      =>Initial 0
4459      divert(`1')
4460      Diversion one: divnum
4461      divert(`2')
4462      Diversion two: divnum
4463      ^D
4464      =>
4465      =>Diversion one: 1
4466      =>
4467      =>Diversion two: 2
4468
4469 \1f
4470 File: m4.info,  Node: Cleardivert,  Prev: Divnum,  Up: Diversions
4471
4472 10.4 Discarding diverted text
4473 =============================
4474
4475 Often it is not known, when output is diverted, whether the diverted
4476 text is actually needed.  Since all non-empty diversion are brought back
4477 on the main output stream when the end of input is seen, a method of
4478 discarding a diversion is needed.  If all diversions should be
4479 discarded, the easiest is to end the input to 'm4' with 'divert(`-1')'
4480 followed by an explicit 'undivert':
4481
4482      divert(`1')
4483      Diversion one: divnum
4484      divert(`2')
4485      Diversion two: divnum
4486      divert(`-1')
4487      undivert
4488      ^D
4489
4490 No output is produced at all.
4491
4492    Clearing selected diversions can be done with the following macro:
4493
4494  -- Composite: cleardivert ([DIVERSIONS...])
4495      Discard the contents of each of the listed numeric DIVERSIONS.
4496
4497      define(`cleardivert',
4498      `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
4499      =>
4500
4501    It is called just like 'undivert', but the effect is to clear the
4502 diversions, given by the arguments.  (This macro has a nasty bug!  You
4503 should try to see if you can find it and correct it; or *note Answers:
4504 Improved cleardivert.).
4505
4506 \1f
4507 File: m4.info,  Node: Text handling,  Next: Arithmetic,  Prev: Diversions,  Up: Top
4508
4509 11 Macros for text handling
4510 ***************************
4511
4512 There are a number of builtins in 'm4' for manipulating text in various
4513 ways, extracting substrings, searching, substituting, and so on.
4514
4515 * Menu:
4516
4517 * Len::                         Calculating length of strings
4518 * Index macro::                 Searching for substrings
4519 * Regexp::                      Searching for regular expressions
4520 * Substr::                      Extracting substrings
4521 * Translit::                    Translating characters
4522 * Patsubst::                    Substituting text by regular expression
4523 * Format::                      Formatting strings (printf-like)
4524
4525 \1f
4526 File: m4.info,  Node: Len,  Next: Index macro,  Up: Text handling
4527
4528 11.1 Calculating length of strings
4529 ==================================
4530
4531 The length of a string can be calculated by 'len':
4532
4533  -- Builtin: len (STRING)
4534      Expands to the length of STRING, as a decimal number.
4535
4536      The macro 'len' is recognized only with parameters.
4537
4538      len()
4539      =>0
4540      len(`abcdef')
4541      =>6
4542
4543 \1f
4544 File: m4.info,  Node: Index macro,  Next: Regexp,  Prev: Len,  Up: Text handling
4545
4546 11.2 Searching for substrings
4547 =============================
4548
4549 Searching for substrings is done with 'index':
4550
4551  -- Builtin: index (STRING, SUBSTRING)
4552      Expands to the index of the first occurrence of SUBSTRING in
4553      STRING.  The first character in STRING has index 0.  If SUBSTRING
4554      does not occur in STRING, 'index' expands to '-1'.
4555
4556      The macro 'index' is recognized only with parameters.
4557
4558      index(`gnus, gnats, and armadillos', `nat')
4559      =>7
4560      index(`gnus, gnats, and armadillos', `dag')
4561      =>-1
4562
4563    Omitting SUBSTRING evokes a warning, but still produces output;
4564 contrast this with an empty SUBSTRING.
4565
4566      index(`abc')
4567      error->m4:stdin:1: Warning: too few arguments to builtin `index'
4568      =>0
4569      index(`abc', `')
4570      =>0
4571      index(`abc', `b')
4572      =>1
4573
4574 \1f
4575 File: m4.info,  Node: Regexp,  Next: Substr,  Prev: Index macro,  Up: Text handling
4576
4577 11.3 Searching for regular expressions
4578 ======================================
4579
4580 Searching for regular expressions is done with the builtin 'regexp':
4581
4582  -- Builtin: regexp (STRING, REGEXP, [REPLACEMENT])
4583      Searches for REGEXP in STRING.  The syntax for regular expressions
4584      is the same as in GNU Emacs, which is similar to BRE, Basic Regular
4585      Expressions in POSIX. *Note Syntax of Regular Expressions:
4586      (emacs)Regexps.  Support for ERE, Extended Regular Expressions is
4587      not available, but will be added in GNU M4 2.0.
4588
4589      If REPLACEMENT is omitted, 'regexp' expands to the index of the
4590      first match of REGEXP in STRING.  If REGEXP does not match anywhere
4591      in STRING, it expands to -1.
4592
4593      If REPLACEMENT is supplied, and there was a match, 'regexp' changes
4594      the expansion to this argument, with '\N' substituted by the text
4595      matched by the Nth parenthesized sub-expression of REGEXP, up to
4596      nine sub-expressions.  The escape '\&' is replaced by the text of
4597      the entire regular expression matched.  For all other characters,
4598      '\' treats the next character literally.  A warning is issued if
4599      there were fewer sub-expressions than the '\N' requested, or if
4600      there is a trailing '\'.  If there was no match, 'regexp' expands
4601      to the empty string.
4602
4603      The macro 'regexp' is recognized only with parameters.
4604
4605      regexp(`GNUs not Unix', `\<[a-z]\w+')
4606      =>5
4607      regexp(`GNUs not Unix', `\<Q\w*')
4608      =>-1
4609      regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
4610      =>*** Unix *** nix ***
4611      regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***')
4612      =>
4613
4614    Here are some more examples on the handling of backslash:
4615
4616      regexp(`abc', `\(b\)', `\\\10\a')
4617      =>\b0a
4618      regexp(`abc', `b', `\1\')
4619      error->m4:stdin:2: Warning: sub-expression 1 not present
4620      error->m4:stdin:2: Warning: trailing \ ignored in replacement
4621      =>
4622      regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6')
4623      error->m4:stdin:3: Warning: sub-expression 4 not present
4624      error->m4:stdin:3: Warning: sub-expression 5 not present
4625      error->m4:stdin:3: Warning: sub-expression 6 not present
4626      =>c
4627
4628    Omitting REGEXP evokes a warning, but still produces output; contrast
4629 this with an empty REGEXP argument.
4630
4631      regexp(`abc')
4632      error->m4:stdin:1: Warning: too few arguments to builtin `regexp'
4633      =>0
4634      regexp(`abc', `')
4635      =>0
4636      regexp(`abc', `', `\\def')
4637      =>\def
4638
4639 \1f
4640 File: m4.info,  Node: Substr,  Next: Translit,  Prev: Regexp,  Up: Text handling
4641
4642 11.4 Extracting substrings
4643 ==========================
4644
4645 Substrings are extracted with 'substr':
4646
4647  -- Builtin: substr (STRING, FROM, [LENGTH])
4648      Expands to the substring of STRING, which starts at index FROM, and
4649      extends for LENGTH characters, or to the end of STRING, if LENGTH
4650      is omitted.  The starting index of a string is always 0.  The
4651      expansion is empty if there is an error parsing FROM or LENGTH, if
4652      FROM is beyond the end of STRING, or if LENGTH is negative.
4653
4654      The macro 'substr' is recognized only with parameters.
4655
4656      substr(`gnus, gnats, and armadillos', `6')
4657      =>gnats, and armadillos
4658      substr(`gnus, gnats, and armadillos', `6', `5')
4659      =>gnats
4660
4661    Omitting FROM evokes a warning, but still produces output.
4662
4663      substr(`abc')
4664      error->m4:stdin:1: Warning: too few arguments to builtin `substr'
4665      =>abc
4666      substr(`abc',)
4667      error->m4:stdin:2: empty string treated as 0 in builtin `substr'
4668      =>abc
4669
4670 \1f
4671 File: m4.info,  Node: Translit,  Next: Patsubst,  Prev: Substr,  Up: Text handling
4672
4673 11.5 Translating characters
4674 ===========================
4675
4676 Character translation is done with 'translit':
4677
4678  -- Builtin: translit (STRING, CHARS, [REPLACEMENT])
4679      Expands to STRING, with each character that occurs in CHARS
4680      translated into the character from REPLACEMENT with the same index.
4681
4682      If REPLACEMENT is shorter than CHARS, the excess characters of
4683      CHARS are deleted from the expansion; if CHARS is shorter, the
4684      excess characters in REPLACEMENT are silently ignored.  If
4685      REPLACEMENT is omitted, all characters in STRING that are present
4686      in CHARS are deleted from the expansion.  If a character appears
4687      more than once in CHARS, only the first instance is used in making
4688      the translation.  Only a single translation pass is made, even if
4689      characters in REPLACEMENT also appear in CHARS.
4690
4691      As a GNU extension, both CHARS and REPLACEMENT can contain
4692      character-ranges, e.g., 'a-z' (meaning all lowercase letters) or
4693      '0-9' (meaning all digits).  To include a dash '-' in CHARS or
4694      REPLACEMENT, place it first or last in the entire string, or as the
4695      last character of a range.  Back-to-back ranges can share a common
4696      endpoint.  It is not an error for the last character in the range
4697      to be 'larger' than the first.  In that case, the range runs
4698      backwards, i.e., '9-0' means the string '9876543210'.  The
4699      expansion of a range is dependent on the underlying encoding of
4700      characters, so using ranges is not always portable between
4701      machines.
4702
4703      The macro 'translit' is recognized only with parameters.
4704
4705      translit(`GNUs not Unix', `A-Z')
4706      =>s not nix
4707      translit(`GNUs not Unix', `a-z', `A-Z')
4708      =>GNUS NOT UNIX
4709      translit(`GNUs not Unix', `A-Z', `z-a')
4710      =>tmfs not fnix
4711      translit(`+,-12345', `+--1-5', `<;>a-c-a')
4712      =><;>abcba
4713      translit(`abcdef', `aabdef', `bcged')
4714      =>bgced
4715
4716    In the ASCII encoding, the first example deletes all uppercase
4717 letters, the second converts lowercase to uppercase, and the third
4718 'mirrors' all uppercase letters, while converting them to lowercase.
4719 The two first cases are by far the most common, even though they are not
4720 portable to EBCDIC or other encodings.  The fourth example shows a range
4721 ending in '-', as well as back-to-back ranges.  The final example shows
4722 that 'a' is mapped to 'b', not 'c'; the resulting 'b' is not further
4723 remapped to 'g'; the 'd' and 'e' are swapped, and the 'f' is discarded.
4724
4725    Omitting CHARS evokes a warning, but still produces output.
4726
4727      translit(`abc')
4728      error->m4:stdin:1: Warning: too few arguments to builtin `translit'
4729      =>abc
4730
4731 \1f
4732 File: m4.info,  Node: Patsubst,  Next: Format,  Prev: Translit,  Up: Text handling
4733
4734 11.6 Substituting text by regular expression
4735 ============================================
4736
4737 Global substitution in a string is done by 'patsubst':
4738
4739  -- Builtin: patsubst (STRING, REGEXP, [REPLACEMENT])
4740      Searches STRING for matches of REGEXP, and substitutes REPLACEMENT
4741      for each match.  The syntax for regular expressions is the same as
4742      in GNU Emacs (*note Regexp::).
4743
4744      The parts of STRING that are not covered by any match of REGEXP are
4745      copied to the expansion.  Whenever a match is found, the search
4746      proceeds from the end of the match, so a character from STRING will
4747      never be substituted twice.  If REGEXP matches a string of zero
4748      length, the start position for the search is incremented, to avoid
4749      infinite loops.
4750
4751      When a replacement is to be made, REPLACEMENT is inserted into the
4752      expansion, with '\N' substituted by the text matched by the Nth
4753      parenthesized sub-expression of PATSUBST, for up to nine
4754      sub-expressions.  The escape '\&' is replaced by the text of the
4755      entire regular expression matched.  For all other characters, '\'
4756      treats the next character literally.  A warning is issued if there
4757      were fewer sub-expressions than the '\N' requested, or if there is
4758      a trailing '\'.
4759
4760      The REPLACEMENT argument can be omitted, in which case the text
4761      matched by REGEXP is deleted.
4762
4763      The macro 'patsubst' is recognized only with parameters.
4764
4765      patsubst(`GNUs not Unix', `^', `OBS: ')
4766      =>OBS: GNUs not Unix
4767      patsubst(`GNUs not Unix', `\<', `OBS: ')
4768      =>OBS: GNUs OBS: not OBS: Unix
4769      patsubst(`GNUs not Unix', `\w*', `(\&)')
4770      =>(GNUs)() (not)() (Unix)()
4771      patsubst(`GNUs not Unix', `\w+', `(\&)')
4772      =>(GNUs) (not) (Unix)
4773      patsubst(`GNUs not Unix', `[A-Z][a-z]+')
4774      =>GN not 
4775      patsubst(`GNUs not Unix', `not', `NOT\')
4776      error->m4:stdin:6: Warning: trailing \ ignored in replacement
4777      =>GNUs NOT Unix
4778
4779    Here is a slightly more realistic example, which capitalizes
4780 individual words or whole sentences, by substituting calls of the macros
4781 'upcase' and 'downcase' into the strings.
4782
4783  -- Composite: upcase (TEXT)
4784  -- Composite: downcase (TEXT)
4785  -- Composite: capitalize (TEXT)
4786      Expand to TEXT, but with capitalization changed: 'upcase' changes
4787      all letters to upper case, 'downcase' changes all letters to lower
4788      case, and 'capitalize' changes the first character of each word to
4789      upper case and the remaining characters to lower case.
4790
4791    First, an example of their usage, using implementations distributed
4792 in 'm4-1.4.18/examples/capitalize.m4'.
4793
4794      $ m4 -I examples
4795      include(`capitalize.m4')
4796      =>
4797      upcase(`GNUs not Unix')
4798      =>GNUS NOT UNIX
4799      downcase(`GNUs not Unix')
4800      =>gnus not unix
4801      capitalize(`GNUs not Unix')
4802      =>Gnus Not Unix
4803
4804    Now for the implementation.  There is a helper macro '_capitalize'
4805 which puts only its first word in mixed case.  Then 'capitalize' merely
4806 parses out the words, and replaces them with an invocation of
4807 '_capitalize'.  (As presented here, the 'capitalize' macro has some
4808 subtle flaws.  You should try to see if you can find and correct them;
4809 or *note Answers: Improved capitalize.).
4810
4811      $ m4 -I examples
4812      undivert(`capitalize.m4')dnl
4813      =>divert(`-1')
4814      =># upcase(text)
4815      =># downcase(text)
4816      =># capitalize(text)
4817      =>#   change case of text, simple version
4818      =>define(`upcase', `translit(`$*', `a-z', `A-Z')')
4819      =>define(`downcase', `translit(`$*', `A-Z', `a-z')')
4820      =>define(`_capitalize',
4821      =>       `regexp(`$1', `^\(\w\)\(\w*\)',
4822      =>               `upcase(`\1')`'downcase(`\2')')')
4823      =>define(`capitalize', `patsubst(`$1', `\w+', `_$0(`\&')')')
4824      =>divert`'dnl
4825
4826    While 'regexp' replaces the whole input with the replacement as soon
4827 as there is a match, 'patsubst' replaces each _occurrence_ of a match
4828 and preserves non-matching pieces:
4829
4830      define(`patreg',
4831      `patsubst($@)
4832      regexp($@)')dnl
4833      patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
4834      =>bar FOO baz FOO
4835      =>FOO
4836      patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
4837      =>bab abb 212
4838      =>bab
4839
4840    Omitting REGEXP evokes a warning, but still produces output; contrast
4841 this with an empty REGEXP argument.
4842
4843      patsubst(`abc')
4844      error->m4:stdin:1: Warning: too few arguments to builtin `patsubst'
4845      =>abc
4846      patsubst(`abc', `')
4847      =>abc
4848      patsubst(`abc', `', `\\-')
4849      =>\-a\-b\-c\-
4850
4851 \1f
4852 File: m4.info,  Node: Format,  Prev: Patsubst,  Up: Text handling
4853
4854 11.7 Formatting strings (printf-like)
4855 =====================================
4856
4857 Formatted output can be made with 'format':
4858
4859  -- Builtin: format (FORMAT-STRING, ...)
4860      Works much like the C function 'printf'.  The first argument
4861      FORMAT-STRING can contain '%' specifications which are satisfied by
4862      additional arguments, and the expansion of 'format' is the
4863      formatted string.
4864
4865      The macro 'format' is recognized only with parameters.
4866
4867    Its use is best described by a few examples:
4868
4869      define(`foo', `The brown fox jumped over the lazy dog')
4870      =>
4871      format(`The string "%s" uses %d characters', foo, len(foo))
4872      =>The string "The brown fox jumped over the lazy dog" uses 38 characters
4873      format(`%*.*d', `-1', `-1', `1')
4874      =>1
4875      format(`%.0f', `56789.9876')
4876      =>56790
4877      len(format(`%-*X', `5000', `1'))
4878      =>5000
4879      ifelse(format(`%010F', `infinity'), `       INF', `success',
4880             format(`%010F', `infinity'), `  INFINITY', `success',
4881             format(`%010F', `infinity'))
4882      =>success
4883      ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success',
4884             format(`%.1A', `1.999'), `0X2.0P+0', `success',
4885             format(`%.1A', `1.999'))
4886      =>success
4887      format(`%g', `0xa.P+1')
4888      =>20
4889
4890    Using the 'forloop' macro defined earlier (*note Forloop::), this
4891 example shows how 'format' can be used to produce tabular output.
4892
4893      $ m4 -I examples
4894      include(`forloop.m4')
4895      =>
4896      forloop(`i', `1', `10', `format(`%6d squared is %10d
4897      ', i, eval(i**2))')
4898      =>     1 squared is          1
4899      =>     2 squared is          4
4900      =>     3 squared is          9
4901      =>     4 squared is         16
4902      =>     5 squared is         25
4903      =>     6 squared is         36
4904      =>     7 squared is         49
4905      =>     8 squared is         64
4906      =>     9 squared is         81
4907      =>    10 squared is        100
4908      =>
4909
4910    The builtin 'format' is modeled after the ANSI C 'printf' function,
4911 and supports these '%' specifiers: 'c', 's', 'd', 'o', 'x', 'X', 'u',
4912 'a', 'A', 'e', 'E', 'f', 'F', 'g', 'G', and '%'; it supports field
4913 widths and precisions, and the flags '+', '-', ' ', '0', '#', and '''.
4914 For integer specifiers, the width modifiers 'hh', 'h', and 'l' are
4915 recognized, and for floating point specifiers, the width modifier 'l' is
4916 recognized.  Items not yet supported include positional arguments, the
4917 'n', 'p', 'S', and 'C' specifiers, the 'z', 't', 'j', 'L' and 'll'
4918 modifiers, and any platform extensions available in the native 'printf'.
4919 For more details on the functioning of 'printf', see the C Library
4920 Manual, or the POSIX specification (for example, '%a' is supported even
4921 on platforms that haven't yet implemented C99 hexadecimal floating point
4922 output natively).
4923
4924    Unrecognized specifiers result in a warning.  It is anticipated that
4925 a future release of GNU 'm4' will support more specifiers, and give
4926 better warnings when various problems such as overflow are encountered.
4927 Likewise, escape sequences are not yet recognized.
4928
4929      format(`%p', `0')
4930      error->m4:stdin:1: Warning: unrecognized specifier in `%p'
4931      =>
4932
4933 \1f
4934 File: m4.info,  Node: Arithmetic,  Next: Shell commands,  Prev: Text handling,  Up: Top
4935
4936 12 Macros for doing arithmetic
4937 ******************************
4938
4939 Integer arithmetic is included in 'm4', with a C-like syntax.  As
4940 convenient shorthands, there are builtins for simple increment and
4941 decrement operations.
4942
4943 * Menu:
4944
4945 * Incr::                        Decrement and increment operators
4946 * Eval::                        Evaluating integer expressions
4947
4948 \1f
4949 File: m4.info,  Node: Incr,  Next: Eval,  Up: Arithmetic
4950
4951 12.1 Decrement and increment operators
4952 ======================================
4953
4954 Increment and decrement of integers are supported using the builtins
4955 'incr' and 'decr':
4956
4957  -- Builtin: incr (NUMBER)
4958  -- Builtin: decr (NUMBER)
4959      Expand to the numerical value of NUMBER, incremented or
4960      decremented, respectively, by one.  Except for the empty string,
4961      the expansion is empty if NUMBER could not be parsed.
4962
4963      The macros 'incr' and 'decr' are recognized only with parameters.
4964
4965      incr(`4')
4966      =>5
4967      decr(`7')
4968      =>6
4969      incr()
4970      error->m4:stdin:3: empty string treated as 0 in builtin `incr'
4971      =>1
4972      decr()
4973      error->m4:stdin:4: empty string treated as 0 in builtin `decr'
4974      =>-1
4975
4976 \1f
4977 File: m4.info,  Node: Eval,  Prev: Incr,  Up: Arithmetic
4978
4979 12.2 Evaluating integer expressions
4980 ===================================
4981
4982 Integer expressions are evaluated with 'eval':
4983
4984  -- Builtin: eval (EXPRESSION, [RADIX = '10'], [WIDTH])
4985      Expands to the value of EXPRESSION.  The expansion is empty if a
4986      problem is encountered while parsing the arguments.  If specified,
4987      RADIX and WIDTH control the format of the output.
4988
4989      Calculations are done with 32-bit signed numbers.  Overflow
4990      silently results in wraparound.  A warning is issued if division by
4991      zero is attempted, or if EXPRESSION could not be parsed.
4992
4993      Expressions can contain the following operators, listed in order of
4994      decreasing precedence.
4995
4996      '()'
4997           Parentheses
4998      '+ - ~ !'
4999           Unary plus and minus, and bitwise and logical negation
5000      '**'
5001           Exponentiation
5002      '* / %'
5003           Multiplication, division, and modulo
5004      '+ -'
5005           Addition and subtraction
5006      '<< >>'
5007           Shift left or right
5008      '> >= < <='
5009           Relational operators
5010      '== !='
5011           Equality operators
5012      '&'
5013           Bitwise and
5014      '^'
5015           Bitwise exclusive-or
5016      '|'
5017           Bitwise or
5018      '&&'
5019           Logical and
5020      '||'
5021           Logical or
5022
5023      The macro 'eval' is recognized only with parameters.
5024
5025    All binary operators, except exponentiation, are left associative.  C
5026 operators that perform variable assignment, such as '+=' or '--', are
5027 not implemented, since 'eval' only operates on constants, not variables.
5028 Attempting to use them results in an error.  However, since traditional
5029 implementations treated '=' as an undocumented alias for '==' as opposed
5030 to an assignment operator, this usage is supported as a special case.
5031 Be aware that a future version of GNU M4 may support assignment
5032 semantics as an extension when POSIX mode is not requested, and that
5033 using '=' to check equality is not portable.
5034
5035      eval(`2 = 2')
5036      error->m4:stdin:1: Warning: recommend ==, not =, for equality operator
5037      =>1
5038      eval(`++0')
5039      error->m4:stdin:2: invalid operator in eval: ++0
5040      =>
5041      eval(`0 |= 1')
5042      error->m4:stdin:3: invalid operator in eval: 0 |= 1
5043      =>
5044
5045    Note that some older 'm4' implementations use '^' as an alternate
5046 operator for the exponentiation, although POSIX requires the C behavior
5047 of bitwise exclusive-or.  The precedence of the negation operators, '~'
5048 and '!', was traditionally lower than equality.  The unary operators
5049 could not be used reliably more than once on the same term without
5050 intervening parentheses.  The traditional precedence of the equality
5051 operators '==' and '!=' was identical instead of lower than the
5052 relational operators such as '<', even through GNU M4 1.4.8.  Starting
5053 with version 1.4.9, GNU M4 correctly follows POSIX precedence rules.  M4
5054 scripts designed to be portable between releases must be aware that
5055 parentheses may be required to enforce C precedence rules.  Likewise,
5056 division by zero, even in the unused branch of a short-circuiting
5057 operator, is not always well-defined in other implementations.
5058
5059    Following are some examples where the current version of M4 follows C
5060 precedence rules, but where older versions and some other
5061 implementations of 'm4' require explicit parentheses to get the correct
5062 result:
5063
5064      eval(`1 == 2 > 0')
5065      =>1
5066      eval(`(1 == 2) > 0')
5067      =>0
5068      eval(`! 0 * 2')
5069      =>2
5070      eval(`! (0 * 2)')
5071      =>1
5072      eval(`1 | 1 ^ 1')
5073      =>1
5074      eval(`(1 | 1) ^ 1')
5075      =>0
5076      eval(`+ + - ~ ! ~ 0')
5077      =>1
5078      eval(`2 || 1 / 0')
5079      =>1
5080      eval(`0 || 1 / 0')
5081      error->m4:stdin:9: divide by zero in eval: 0 || 1 / 0
5082      =>
5083      eval(`0 && 1 % 0')
5084      =>0
5085      eval(`2 && 1 % 0')
5086      error->m4:stdin:11: modulo by zero in eval: 2 && 1 % 0
5087      =>
5088
5089    As a GNU extension, the operator '**' performs integral
5090 exponentiation.  The operator is right-associative, and if evaluated,
5091 the exponent must be non-negative, and at least one of the arguments
5092 must be non-zero, or a warning is issued.
5093
5094      eval(`2 ** 3 ** 2')
5095      =>512
5096      eval(`(2 ** 3) ** 2')
5097      =>64
5098      eval(`0 ** 1')
5099      =>0
5100      eval(`2 ** 0')
5101      =>1
5102      eval(`0 ** 0')
5103      =>
5104      error->m4:stdin:5: divide by zero in eval: 0 ** 0
5105      eval(`4 ** -2')
5106      error->m4:stdin:6: negative exponent in eval: 4 ** -2
5107      =>
5108
5109    Within EXPRESSION, (but not RADIX or WIDTH), numbers without a
5110 special prefix are decimal.  A simple '0' prefix introduces an octal
5111 number.  '0x' introduces a hexadecimal number.  As GNU extensions, '0b'
5112 introduces a binary number.  '0r' introduces a number expressed in any
5113 radix between 1 and 36: the prefix should be immediately followed by the
5114 decimal expression of the radix, a colon, then the digits making the
5115 number.  For radix 1, leading zeros are ignored, and all remaining
5116 digits must be '1'; for all other radices, the digits are '0', '1', '2',
5117 ....  Beyond '9', the digits are 'a', 'b' ... up to 'z'.  Lower and
5118 upper case letters can be used interchangeably in numbers prefixes and
5119 as number digits.
5120
5121    Parentheses may be used to group subexpressions whenever needed.  For
5122 the relational operators, a true relation returns '1', and a false
5123 relation return '0'.
5124
5125    Here are a few examples of use of 'eval'.
5126
5127      eval(`-3 * 5')
5128      =>-15
5129      eval(`-99 / 10')
5130      =>-9
5131      eval(`-99 % 10')
5132      =>-9
5133      eval(`99 % -10')
5134      =>9
5135      eval(index(`Hello world', `llo') >= 0)
5136      =>1
5137      eval(`0r1:0111 + 0b100 + 0r3:12')
5138      =>12
5139      define(`square', `eval(`($1) ** 2')')
5140      =>
5141      square(`9')
5142      =>81
5143      square(square(`5')` + 1')
5144      =>676
5145      define(`foo', `666')
5146      =>
5147      eval(`foo / 6')
5148      error->m4:stdin:11: bad expression in eval: foo / 6
5149      =>
5150      eval(foo / 6)
5151      =>111
5152
5153    As the last two lines show, 'eval' does not handle macro names, even
5154 if they expand to a valid expression (or part of a valid expression).
5155 Therefore all macros must be expanded before they are passed to 'eval'.
5156
5157    Some calculations are not portable to other implementations, since
5158 they have undefined semantics in C, but GNU 'm4' has well-defined
5159 behavior on overflow.  When shifting, an out-of-range shift amount is
5160 implicitly brought into the range of 32-bit signed integers using an
5161 implicit bit-wise and with 0x1f).
5162
5163      define(`max_int', eval(`0x7fffffff'))
5164      =>
5165      define(`min_int', incr(max_int))
5166      =>
5167      eval(min_int` < 0')
5168      =>1
5169      eval(max_int` > 0')
5170      =>1
5171      ifelse(eval(min_int` / -1'), min_int, `overflow occurred')
5172      =>overflow occurred
5173      min_int
5174      =>-2147483648
5175      eval(`0x80000000 % -1')
5176      =>0
5177      eval(`-4 >> 1')
5178      =>-2
5179      eval(`-4 >> 33')
5180      =>-2
5181
5182    If RADIX is specified, it specifies the radix to be used in the
5183 expansion.  The default radix is 10; this is also the case if RADIX is
5184 the empty string.  A warning results if the radix is outside the range
5185 of 1 through 36, inclusive.  The result of 'eval' is always taken to be
5186 signed.  No radix prefix is output, and for radices greater than 10, the
5187 digits are lower case.  The WIDTH argument specifies the minimum output
5188 width, excluding any negative sign.  The result is zero-padded to extend
5189 the expansion to the requested width.  A warning results if the width is
5190 negative.  If RADIX or WIDTH is out of bounds, the expansion of 'eval'
5191 is empty.
5192
5193      eval(`666', `10')
5194      =>666
5195      eval(`666', `11')
5196      =>556
5197      eval(`666', `6')
5198      =>3030
5199      eval(`666', `6', `10')
5200      =>0000003030
5201      eval(`-666', `6', `10')
5202      =>-0000003030
5203      eval(`10', `', `0')
5204      =>10
5205      `0r1:'eval(`10', `1', `11')
5206      =>0r1:01111111111
5207      eval(`10', `16')
5208      =>a
5209      eval(`1', `37')
5210      error->m4:stdin:9: radix 37 in builtin `eval' out of range
5211      =>
5212      eval(`1', , `-1')
5213      error->m4:stdin:10: negative width to builtin `eval'
5214      =>
5215      eval()
5216      error->m4:stdin:11: empty string treated as 0 in builtin `eval'
5217      =>0
5218
5219 \1f
5220 File: m4.info,  Node: Shell commands,  Next: Miscellaneous,  Prev: Arithmetic,  Up: Top
5221
5222 13 Macros for running shell commands
5223 ************************************
5224
5225 There are a few builtin macros in 'm4' that allow you to run shell
5226 commands from within 'm4'.
5227
5228    Note that the definition of a valid shell command is system
5229 dependent.  On UNIX systems, this is the typical '/bin/sh'.  But on
5230 other systems, such as native Windows, the shell has a different syntax
5231 of commands that it understands.  Some examples in this chapter assume
5232 '/bin/sh', and also demonstrate how to quit early with a known exit
5233 value if this is not the case.
5234
5235 * Menu:
5236
5237 * Platform macros::             Determining the platform
5238 * Syscmd::                      Executing simple commands
5239 * Esyscmd::                     Reading the output of commands
5240 * Sysval::                      Exit status
5241 * Mkstemp::                     Making temporary files
5242
5243 \1f
5244 File: m4.info,  Node: Platform macros,  Next: Syscmd,  Up: Shell commands
5245
5246 13.1 Determining the platform
5247 =============================
5248
5249 Sometimes it is desirable for an input file to know which platform 'm4'
5250 is running on.  GNU 'm4' provides several macros that are predefined to
5251 expand to the empty string; checking for their existence will confirm
5252 platform details.
5253
5254  -- Optional builtin: __gnu__
5255  -- Optional builtin: __os2__
5256  -- Optional builtin: os2
5257  -- Optional builtin: __unix__
5258  -- Optional builtin: unix
5259  -- Optional builtin: __windows__
5260  -- Optional builtin: windows
5261      Each of these macros is conditionally defined as needed to describe
5262      the environment of 'm4'.  If defined, each macro expands to the
5263      empty string.  For now, these macros silently ignore all arguments,
5264      but in a future release of M4, they might warn if arguments are
5265      present.
5266
5267    When GNU extensions are in effect (that is, when you did not use the
5268 '-G' option, *note Invoking m4: Limits control.), GNU 'm4' will define
5269 the macro '__gnu__' to expand to the empty string.
5270
5271      $ m4
5272      __gnu__
5273      =>
5274      __gnu__(`ignored')
5275      =>
5276      Extensions are ifdef(`__gnu__', `active', `inactive')
5277      =>Extensions are active
5278
5279      $ m4 -G
5280      __gnu__
5281      =>__gnu__
5282      __gnu__(`ignored')
5283      =>__gnu__(ignored)
5284      Extensions are ifdef(`__gnu__', `active', `inactive')
5285      =>Extensions are inactive
5286
5287    On UNIX systems, GNU 'm4' will define '__unix__' by default, or
5288 'unix' when the '-G' option is specified.
5289
5290    On native Windows systems, GNU 'm4' will define '__windows__' by
5291 default, or 'windows' when the '-G' option is specified.
5292
5293    On OS/2 systems, GNU 'm4' will define '__os2__' by default, or 'os2'
5294 when the '-G' option is specified.
5295
5296    If GNU 'm4' does not provide a platform macro for your system, please
5297 report that as a bug.
5298
5299      define(`provided', `0')
5300      =>
5301      ifdef(`__unix__', `define(`provided', incr(provided))')
5302      =>
5303      ifdef(`__windows__', `define(`provided', incr(provided))')
5304      =>
5305      ifdef(`__os2__', `define(`provided', incr(provided))')
5306      =>
5307      provided
5308      =>1
5309
5310 \1f
5311 File: m4.info,  Node: Syscmd,  Next: Esyscmd,  Prev: Platform macros,  Up: Shell commands
5312
5313 13.2 Executing simple commands
5314 ==============================
5315
5316 Any shell command can be executed, using 'syscmd':
5317
5318  -- Builtin: syscmd (SHELL-COMMAND)
5319      Executes SHELL-COMMAND as a shell command.
5320
5321      The expansion of 'syscmd' is void, _not_ the output from
5322      SHELL-COMMAND!  Output or error messages from SHELL-COMMAND are not
5323      read by 'm4'.  *Note Esyscmd::, if you need to process the command
5324      output.
5325
5326      Prior to executing the command, 'm4' flushes its buffers.  The
5327      default standard input, output and error of SHELL-COMMAND are the
5328      same as those of 'm4'.
5329
5330      By default, the SHELL-COMMAND will be used as the argument to the
5331      '-c' option of the '/bin/sh' shell (or the version of 'sh'
5332      specified by 'command -p getconf PATH', if your system supports
5333      that).  If you prefer a different shell, the 'configure' script can
5334      be given the option '--with-syscmd-shell=LOCATION' to set the
5335      location of an alternative shell at GNU 'm4' installation; the
5336      alternative shell must still support '-c'.
5337
5338      The macro 'syscmd' is recognized only with parameters.
5339
5340      define(`foo', `FOO')
5341      =>
5342      syscmd(`echo foo')
5343      =>foo
5344      =>
5345
5346    Note how the expansion of 'syscmd' keeps the trailing newline of the
5347 command, as well as using the newline that appeared after the macro.
5348
5349    The following is an example of SHELL-COMMAND using the same standard
5350 input as 'm4':
5351
5352      $ echo "m4wrap(\`syscmd(\`cat')')" | m4
5353      =>
5354
5355    It tells 'm4' to read all of its input before executing the wrapped
5356 text, then hand a valid (albeit emptied) pipe as standard input for the
5357 'cat' subcommand.  Therefore, you should be careful when using standard
5358 input (either by specifying no files, or by passing '-' as a file name
5359 on the command line, *note Invoking m4: Command line files.), and also
5360 invoking subcommands via 'syscmd' or 'esyscmd' that consume data from
5361 standard input.  When standard input is a seekable file, the subprocess
5362 will pick up with the next character not yet processed by 'm4'; when it
5363 is a pipe or other non-seekable file, there is no guarantee how much
5364 data will already be buffered by 'm4' and thus unavailable to the child.
5365
5366 \1f
5367 File: m4.info,  Node: Esyscmd,  Next: Sysval,  Prev: Syscmd,  Up: Shell commands
5368
5369 13.3 Reading the output of commands
5370 ===================================
5371
5372 If you want 'm4' to read the output of a shell command, use 'esyscmd':
5373
5374  -- Builtin: esyscmd (SHELL-COMMAND)
5375      Expands to the standard output of the shell command SHELL-COMMAND.
5376
5377      Prior to executing the command, 'm4' flushes its buffers.  The
5378      default standard input and standard error of SHELL-COMMAND are the
5379      same as those of 'm4'.  The error output of SHELL-COMMAND is not a
5380      part of the expansion: it will appear along with the error output
5381      of 'm4'.
5382
5383      By default, the SHELL-COMMAND will be used as the argument to the
5384      '-c' option of the '/bin/sh' shell (or the version of 'sh'
5385      specified by 'command -p getconf PATH', if your system supports
5386      that).  If you prefer a different shell, the 'configure' script can
5387      be given the option '--with-syscmd-shell=LOCATION' to set the
5388      location of an alternative shell at GNU 'm4' installation; the
5389      alternative shell must still support '-c'.
5390
5391      The macro 'esyscmd' is recognized only with parameters.
5392
5393      define(`foo', `FOO')
5394      =>
5395      esyscmd(`echo foo')
5396      =>FOO
5397      =>
5398
5399    Note how the expansion of 'esyscmd' keeps the trailing newline of the
5400 command, as well as using the newline that appeared after the macro.
5401
5402    Just as with 'syscmd', care must be exercised when sharing standard
5403 input between 'm4' and the child process of 'esyscmd'.
5404
5405 \1f
5406 File: m4.info,  Node: Sysval,  Next: Mkstemp,  Prev: Esyscmd,  Up: Shell commands
5407
5408 13.4 Exit status
5409 ================
5410
5411 To see whether a shell command succeeded, use 'sysval':
5412
5413  -- Builtin: sysval
5414      Expands to the exit status of the last shell command run with
5415      'syscmd' or 'esyscmd'.  Expands to 0 if no command has been run
5416      yet.
5417
5418      sysval
5419      =>0
5420      syscmd(`false')
5421      =>
5422      ifelse(sysval, `0', `zero', `non-zero')
5423      =>non-zero
5424      syscmd(`exit 2')
5425      =>
5426      sysval
5427      =>2
5428      syscmd(`true')
5429      =>
5430      sysval
5431      =>0
5432      esyscmd(`false')
5433      =>
5434      ifelse(sysval, `0', `zero', `non-zero')
5435      =>non-zero
5436      esyscmd(`echo dnl && exit 127')
5437      =>
5438      sysval
5439      =>127
5440      esyscmd(`true')
5441      =>
5442      sysval
5443      =>0
5444
5445    'sysval' results in 127 if there was a problem executing the command,
5446 for example, if the system-imposed argument length is exceeded, or if
5447 there were not enough resources to fork.  It is not possible to
5448 distinguish between failed execution and successful execution that had
5449 an exit status of 127, unless there was output from the child process.
5450
5451    On UNIX platforms, where it is possible to detect when command
5452 execution is terminated by a signal, rather than a normal exit, the
5453 result is the signal number shifted left by eight bits.
5454
5455      dnl This test assumes kill is a shell builtin, and that signals are
5456      dnl recognizable.
5457      ifdef(`__unix__', ,
5458            `errprint(` skipping: syscmd does not have unix semantics
5459      ')m4exit(`77')')dnl
5460      syscmd(`kill -9 $$')
5461      =>
5462      sysval
5463      =>2304
5464      syscmd()
5465      =>
5466      sysval
5467      =>0
5468      esyscmd(`kill -9 $$')
5469      =>
5470      sysval
5471      =>2304
5472
5473 \1f
5474 File: m4.info,  Node: Mkstemp,  Prev: Sysval,  Up: Shell commands
5475
5476 13.5 Making temporary files
5477 ===========================
5478
5479 Commands specified to 'syscmd' or 'esyscmd' might need a temporary file,
5480 for output or for some other purpose.  There is a builtin macro,
5481 'mkstemp', for making a temporary file:
5482
5483  -- Builtin: mkstemp (TEMPLATE)
5484  -- Builtin: maketemp (TEMPLATE)
5485      Expands to the quoted name of a new, empty file, made from the
5486      string TEMPLATE, which should end with the string 'XXXXXX'.  The
5487      six 'X' characters are then replaced with random characters
5488      matching the regular expression '[a-zA-Z0-9._-]', in order to make
5489      the file name unique.  If fewer than six 'X' characters are found
5490      at the end of 'template', the result will be longer than the
5491      template.  The created file will have access permissions as if by
5492      'chmod =rw,go=', meaning that the current umask of the 'm4' process
5493      is taken into account, and at most only the current user can read
5494      and write the file.
5495
5496      The traditional behavior, standardized by POSIX, is that 'maketemp'
5497      merely replaces the trailing 'X' with the process id, without
5498      creating a file or quoting the expansion, and without ensuring that
5499      the resulting string is a unique file name.  In part, this means
5500      that using the same TEMPLATE twice in the same input file will
5501      result in the same expansion.  This behavior is a security hole, as
5502      it is very easy for another process to guess the name that will be
5503      generated, and thus interfere with a subsequent use of 'syscmd'
5504      trying to manipulate that file name.  Hence, POSIX has recommended
5505      that all new implementations of 'm4' provide the secure 'mkstemp'
5506      builtin, and that users of 'm4' check for its existence.
5507
5508      The expansion is void and an error issued if a temporary file could
5509      not be created.
5510
5511      The macros 'mkstemp' and 'maketemp' are recognized only with
5512      parameters.
5513
5514    If you try this next example, you will most likely get different
5515 output for the two file names, since the replacement characters are
5516 randomly chosen:
5517
5518      $ m4
5519      define(`tmp', `oops')
5520      =>
5521      maketemp(`/tmp/fooXXXXXX')
5522      =>/tmp/fooa07346
5523      ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))',
5524            `define(`mkstemp', defn(`maketemp'))dnl
5525      errprint(`warning: potentially insecure maketemp implementation
5526      ')')
5527      =>
5528      mkstemp(`doc')
5529      =>docQv83Uw
5530
5531    Unless you use the '--traditional' command line option (or '-G',
5532 *note Invoking m4: Limits control.), the GNU version of 'maketemp' is
5533 secure.  This means that using the same template to multiple calls will
5534 generate multiple files.  However, we recommend that you use the new
5535 'mkstemp' macro, introduced in GNU M4 1.4.8, which is secure even in
5536 traditional mode.  Also, as of M4 1.4.11, the secure implementation
5537 quotes the resulting file name, so that you are guaranteed to know what
5538 file was created even if the random file name happens to match an
5539 existing macro.  Notice that this example is careful to use 'defn' to
5540 avoid unintended expansion of 'foo'.
5541
5542      $ m4
5543      define(`foo', `errprint(`oops')')
5544      =>
5545      syscmd(`rm -f foo-??????')sysval
5546      =>0
5547      define(`file1', maketemp(`foo-XXXXXX'))dnl
5548      ifelse(esyscmd(`echo \` foo-?????? \''), ` foo-?????? ',
5549             `no file', `created')
5550      =>created
5551      define(`file2', maketemp(`foo-XX'))dnl
5552      define(`file3', mkstemp(`foo-XXXXXX'))dnl
5553      ifelse(len(defn(`file1')), len(defn(`file2')),
5554             `same length', `different')
5555      =>same length
5556      ifelse(defn(`file1'), defn(`file2'), `same', `different file')
5557      =>different file
5558      ifelse(defn(`file2'), defn(`file3'), `same', `different file')
5559      =>different file
5560      ifelse(defn(`file1'), defn(`file3'), `same', `different file')
5561      =>different file
5562      syscmd(`rm 'defn(`file1') defn(`file2') defn(`file3'))
5563      =>
5564      sysval
5565      =>0
5566
5567 \1f
5568 File: m4.info,  Node: Miscellaneous,  Next: Frozen files,  Prev: Shell commands,  Up: Top
5569
5570 14 Miscellaneous builtin macros
5571 *******************************
5572
5573 This chapter describes various builtins, that do not really belong in
5574 any of the previous chapters.
5575
5576 * Menu:
5577
5578 * Errprint::                    Printing error messages
5579 * Location::                    Printing current location
5580 * M4exit::                      Exiting from 'm4'
5581
5582 \1f
5583 File: m4.info,  Node: Errprint,  Next: Location,  Up: Miscellaneous
5584
5585 14.1 Printing error messages
5586 ============================
5587
5588 You can print error messages using 'errprint':
5589
5590  -- Builtin: errprint (MESSAGE, ...)
5591      Prints MESSAGE and the rest of the arguments to standard error,
5592      separated by spaces.  Standard error is used, regardless of the
5593      '--debugfile' option (*note Invoking m4: Debugging options.).
5594
5595      The expansion of 'errprint' is void.  The macro 'errprint' is
5596      recognized only with parameters.
5597
5598      errprint(`Invalid arguments to forloop
5599      ')
5600      error->Invalid arguments to forloop
5601      =>
5602      errprint(`1')errprint(`2',`3
5603      ')
5604      error->12 3
5605      =>
5606
5607    A trailing newline is _not_ printed automatically, so it should be
5608 supplied as part of the argument, as in the example.  Unfortunately, the
5609 exact output of 'errprint' is not very portable to other 'm4'
5610 implementations: POSIX requires that all arguments be printed, but some
5611 implementations of 'm4' only print the first.  Furthermore, some BSD
5612 implementations always append a newline for each 'errprint' call,
5613 regardless of whether the last argument already had one, and POSIX is
5614 silent on whether this is acceptable.
5615
5616 \1f
5617 File: m4.info,  Node: Location,  Next: M4exit,  Prev: Errprint,  Up: Miscellaneous
5618
5619 14.2 Printing current location
5620 ==============================
5621
5622 To make it possible to specify the location of an error, three utility
5623 builtins exist:
5624
5625  -- Builtin: __file__
5626  -- Builtin: __line__
5627  -- Builtin: __program__
5628      Expand to the quoted name of the current input file, the current
5629      input line number in that file, and the quoted name of the current
5630      invocation of 'm4'.
5631
5632      errprint(__program__:__file__:__line__: `input error
5633      ')
5634      error->m4:stdin:1: input error
5635      =>
5636
5637    Line numbers start at 1 for each file.  If the file was found due to
5638 the '-I' option or 'M4PATH' environment variable, that is reflected in
5639 the file name.  The syncline option ('-s', *note Invoking m4:
5640 Preprocessor features.), and the 'f' and 'l' flags of 'debugmode' (*note
5641 Debug Levels::), also use this notion of current file and line.
5642 Redefining the three location macros has no effect on syncline, debug,
5643 warning, or error message output.
5644
5645    This example reuses the file 'incl.m4' mentioned earlier (*note
5646 Include::):
5647
5648      $ m4 -I examples
5649      define(`foo', ``$0' called at __file__:__line__')
5650      =>
5651      foo
5652      =>foo called at stdin:2
5653      include(`incl.m4')
5654      =>Include file start
5655      =>foo called at examples/incl.m4:2
5656      =>Include file end
5657      =>
5658
5659    The location of macros invoked during the rescanning of macro
5660 expansion text corresponds to the location in the file where the
5661 expansion was triggered, regardless of how many newline characters the
5662 expansion text contains.  As of GNU M4 1.4.8, the location of text
5663 wrapped with 'm4wrap' (*note M4wrap::) is the point at which the
5664 'm4wrap' was invoked.  Previous versions, however, behaved as though
5665 wrapped text came from line 0 of the file "".
5666
5667      define(`echo', `$@')
5668      =>
5669      define(`foo', `echo(__line__
5670      __line__)')
5671      =>
5672      echo(__line__
5673      __line__)
5674      =>4
5675      =>5
5676      m4wrap(`foo
5677      ')
5678      =>
5679      foo(errprint(__line__
5680      __line__
5681      ))
5682      error->8
5683      error->9
5684      =>8
5685      =>8
5686      __line__
5687      =>11
5688      m4wrap(`__line__
5689      ')
5690      =>
5691      ^D
5692      =>12
5693      =>6
5694      =>6
5695
5696    The '__program__' macro behaves like '$0' in shell terminology.  If
5697 you invoke 'm4' through an absolute path or a link with a different
5698 spelling, rather than by relying on a 'PATH' search for plain 'm4', it
5699 will affect how '__program__' expands.  The intent is that you can use
5700 it to produce error messages with the same formatting that 'm4' produces
5701 internally.  It can also be used within 'syscmd' (*note Syscmd::) to
5702 pick the same version of 'm4' that is currently running, rather than
5703 whatever version of 'm4' happens to be first in 'PATH'.  It was first
5704 introduced in GNU M4 1.4.6.
5705
5706 \1f
5707 File: m4.info,  Node: M4exit,  Prev: Location,  Up: Miscellaneous
5708
5709 14.3 Exiting from 'm4'
5710 ======================
5711
5712 If you need to exit from 'm4' before the entire input has been read, you
5713 can use 'm4exit':
5714
5715  -- Builtin: m4exit ([CODE = '0'])
5716      Causes 'm4' to exit, with exit status CODE.  If CODE is left out,
5717      the exit status is zero.  If CODE cannot be parsed, or is outside
5718      the range of 0 to 255, the exit status is one.  No further input is
5719      read, and all wrapped and diverted text is discarded.
5720
5721      m4wrap(`This text is lost due to `m4exit'.')
5722      =>
5723      divert(`1') So is this.
5724      divert
5725      =>
5726      m4exit And this is never read.
5727
5728    A common use of this is to abort processing:
5729
5730  -- Composite: fatal_error (MESSAGE)
5731      Abort processing with an error message and non-zero status.  Prefix
5732      MESSAGE with details about where the error occurred, and print the
5733      resulting string to standard error.
5734
5735      define(`fatal_error',
5736             `errprint(__program__:__file__:__line__`: fatal error: $*
5737      ')m4exit(`1')')
5738      =>
5739      fatal_error(`this is a BAD one, buster')
5740      error->m4:stdin:4: fatal error: this is a BAD one, buster
5741
5742    After this macro call, 'm4' will exit with exit status 1.  This macro
5743 is only intended for error exits, since the normal exit procedures are
5744 not followed, i.e., diverted text is not undiverted, and saved text
5745 (*note M4wrap::) is not reread.  (This macro could be made more robust
5746 to earlier versions of 'm4'.  You should try to see if you can find
5747 weaknesses and correct them; or *note Answers: Improved fatal_error.).
5748
5749    Note that it is still possible for the exit status to be different
5750 than what was requested by 'm4exit'.  If 'm4' detects some other error,
5751 such as a write error on standard output, the exit status will be
5752 non-zero even if 'm4exit' requested zero.
5753
5754    If standard input is seekable, then the file will be positioned at
5755 the next unread character.  If it is a pipe or other non-seekable file,
5756 then there are no guarantees how much data 'm4' might have read into
5757 buffers, and thus discarded.
5758
5759 \1f
5760 File: m4.info,  Node: Frozen files,  Next: Compatibility,  Prev: Miscellaneous,  Up: Top
5761
5762 15 Fast loading of frozen state
5763 *******************************
5764
5765 Some bigger 'm4' applications may be built over a common base containing
5766 hundreds of definitions and other costly initializations.  Usually, the
5767 common base is kept in one or more declarative files, which files are
5768 listed on each 'm4' invocation prior to the user's input file, or else
5769 each input file uses 'include'.
5770
5771    Reading the common base of a big application, over and over again,
5772 may be time consuming.  GNU 'm4' offers some machinery to speed up the
5773 start of an application using lengthy common bases.
5774
5775 * Menu:
5776
5777 * Using frozen files::          Using frozen files
5778 * Frozen file format::          Frozen file format
5779
5780 \1f
5781 File: m4.info,  Node: Using frozen files,  Next: Frozen file format,  Up: Frozen files
5782
5783 15.1 Using frozen files
5784 =======================
5785
5786 Suppose a user has a library of 'm4' initializations in 'base.m4', which
5787 is then used with multiple input files:
5788
5789      $ m4 base.m4 input1.m4
5790      $ m4 base.m4 input2.m4
5791      $ m4 base.m4 input3.m4
5792
5793    Rather than spending time parsing the fixed contents of 'base.m4'
5794 every time, the user might rather execute:
5795
5796      $ m4 -F base.m4f base.m4
5797
5798 once, and further execute, as often as needed:
5799
5800      $ m4 -R base.m4f input1.m4
5801      $ m4 -R base.m4f input2.m4
5802      $ m4 -R base.m4f input3.m4
5803
5804 with the varying input.  The first call, containing the '-F' option,
5805 only reads and executes file 'base.m4', defining various application
5806 macros and computing other initializations.  Once the input file
5807 'base.m4' has been completely processed, GNU 'm4' produces in 'base.m4f'
5808 a "frozen" file, that is, a file which contains a kind of snapshot of
5809 the 'm4' internal state.
5810
5811    Later calls, containing the '-R' option, are able to reload the
5812 internal state of 'm4', from 'base.m4f', _prior_ to reading any other
5813 input files.  This means instead of starting with a virgin copy of 'm4',
5814 input will be read after having effectively recovered the effect of a
5815 prior run.  In our example, the effect is the same as if file 'base.m4'
5816 has been read anew.  However, this effect is achieved a lot faster.
5817
5818    Only one frozen file may be created or read in any one 'm4'
5819 invocation.  It is not possible to recover two frozen files at once.
5820 However, frozen files may be updated incrementally, through using '-R'
5821 and '-F' options simultaneously.  For example, if some care is taken,
5822 the command:
5823
5824      $ m4 file1.m4 file2.m4 file3.m4 file4.m4
5825
5826 could be broken down in the following sequence, accumulating the same
5827 output:
5828
5829      $ m4 -F file1.m4f file1.m4
5830      $ m4 -R file1.m4f -F file2.m4f file2.m4
5831      $ m4 -R file2.m4f -F file3.m4f file3.m4
5832      $ m4 -R file3.m4f file4.m4
5833
5834    Some care is necessary because not every effort has been made for
5835 this to work in all cases.  In particular, the trace attribute of macros
5836 is not handled, nor the current setting of 'changeword'.  Currently,
5837 'm4wrap' and 'sysval' also have problems.  Also, interactions for some
5838 options of 'm4', being used in one call and not in the next, have not
5839 been fully analyzed yet.  On the other end, you may be confident that
5840 stacks of 'pushdef' definitions are handled correctly, as well as
5841 undefined or renamed builtins, and changed strings for quotes or
5842 comments.  And future releases of GNU M4 will improve on the utility of
5843 frozen files.
5844
5845    When an 'm4' run is to be frozen, the automatic undiversion which
5846 takes place at end of execution is inhibited.  Instead, all positively
5847 numbered diversions are saved into the frozen file.  The active
5848 diversion number is also transmitted.
5849
5850    A frozen file to be reloaded need not reside in the current
5851 directory.  It is looked up the same way as an 'include' file (*note
5852 Search Path::).
5853
5854    If the frozen file was generated with a newer version of 'm4', and
5855 contains directives that an older 'm4' cannot parse, attempting to load
5856 the frozen file with option '-R' will cause 'm4' to exit with status 63
5857 to indicate version mismatch.
5858
5859 \1f
5860 File: m4.info,  Node: Frozen file format,  Prev: Using frozen files,  Up: Frozen files
5861
5862 15.2 Frozen file format
5863 =======================
5864
5865 Frozen files are sharable across architectures.  It is safe to write a
5866 frozen file on one machine and read it on another, given that the second
5867 machine uses the same or newer version of GNU 'm4'.  It is conventional,
5868 but not required, to give a frozen file the suffix of '.m4f'.
5869
5870    These are simple (editable) text files, made up of directives, each
5871 starting with a capital letter and ending with a newline (<NL>).
5872 Wherever a directive is expected, the character '#' introduces a comment
5873 line; empty lines are also ignored if they are not part of an embedded
5874 string.  In the following descriptions, each LEN refers to the length of
5875 the corresponding strings STR in the next line of input.  Numbers are
5876 always expressed in decimal.  There are no escape characters.  The
5877 directives are:
5878
5879 'C LEN1 , LEN2 <NL> STR1 STR2 <NL>'
5880      Uses STR1 and STR2 as the begin-comment and end-comment strings.
5881      If omitted, then '#' and <NL> are the comment delimiters.
5882
5883 'D NUMBER, LEN <NL> STR <NL>'
5884      Selects diversion NUMBER, making it current, then copy STR in the
5885      current diversion.  NUMBER may be a negative number for a
5886      non-existing diversion.  To merely specify an active selection, use
5887      this command with an empty STR.  With 0 as the diversion NUMBER,
5888      STR will be issued on standard output at reload time.  GNU 'm4'
5889      will not produce the 'D' directive with non-zero length for
5890      diversion 0, but this can be done with manual edits.  This
5891      directive may appear more than once for the same diversion, in
5892      which case the diversion is the concatenation of the various uses.
5893      If omitted, then diversion 0 is current.
5894
5895 'F LEN1 , LEN2 <NL> STR1 STR2 <NL>'
5896      Defines, through 'pushdef', a definition for STR1 expanding to the
5897      function whose builtin name is STR2.  If the builtin does not exist
5898      (for example, if the frozen file was produced by a copy of 'm4'
5899      compiled with changeword support, but the version of 'm4' reloading
5900      was compiled without it), the reload is silent, but any subsequent
5901      use of the definition of STR1 will result in a warning.  This
5902      directive may appear more than once for the same name, and its
5903      order, along with 'T', is important.  If omitted, you will have no
5904      access to any builtins.
5905
5906 'Q LEN1 , LEN2 <NL> STR1 STR2 <NL>'
5907      Uses STR1 and STR2 as the begin-quote and end-quote strings.  If
5908      omitted, then '`' and ''' are the quote delimiters.
5909
5910 'T LEN1 , LEN2 <NL> STR1 STR2 <NL>'
5911      Defines, though 'pushdef', a definition for STR1 expanding to the
5912      text given by STR2.  This directive may appear more than once for
5913      the same name, and its order, along with 'F', is important.
5914
5915 'V NUMBER <NL>'
5916      Confirms the format of the file.  'm4' 1.4.18 only creates and
5917      understands frozen files where NUMBER is 1.  This directive must be
5918      the first non-comment in the file, and may not appear more than
5919      once.
5920
5921 \1f
5922 File: m4.info,  Node: Compatibility,  Next: Answers,  Prev: Frozen files,  Up: Top
5923
5924 16 Compatibility with other versions of 'm4'
5925 ********************************************
5926
5927 This chapter describes the many of the differences between this
5928 implementation of 'm4', and of other implementations found under UNIX,
5929 such as System V Release 4, Solaris, and BSD flavors.  In particular, it
5930 lists the known differences and extensions to POSIX. However, the list
5931 is not necessarily comprehensive.
5932
5933    At the time of this writing, POSIX 2001 (also known as IEEE Std
5934 1003.1-2001) is the latest standard, although a new version of POSIX is
5935 under development and includes several proposals for modifying what 'm4'
5936 is required to do.  The requirements for 'm4' are shared between SUSv3
5937 and POSIX, and can be viewed at
5938 <http://www.opengroup.org/onlinepubs/000095399/utilities/m4.html>.
5939
5940 * Menu:
5941
5942 * Extensions::                  Extensions in GNU M4
5943 * Incompatibilities::           Facilities in System V m4 not in GNU M4
5944 * Other Incompatibilities::     Other incompatibilities
5945
5946 \1f
5947 File: m4.info,  Node: Extensions,  Next: Incompatibilities,  Up: Compatibility
5948
5949 16.1 Extensions in GNU M4
5950 =========================
5951
5952 This version of 'm4' contains a few facilities that do not exist in
5953 System V 'm4'.  These extra facilities are all suppressed by using the
5954 '-G' command line option (*note Invoking m4: Limits control.), unless
5955 overridden by other command line options.
5956
5957    * In the '$N' notation for macro arguments, N can contain several
5958      digits, while the System V 'm4' only accepts one digit.  This
5959      allows macros in GNU 'm4' to take any number of arguments, and not
5960      only nine (*note Arguments::).
5961
5962      This means that 'define(`foo', `$11')' is ambiguous between
5963      implementations.  To portably choose between grabbing the first
5964      parameter and appending 1 to the expansion, or grabbing the
5965      eleventh parameter, you can do the following:
5966
5967           define(`a1', `A1')
5968           =>
5969           dnl First argument, concatenated with 1
5970           define(`_1', `$1')define(`first1', `_1($@)1')
5971           =>
5972           dnl Eleventh argument, portable
5973           define(`_9', `$9')define(`eleventh', `_9(shift(shift($@)))')
5974           =>
5975           dnl Eleventh argument, GNU style
5976           define(`Eleventh', `$11')
5977           =>
5978           first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
5979           =>A1
5980           eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
5981           =>k
5982           Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k')
5983           =>k
5984
5985      Also see the 'argn' macro (*note Shift::).
5986
5987    * The 'divert' (*note Divert::) macro can manage more than 9
5988      diversions.  GNU 'm4' treats all positive numbers as valid
5989      diversions, rather than discarding diversions greater than 9.
5990
5991    * Files included with 'include' and 'sinclude' are sought in a user
5992      specified search path, if they are not found in the working
5993      directory.  The search path is specified by the '-I' option and the
5994      'M4PATH' environment variable (*note Search Path::).
5995
5996    * Arguments to 'undivert' can be non-numeric, in which case the named
5997      file will be included uninterpreted in the output (*note
5998      Undivert::).
5999
6000    * Formatted output is supported through the 'format' builtin, which
6001      is modeled after the C library function 'printf' (*note Format::).
6002
6003    * Searches and text substitution through basic regular expressions
6004      are supported by the 'regexp' (*note Regexp::) and 'patsubst'
6005      (*note Patsubst::) builtins.  Some BSD implementations use extended
6006      regular expressions instead.
6007
6008    * The output of shell commands can be read into 'm4' with 'esyscmd'
6009      (*note Esyscmd::).
6010
6011    * There is indirect access to any builtin macro with 'builtin' (*note
6012      Builtin::).
6013
6014    * Macros can be called indirectly through 'indir' (*note Indir::).
6015
6016    * The name of the program, the current input file, and the current
6017      input line number are accessible through the builtins
6018      '__program__', '__file__', and '__line__' (*note Location::).
6019
6020    * The format of the output from 'dumpdef' and macro tracing can be
6021      controlled with 'debugmode' (*note Debug Levels::).
6022
6023    * The destination of trace and debug output can be controlled with
6024      'debugfile' (*note Debug Output::).
6025
6026    * The 'maketemp' (*note Mkstemp::) macro behaves like 'mkstemp',
6027      creating a new file with a unique name on every invocation, rather
6028      than following the insecure behavior of replacing the trailing 'X'
6029      characters with the 'm4' process id.
6030
6031    * POSIX only requires support for the command line options '-s',
6032      '-D', and '-U', so all other options accepted by GNU M4 are
6033      extensions.  *Note Invoking m4::, for a description of these
6034      options.
6035
6036      The debugging and tracing facilities in GNU 'm4' are much more
6037      extensive than in most other versions of 'm4'.
6038
6039 \1f
6040 File: m4.info,  Node: Incompatibilities,  Next: Other Incompatibilities,  Prev: Extensions,  Up: Compatibility
6041
6042 16.2 Facilities in System V 'm4' not in GNU 'm4'
6043 ================================================
6044
6045 The version of 'm4' from System V contains a few facilities that have
6046 not been implemented in GNU 'm4' yet.  Additionally, POSIX requires some
6047 behaviors that GNU 'm4' has not implemented yet.  Relying on these
6048 behaviors is non-portable, as a future release of GNU 'm4' may change.
6049
6050    * POSIX requires support for multiple arguments to 'defn', without
6051      any clarification on how 'defn' behaves when one of the multiple
6052      arguments names a builtin.  System V 'm4' and some other
6053      implementations allow mixing builtins and text macros into a single
6054      macro.  GNU 'm4' only supports joining multiple text arguments,
6055      although a future implementation may lift this restriction to
6056      behave more like System V.  The only portable way to join text
6057      macros with builtins is via helper macros and implicit
6058      concatenation of macro results.
6059
6060    * POSIX requires an application to exit with non-zero status if it
6061      wrote an error message to stderr.  This has not yet been
6062      consistently implemented for the various builtins that are required
6063      to issue an error (such as 'eval' (*note Eval::) when an argument
6064      cannot be parsed).
6065
6066    * Some traditional implementations only allow reading standard input
6067      once, but GNU 'm4' correctly handles multiple instances of '-' on
6068      the command line.
6069
6070    * POSIX requires 'm4wrap' (*note M4wrap::) to act in FIFO (first-in,
6071      first-out) order, but GNU 'm4' currently uses LIFO order.
6072      Furthermore, POSIX states that only the first argument to 'm4wrap'
6073      is saved for later evaluation, but GNU 'm4' saves and processes all
6074      arguments, with output separated by spaces.
6075
6076    * POSIX states that builtins that require arguments, but are called
6077      without arguments, have undefined behavior.  Traditional
6078      implementations simply behave as though empty strings had been
6079      passed.  For example, 'a`'define`'b' would expand to 'ab'.  But GNU
6080      'm4' ignores certain builtins if they have missing arguments,
6081      giving 'adefineb' for the above example.
6082
6083    * Traditional implementations handle 'define(`f',`1')' (*note
6084      Define::) by undefining the entire stack of previous definitions,
6085      and if doing 'undefine(`f')' first.  GNU 'm4' replaces just the top
6086      definition on the stack, as if doing 'popdef(`f')' followed by
6087      'pushdef(`f',`1')'.  POSIX allows either behavior.
6088
6089    * POSIX 2001 requires 'syscmd' (*note Syscmd::) to evaluate command
6090      output for macro expansion, but this was a mistake that is
6091      anticipated to be corrected in the next version of POSIX. GNU 'm4'
6092      follows traditional behavior in 'syscmd' where output is not
6093      rescanned, and provides the extension 'esyscmd' that does scan the
6094      output.
6095
6096    * At one point, POSIX required 'changequote(ARG)' (*note
6097      Changequote::) to use newline as the close quote, but this was a
6098      bug, and the next version of POSIX is anticipated to state that
6099      using empty strings or just one argument is unspecified.
6100      Meanwhile, the GNU 'm4' behavior of treating an empty end-quote
6101      delimiter as ''' is not portable, as Solaris treats it as repeating
6102      the start-quote delimiter, and BSD treats it as leaving the
6103      previous end-quote delimiter unchanged.  For predictable results,
6104      never call changequote with just one argument, or with empty
6105      strings for arguments.
6106
6107    * At one point, POSIX required 'changecom(ARG,)' (*note Changecom::)
6108      to make it impossible to end a comment, but this is a bug, and the
6109      next version of POSIX is anticipated to state that using empty
6110      strings is unspecified.  Meanwhile, the GNU 'm4' behavior of
6111      treating an empty end-comment delimiter as newline is not portable,
6112      as BSD treats it as leaving the previous end-comment delimiter
6113      unchanged.  It is also impossible in BSD implementations to disable
6114      comments, even though that is required by POSIX. For predictable
6115      results, never call changecom with empty strings for arguments.
6116
6117    * Most implementations of 'm4' give macros a higher precedence than
6118      comments when parsing, meaning that if the start delimiter given to
6119      'changecom' (*note Changecom::) starts with a macro name, comments
6120      are effectively disabled.  POSIX does not specify what the
6121      precedence is, so this version of GNU 'm4' parser recognizes
6122      comments, then macros, then quoted strings.
6123
6124    * Traditional implementations allow argument collection, but not
6125      string and comment processing, to span file boundaries.  Thus, if
6126      'a.m4' contains 'len(', and 'b.m4' contains 'abc)', 'm4 a.m4 b.m4'
6127      outputs '3' with traditional 'm4', but gives an error message that
6128      the end of file was encountered inside a macro with GNU 'm4'.  On
6129      the other hand, traditional implementations do end of file
6130      processing for files included with 'include' or 'sinclude' (*note
6131      Include::), while GNU 'm4' seamlessly integrates the content of
6132      those files.  Thus 'include(`a.m4')include(`b.m4')' will output '3'
6133      instead of giving an error.
6134
6135    * Traditional 'm4' treats 'traceon' (*note Trace::) without arguments
6136      as a global variable, independent of named macro tracing.  Also,
6137      once a macro is undefined, named tracing of that macro is lost.  On
6138      the other hand, when GNU 'm4' encounters 'traceon' without
6139      arguments, it turns tracing on for all existing definitions at the
6140      time, but does not trace future definitions; 'traceoff' without
6141      arguments turns tracing off for all definitions regardless of
6142      whether they were also traced by name; and tracing by name, such as
6143      with '-tfoo' at the command line or 'traceon(`foo')' in the input,
6144      is an attribute that is preserved even if the macro is currently
6145      undefined.
6146
6147      Additionally, while POSIX requires trace output, it makes no
6148      demands on the formatting of that output.  Parsing trace output is
6149      not guaranteed to be reliable, even between different releases of
6150      GNU M4; however, the intent is that any future changes in trace
6151      output will only occur under the direction of additional
6152      'debugmode' flags (*note Debug Levels::).
6153
6154    * POSIX requires 'eval' (*note Eval::) to treat all operators with
6155      the same precedence as C.  However, earlier versions of GNU 'm4'
6156      followed the traditional behavior of other 'm4' implementations,
6157      where bitwise and logical negation ('~' and '!') have lower
6158      precedence than equality operators; and where equality operators
6159      ('==' and '!=') had the same precedence as relational operators
6160      (such as '<').  Use explicit parentheses to ensure proper
6161      precedence.  As extensions to POSIX, GNU 'm4' gives well-defined
6162      semantics to operations that C leaves undefined, such as when
6163      overflow occurs, when shifting negative numbers, or when performing
6164      division by zero.  POSIX also requires '=' to cause an error, but
6165      many traditional implementations allowed it as an alias for '=='.
6166
6167    * POSIX 2001 requires 'translit' (*note Translit::) to treat each
6168      character of the second and third arguments literally.  However, it
6169      is anticipated that the next version of POSIX will allow the GNU
6170      'm4' behavior of treating '-' as a range operator.
6171
6172    * POSIX requires 'm4' to honor the locale environment variables of
6173      'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', and 'NLSPATH', but
6174      this has not yet been implemented in GNU 'm4'.
6175
6176    * POSIX states that only unquoted leading newlines and blanks (that
6177      is, space and tab) are ignored when collecting macro arguments.
6178      However, this appears to be a bug in POSIX, since most traditional
6179      implementations also ignore all whitespace (formfeed, carriage
6180      return, and vertical tab).  GNU 'm4' follows tradition and ignores
6181      all leading unquoted whitespace.
6182
6183    * A strictly-compliant POSIX client is not allowed to use
6184      command-line arguments not specified by POSIX. However, since this
6185      version of M4 ignores 'POSIXLY_CORRECT' and enables the option
6186      '--gnu' by default (*note Invoking m4: Limits control.), a client
6187      desiring to be strictly compliant has no way to disable GNU
6188      extensions that conflict with POSIX when directly invoking the
6189      compiled 'm4'.  A future version of 'GNU' M4 will honor the
6190      environment variable 'POSIXLY_CORRECT', implicitly enabling
6191      '--traditional' if it is set, in order to allow a
6192      strictly-compliant client.  In the meantime, a client needing
6193      strict POSIX compliance can use the workaround of invoking a shell
6194      script wrapper, where the wrapper then adds '--traditional' to the
6195      arguments passed to the compiled 'm4'.
6196
6197 \1f
6198 File: m4.info,  Node: Other Incompatibilities,  Prev: Incompatibilities,  Up: Compatibility
6199
6200 16.3 Other incompatibilities
6201 ============================
6202
6203 There are a few other incompatibilities between this implementation of
6204 'm4', and the System V version.
6205
6206    * GNU 'm4' implements sync lines differently from System V 'm4', when
6207      text is being diverted.  GNU 'm4' outputs the sync lines when the
6208      text is being diverted, and System V 'm4' when the diverted text is
6209      being brought back.
6210
6211      The problem is which lines and file names should be attached to
6212      text that is being, or has been, diverted.  System V 'm4' regards
6213      all the diverted text as being generated by the source line
6214      containing the 'undivert' call, whereas GNU 'm4' regards the
6215      diverted text as being generated at the time it is diverted.
6216
6217      The sync line option is used mostly when using 'm4' as a front end
6218      to a compiler.  If a diverted line causes a compiler error, the
6219      error messages should most probably refer to the place where the
6220      diversion was made, and not where it was inserted again.
6221
6222           divert(2)2
6223           divert(1)1
6224           divert`'0
6225           =>#line 3 "stdin"
6226           =>0
6227           ^D
6228           =>#line 2 "stdin"
6229           =>1
6230           =>#line 1 "stdin"
6231           =>2
6232
6233      The current 'm4' implementation has a limitation that the syncline
6234      output at the start of each diversion occurs no matter what, even
6235      if the previous diversion did not end with a newline.  This goes
6236      contrary to the claim that synclines appear on a line by
6237      themselves, so this limitation may be corrected in a future version
6238      of 'm4'.  In the meantime, when using '-s', it is wisest to make
6239      sure all diversions end with newline.
6240
6241    * GNU 'm4' makes no attempt at prohibiting self-referential
6242      definitions like:
6243
6244           define(`x', `x')
6245           =>
6246           define(`x', `x ')
6247           =>
6248
6249      There is nothing inherently wrong with defining 'x' to return 'x'.
6250      The wrong thing is to expand 'x' unquoted, because that would cause
6251      an infinite rescan loop.  In 'm4', one might use macros to hold
6252      strings, as we do for variables in other programming languages,
6253      further checking them with:
6254
6255           ifelse(defn(`HOLDER'), `VALUE', ...)
6256
6257      In cases like this one, an interdiction for a macro to hold its own
6258      name would be a useless limitation.  Of course, this leaves more
6259      rope for the GNU 'm4' user to hang himself!  Rescanning hangs may
6260      be avoided through careful programming, a little like for endless
6261      loops in traditional programming languages.
6262
6263 \1f
6264 File: m4.info,  Node: Answers,  Next: Copying This Package,  Prev: Compatibility,  Up: Top
6265
6266 17 Correct version of some examples
6267 ***********************************
6268
6269 Some of the examples in this manuals are buggy or not very robust, for
6270 demonstration purposes.  Improved versions of these composite macros are
6271 presented here.
6272
6273 * Menu:
6274
6275 * Improved exch::               Solution for 'exch'
6276 * Improved forloop::            Solution for 'forloop'
6277 * Improved foreach::            Solution for 'foreach'
6278 * Improved copy::               Solution for 'copy'
6279 * Improved m4wrap::             Solution for 'm4wrap'
6280 * Improved cleardivert::        Solution for 'cleardivert'
6281 * Improved capitalize::         Solution for 'capitalize'
6282 * Improved fatal_error::        Solution for 'fatal_error'
6283
6284 \1f
6285 File: m4.info,  Node: Improved exch,  Next: Improved forloop,  Up: Answers
6286
6287 17.1 Solution for 'exch'
6288 ========================
6289
6290 The 'exch' macro (*note Arguments::) as presented requires clients to
6291 double quote their arguments.  A nicer definition, which lets clients
6292 follow the rule of thumb of one level of quoting per level of
6293 parentheses, involves adding quotes in the definition of 'exch', as
6294 follows:
6295
6296      define(`exch', ``$2', `$1'')
6297      =>
6298      define(exch(`expansion text', `macro'))
6299      =>
6300      macro
6301      =>expansion text
6302
6303 \1f
6304 File: m4.info,  Node: Improved forloop,  Next: Improved foreach,  Prev: Improved exch,  Up: Answers
6305
6306 17.2 Solution for 'forloop'
6307 ===========================
6308
6309 The 'forloop' macro (*note Forloop::) as presented earlier can go into
6310 an infinite loop if given an iterator that is not parsed as a macro
6311 name.  It does not do any sanity checking on its numeric bounds, and
6312 only permits decimal numbers for bounds.  Here is an improved version,
6313 shipped as 'm4-1.4.18/examples/forloop2.m4'; this version also optimizes
6314 overhead by calling four macros instead of six per iteration (excluding
6315 those in TEXT), by not dereferencing the ITERATOR in the helper
6316 '_forloop'.
6317
6318      $ m4 -d -I examples
6319      undivert(`forloop2.m4')dnl
6320      =>divert(`-1')
6321      =># forloop(var, from, to, stmt) - improved version:
6322      =>#   works even if VAR is not a strict macro name
6323      =>#   performs sanity check that FROM is larger than TO
6324      =>#   allows complex numerical expressions in TO and FROM
6325      =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
6326      =>  `pushdef(`$1')_$0(`$1', eval(`$2'),
6327      =>    eval(`$3'), `$4')popdef(`$1')')')
6328      =>define(`_forloop',
6329      =>  `define(`$1', `$2')$4`'ifelse(`$2', `$3', `',
6330      =>    `$0(`$1', incr(`$2'), `$3', `$4')')')
6331      =>divert`'dnl
6332      include(`forloop2.m4')
6333      =>
6334      forloop(`i', `2', `1', `no iteration occurs')
6335      =>
6336      forloop(`', `1', `2', ` odd iterator name')
6337      => odd iterator name odd iterator name
6338      forloop(`i', `5 + 5', `0xc', ` 0x`'eval(i, `16')')
6339      => 0xa 0xb 0xc
6340      forloop(`i', `a', `b', `non-numeric bounds')
6341      error->m4:stdin:6: bad expression in eval (bad input): (a) <= (b)
6342      =>
6343
6344    One other change to notice is that the improved version used '_$0'
6345 rather than '_foreach' to invoke the helper routine.  In general, this
6346 is a good practice to follow, because then the set of macros can be
6347 uniformly transformed.  The following example shows a transformation
6348 that doubles the current quoting and appends a suffix '2' to each
6349 transformed macro.  If 'foreach' refers to the literal '_foreach', then
6350 'foreach2' invokes '_foreach' instead of the intended '_foreach2', and
6351 the mixing of quoting paradigms leads to an infinite recursion loop in
6352 this example.
6353
6354      $ m4 -d -L 9 -I examples
6355      define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4')
6356      =>
6357      define(`double', `define(`$1'`2',
6358        arg1(patsubst(dquote(defn(`$1')), `[`']', `\&\&')))')
6359      =>
6360      double(`forloop')double(`_forloop')defn(`forloop2')
6361      =>ifelse(eval(``($2) <= ($3)''), ``1'',
6362      =>  ``pushdef(``$1'')_$0(``$1'', eval(``$2''),
6363      =>    eval(``$3''), ``$4'')popdef(``$1'')'')
6364      forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
6365      =>
6366      changequote(`[', `]')changequote([``], [''])
6367      =>
6368      forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
6369      =>
6370      changequote`'include(`forloop.m4')
6371      =>
6372      double(`forloop')double(`_forloop')defn(`forloop2')
6373      =>pushdef(``$1'', ``$2'')_forloop($@)popdef(``$1'')
6374      forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)')
6375      =>
6376      changequote(`[', `]')changequote([``], [''])
6377      =>
6378      forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'')
6379      error->m4:stdin:12: recursion limit of 9 exceeded, use -L<N> to change it
6380
6381    One more optimization is still possible.  Instead of repeatedly
6382 assigning a variable then invoking or dereferencing it, it is possible
6383 to pass the current iterator value as a single argument.  Coupled with
6384 'curry' if other arguments are needed (*note Composition::), or with
6385 helper macros if the argument is needed in more than one place in the
6386 expansion, the output can be generated with three, rather than four,
6387 macros of overhead per iteration.  Notice how the file
6388 'm4-1.4.18/examples/forloop3.m4' rearranges the arguments of the helper
6389 '_forloop' to take two arguments that are placed around the current
6390 value.  By splitting a balanced set of parantheses across multiple
6391 arguments, the helper macro can now be shared by 'forloop' and the new
6392 'forloop_arg'.
6393
6394      $ m4 -I examples
6395      include(`forloop3.m4')
6396      =>
6397      undivert(`forloop3.m4')dnl
6398      =>divert(`-1')
6399      =># forloop_arg(from, to, macro) - invoke MACRO(value) for
6400      =>#   each value between FROM and TO, without define overhead
6401      =>define(`forloop_arg', `ifelse(eval(`($1) <= ($2)'), `1',
6402      =>  `_forloop(`$1', eval(`$2'), `$3(', `)')')')
6403      =># forloop(var, from, to, stmt) - refactored to share code
6404      =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1',
6405      =>  `pushdef(`$1')_forloop(eval(`$2'), eval(`$3'),
6406      =>    `define(`$1',', `)$4')popdef(`$1')')')
6407      =>define(`_forloop',
6408      =>  `$3`$1'$4`'ifelse(`$1', `$2', `',
6409      =>    `$0(incr(`$1'), `$2', `$3', `$4')')')
6410      =>divert`'dnl
6411      forloop(`i', `1', `3', ` i')
6412      => 1 2 3
6413      define(`echo', `$@')
6414      =>
6415      forloop_arg(`1', `3', ` echo')
6416      => 1 2 3
6417      include(`curry.m4')
6418      =>
6419      forloop_arg(`1', `3', `curry(`pushdef', `a')')
6420      =>
6421      a
6422      =>3
6423      popdef(`a')a
6424      =>2
6425      popdef(`a')a
6426      =>1
6427      popdef(`a')a
6428      =>a
6429
6430    Of course, it is possible to make even more improvements, such as
6431 adding an optional step argument, or allowing iteration through
6432 descending sequences.  GNU Autoconf provides some of these additional
6433 bells and whistles in its 'm4_for' macro.
6434
6435 \1f
6436 File: m4.info,  Node: Improved foreach,  Next: Improved copy,  Prev: Improved forloop,  Up: Answers
6437
6438 17.3 Solution for 'foreach'
6439 ===========================
6440
6441 The 'foreach' and 'foreachq' macros (*note Foreach::) as presented
6442 earlier each have flaws.  First, we will examine and fix the quadratic
6443 behavior of 'foreachq':
6444
6445      $ m4 -I examples
6446      include(`foreachq.m4')
6447      =>
6448      traceon(`shift')debugmode(`aq')
6449      =>
6450      foreachq(`x', ``1', `2', `3', `4'', `x
6451      ')dnl
6452      =>1
6453      error->m4trace: -3- shift(`1', `2', `3', `4')
6454      error->m4trace: -2- shift(`1', `2', `3', `4')
6455      =>2
6456      error->m4trace: -4- shift(`1', `2', `3', `4')
6457      error->m4trace: -3- shift(`2', `3', `4')
6458      error->m4trace: -3- shift(`1', `2', `3', `4')
6459      error->m4trace: -2- shift(`2', `3', `4')
6460      =>3
6461      error->m4trace: -5- shift(`1', `2', `3', `4')
6462      error->m4trace: -4- shift(`2', `3', `4')
6463      error->m4trace: -3- shift(`3', `4')
6464      error->m4trace: -4- shift(`1', `2', `3', `4')
6465      error->m4trace: -3- shift(`2', `3', `4')
6466      error->m4trace: -2- shift(`3', `4')
6467      =>4
6468      error->m4trace: -6- shift(`1', `2', `3', `4')
6469      error->m4trace: -5- shift(`2', `3', `4')
6470      error->m4trace: -4- shift(`3', `4')
6471      error->m4trace: -3- shift(`4')
6472
6473    Each successive iteration was adding more quoted 'shift' invocations,
6474 and the entire list contents were passing through every iteration.  In
6475 general, when recursing, it is a good idea to make the recursion use
6476 fewer arguments, rather than adding additional quoted uses of 'shift'.
6477 By doing so, 'm4' uses less memory, invokes fewer macros, is less likely
6478 to run into machine limits, and most importantly, performs faster.  The
6479 fixed version of 'foreachq' can be found in
6480 'm4-1.4.18/examples/foreachq2.m4':
6481
6482      $ m4 -I examples
6483      include(`foreachq2.m4')
6484      =>
6485      undivert(`foreachq2.m4')dnl
6486      =>include(`quote.m4')dnl
6487      =>divert(`-1')
6488      =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
6489      =>#   quoted list, improved version
6490      =>define(`foreachq', `pushdef(`$1')_$0($@)popdef(`$1')')
6491      =>define(`_arg1q', ``$1'')
6492      =>define(`_rest', `ifelse(`$#', `1', `', `dquote(shift($@))')')
6493      =>define(`_foreachq', `ifelse(`$2', `', `',
6494      =>  `define(`$1', _arg1q($2))$3`'$0(`$1', _rest($2), `$3')')')
6495      =>divert`'dnl
6496      traceon(`shift')debugmode(`aq')
6497      =>
6498      foreachq(`x', ``1', `2', `3', `4'', `x
6499      ')dnl
6500      =>1
6501      error->m4trace: -3- shift(`1', `2', `3', `4')
6502      =>2
6503      error->m4trace: -3- shift(`2', `3', `4')
6504      =>3
6505      error->m4trace: -3- shift(`3', `4')
6506      =>4
6507
6508    Note that the fixed version calls unquoted helper macros in
6509 '_foreachq' to trim elements immediately; those helper macros in turn
6510 must re-supply the layer of quotes lost in the macro invocation.
6511 Contrast the use of '_arg1q', which quotes the first list element, with
6512 '_arg1' of the earlier implementation that returned the first list
6513 element directly.  Additionally, by calling the helper method
6514 immediately, the 'defn(`ITERATOR')' no longer contains unexpanded
6515 macros.
6516
6517    The astute m4 programmer might notice that the solution above still
6518 uses more memory and macro invocations, and thus more time, than
6519 strictly necessary.  Note that '$2', which contains an arbitrarily long
6520 quoted list, is expanded and rescanned three times per iteration of
6521 '_foreachq'.  Furthermore, every iteration of the algorithm effectively
6522 unboxes then reboxes the list, which costs a couple of macro
6523 invocations.  It is possible to rewrite the algorithm for a bit more
6524 speed by swapping the order of the arguments to '_foreachq' in order to
6525 operate on an unboxed list in the first place, and by using the
6526 fixed-length '$#' instead of an arbitrary length list as the key to end
6527 recursion.  The result is an overhead of six macro invocations per loop
6528 (excluding any macros in TEXT), instead of eight.  This alternative
6529 approach is available as 'm4-1.4.18/examples/foreach3.m4':
6530
6531      $ m4 -I examples
6532      include(`foreachq3.m4')
6533      =>
6534      undivert(`foreachq3.m4')dnl
6535      =>divert(`-1')
6536      =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
6537      =>#   quoted list, alternate improved version
6538      =>define(`foreachq', `ifelse(`$2', `', `',
6539      =>  `pushdef(`$1')_$0(`$1', `$3', `', $2)popdef(`$1')')')
6540      =>define(`_foreachq', `ifelse(`$#', `3', `',
6541      =>  `define(`$1', `$4')$2`'$0(`$1', `$2',
6542      =>    shift(shift(shift($@))))')')
6543      =>divert`'dnl
6544      traceon(`shift')debugmode(`aq')
6545      =>
6546      foreachq(`x', ``1', `2', `3', `4'', `x
6547      ')dnl
6548      =>1
6549      error->m4trace: -4- shift(`x', `x
6550      error->', `', `1', `2', `3', `4')
6551      error->m4trace: -3- shift(`x
6552      error->', `', `1', `2', `3', `4')
6553      error->m4trace: -2- shift(`', `1', `2', `3', `4')
6554      =>2
6555      error->m4trace: -4- shift(`x', `x
6556      error->', `1', `2', `3', `4')
6557      error->m4trace: -3- shift(`x
6558      error->', `1', `2', `3', `4')
6559      error->m4trace: -2- shift(`1', `2', `3', `4')
6560      =>3
6561      error->m4trace: -4- shift(`x', `x
6562      error->', `2', `3', `4')
6563      error->m4trace: -3- shift(`x
6564      error->', `2', `3', `4')
6565      error->m4trace: -2- shift(`2', `3', `4')
6566      =>4
6567      error->m4trace: -4- shift(`x', `x
6568      error->', `3', `4')
6569      error->m4trace: -3- shift(`x
6570      error->', `3', `4')
6571      error->m4trace: -2- shift(`3', `4')
6572
6573    In the current version of M4, every instance of '$@' is rescanned as
6574 it is encountered.  Thus, the 'foreachq3.m4' alternative uses much less
6575 memory than 'foreachq2.m4', and executes as much as 10% faster, since
6576 each iteration encounters fewer '$@'.  However, the implementation of
6577 rescanning every byte in '$@' is quadratic in the number of bytes
6578 scanned (for example, making the broken version in 'foreachq.m4' cubic,
6579 rather than quadratic, in behavior).  A future release of M4 will
6580 improve the underlying implementation by reusing results of previous
6581 scans, so that both styles of 'foreachq' can become linear in the number
6582 of bytes scanned.  Notice how the implementation injects an empty
6583 argument prior to expanding '$2' within 'foreachq'; the helper macro
6584 '_foreachq' then ignores the third argument altogether, and ends
6585 recursion when there are three arguments left because there was nothing
6586 left to pass through 'shift'.  Thus, each iteration only needs one
6587 'ifelse', rather than the two conditionals used in the version from
6588 'foreachq2.m4'.
6589
6590    So far, all of the implementations of 'foreachq' presented have been
6591 quadratic with M4 1.4.x.  But 'forloop' is linear, because each
6592 iteration parses a constant amount of arguments.  So, it is possible to
6593 design a variant that uses 'forloop' to do the iteration, then uses '$@'
6594 only once at the end, giving a linear result even with older M4
6595 implementations.  This implementation relies on the GNU extension that
6596 '$10' expands to the tenth argument rather than the first argument
6597 concatenated with '0'.  The trick is to define an intermediate macro
6598 that repeats the text 'm4_define(`$1', `$N')$2`'', with 'n' set to
6599 successive integers corresponding to each argument.  The helper macro
6600 '_foreachq_' is needed in order to generate the literal sequences such
6601 as '$1' into the intermediate macro, rather than expanding them as the
6602 arguments of '_foreachq'.  With this approach, no 'shift' calls are even
6603 needed!  Even though there are seven macros of overhead per iteration
6604 instead of six in 'foreachq3.m4', the linear scaling is apparent at
6605 relatively small list sizes.  However, this approach will need
6606 adjustment when a future version of M4 follows POSIX by no longer
6607 treating '$10' as the tenth argument; the anticipation is that '${10}'
6608 can be used instead, although that alternative syntax is not yet
6609 supported.
6610
6611      $ m4 -I examples
6612      include(`foreachq4.m4')
6613      =>
6614      undivert(`foreachq4.m4')dnl
6615      =>include(`forloop2.m4')dnl
6616      =>divert(`-1')
6617      =># foreachq(x, `item_1, item_2, ..., item_n', stmt)
6618      =>#   quoted list, version based on forloop
6619      =>define(`foreachq',
6620      =>`ifelse(`$2', `', `', `_$0(`$1', `$3', $2)')')
6621      =>define(`_foreachq',
6622      =>`pushdef(`$1', forloop(`$1', `3', `$#',
6623      =>  `$0_(`1', `2', indir(`$1'))')`popdef(
6624      =>    `$1')')indir(`$1', $@)')
6625      =>define(`_foreachq_',
6626      =>``define(`$$1', `$$3')$$2`''')
6627      =>divert`'dnl
6628      traceon(`shift')debugmode(`aq')
6629      =>
6630      foreachq(`x', ``1', `2', `3', `4'', `x
6631      ')dnl
6632      =>1
6633      =>2
6634      =>3
6635      =>4
6636
6637    For yet another approach, the improved version of 'foreach',
6638 available in 'm4-1.4.18/examples/foreach2.m4', simply overquotes the
6639 arguments to '_foreach' to begin with, using 'dquote_elt'.  Then
6640 '_foreach' can just use '_arg1' to remove the extra layer of quoting
6641 that was added up front:
6642
6643      $ m4 -I examples
6644      include(`foreach2.m4')
6645      =>
6646      undivert(`foreach2.m4')dnl
6647      =>include(`quote.m4')dnl
6648      =>divert(`-1')
6649      =># foreach(x, (item_1, item_2, ..., item_n), stmt)
6650      =>#   parenthesized list, improved version
6651      =>define(`foreach', `pushdef(`$1')_$0(`$1',
6652      =>  (dquote(dquote_elt$2)), `$3')popdef(`$1')')
6653      =>define(`_arg1', `$1')
6654      =>define(`_foreach', `ifelse(`$2', `(`')', `',
6655      =>  `define(`$1', _arg1$2)$3`'$0(`$1', (dquote(shift$2)), `$3')')')
6656      =>divert`'dnl
6657      traceon(`shift')debugmode(`aq')
6658      =>
6659      foreach(`x', `(`1', `2', `3', `4')', `x
6660      ')dnl
6661      error->m4trace: -4- shift(`1', `2', `3', `4')
6662      error->m4trace: -4- shift(`2', `3', `4')
6663      error->m4trace: -4- shift(`3', `4')
6664      =>1
6665      error->m4trace: -3- shift(``1'', ``2'', ``3'', ``4'')
6666      =>2
6667      error->m4trace: -3- shift(``2'', ``3'', ``4'')
6668      =>3
6669      error->m4trace: -3- shift(``3'', ``4'')
6670      =>4
6671      error->m4trace: -3- shift(``4'')
6672
6673    It is likewise possible to write a variant of 'foreach' that performs
6674 in linear time on M4 1.4.x; the easiest method is probably writing a
6675 version of 'foreach' that unboxes its list, then invokes '_foreachq' as
6676 previously defined in 'foreachq4.m4'.
6677
6678    In summary, recursion over list elements is trickier than it appeared
6679 at first glance, but provides a powerful idiom within 'm4' processing.
6680 As a final demonstration, both list styles are now able to handle
6681 several scenarios that would wreak havoc on one or both of the original
6682 implementations.  This points out one other difference between the list
6683 styles.  'foreach' evaluates unquoted list elements only once, in
6684 preparation for calling '_foreach', similary for 'foreachq' as provided
6685 by 'foreachq3.m4' or 'foreachq4.m4'.  But 'foreachq', as provided by
6686 'foreachq2.m4', evaluates unquoted list elements twice while visiting
6687 the first list element, once in '_arg1q' and once in '_rest'.  When
6688 deciding which list style to use, one must take into account whether
6689 repeating the side effects of unquoted list elements will have any
6690 detrimental effects.
6691
6692      $ m4 -I examples
6693      include(`foreach2.m4')
6694      =>
6695      include(`foreachq2.m4')
6696      =>
6697      dnl 0-element list:
6698      foreach(`x', `', `<x>') / foreachq(`x', `', `<x>')
6699      => / 
6700      dnl 1-element list of empty element
6701      foreach(`x', `()', `<x>') / foreachq(`x', ``'', `<x>')
6702      =><> / <>
6703      dnl 2-element list of empty elements
6704      foreach(`x', `(`',`')', `<x>') / foreachq(`x', ``',`'', `<x>')
6705      =><><> / <><>
6706      dnl 1-element list of a comma
6707      foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', `<x>')
6708      =><,> / <,>
6709      dnl 2-element list of unbalanced parentheses
6710      foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>')
6711      =><(><)> / <(><)>
6712      define(`ab', `oops')dnl using defn(`iterator')
6713      foreach(`x', `(`a', `b')', `defn(`x')') /dnl
6714       foreachq(`x', ``a', `b'', `defn(`x')')
6715      =>ab / ab
6716      define(`active', `ACT, IVE')
6717      =>
6718      traceon(`active')
6719      =>
6720      dnl list of unquoted macros; expansion occurs before recursion
6721      foreach(`x', `(active, active)', `<x>
6722      ')dnl
6723      error->m4trace: -4- active -> `ACT, IVE'
6724      error->m4trace: -4- active -> `ACT, IVE'
6725      =><ACT>
6726      =><IVE>
6727      =><ACT>
6728      =><IVE>
6729      foreachq(`x', `active, active', `<x>
6730      ')dnl
6731      error->m4trace: -3- active -> `ACT, IVE'
6732      error->m4trace: -3- active -> `ACT, IVE'
6733      =><ACT>
6734      error->m4trace: -3- active -> `ACT, IVE'
6735      error->m4trace: -3- active -> `ACT, IVE'
6736      =><IVE>
6737      =><ACT>
6738      =><IVE>
6739      dnl list of quoted macros; expansion occurs during recursion
6740      foreach(`x', `(`active', `active')', `<x>
6741      ')dnl
6742      error->m4trace: -1- active -> `ACT, IVE'
6743      =><ACT, IVE>
6744      error->m4trace: -1- active -> `ACT, IVE'
6745      =><ACT, IVE>
6746      foreachq(`x', ``active', `active'', `<x>
6747      ')dnl
6748      error->m4trace: -1- active -> `ACT, IVE'
6749      =><ACT, IVE>
6750      error->m4trace: -1- active -> `ACT, IVE'
6751      =><ACT, IVE>
6752      dnl list of double-quoted macro names; no expansion
6753      foreach(`x', `(``active'', ``active'')', `<x>
6754      ')dnl
6755      =><active>
6756      =><active>
6757      foreachq(`x', ```active'', ``active''', `<x>
6758      ')dnl
6759      =><active>
6760      =><active>
6761
6762 \1f
6763 File: m4.info,  Node: Improved copy,  Next: Improved m4wrap,  Prev: Improved foreach,  Up: Answers
6764
6765 17.4 Solution for 'copy'
6766 ========================
6767
6768 The macro 'copy' presented above is unable to handle builtin tokens with
6769 M4 1.4.x, because it tries to pass the builtin token through the macro
6770 'curry', where it is silently flattened to an empty string (*note
6771 Composition::).  Rather than using the problematic 'curry' to work
6772 around the limitation that 'stack_foreach' expects to invoke a macro
6773 that takes exactly one argument, we can write a new macro that lets us
6774 form the exact two-argument 'pushdef' call sequence needed, so that we
6775 are no longer passing a builtin token through a text macro.
6776
6777  -- Composite: stack_foreach_sep (MACRO, PRE, POST, SEP)
6778  -- Composite: stack_foreach_sep_lifo (MACRO, PRE, POST, SEP)
6779      For each of the 'pushdef' definitions associated with MACRO, expand
6780      the sequence 'PRE`'definition`'POST'.  Additionally, expand SEP
6781      between definitions.  'stack_foreach_sep' visits the oldest
6782      definition first, while 'stack_foreach_sep_lifo' visits the current
6783      definition first.  The expansion may dereference MACRO, but should
6784      not modify it.  There are a few special macros, such as 'defn',
6785      which cannot be used as the MACRO parameter.
6786
6787    Note that 'stack_foreach(`MACRO', `ACTION')' is equivalent to
6788 'stack_foreach_sep(`MACRO', `ACTION(', `)')'.  By supplying explicit
6789 parentheses, split among the PRE and POST arguments to
6790 'stack_foreach_sep', it is now possible to construct macro calls with
6791 more than one argument, without passing builtin tokens through a macro
6792 call.  It is likewise possible to directly reference the stack
6793 definitions without a macro call, by leaving PRE and POST empty.  Thus,
6794 in addition to fixing 'copy' on builtin tokens, it also executes with
6795 fewer macro invocations.
6796
6797    The new macro also adds a separator that is only output after the
6798 first iteration of the helper '_stack_reverse_sep', implemented by
6799 prepending the original SEP to PRE and omitting a SEP argument in
6800 subsequent iterations.  Note that the empty string that separates SEP
6801 from PRE is provided as part of the fourth argument when originally
6802 calling '_stack_reverse_sep', and not by writing '$4`'$3' as the third
6803 argument in the recursive call; while the other approach would give the
6804 same output, it does so at the expense of increasing the argument size
6805 on each iteration of '_stack_reverse_sep', which results in quadratic
6806 instead of linear execution time.  The improved stack walking macros are
6807 available in 'm4-1.4.18/examples/stack_sep.m4':
6808
6809      $ m4 -I examples
6810      include(`stack_sep.m4')
6811      =>
6812      define(`copy', `ifdef(`$2', `errprint(`$2 already defined
6813      ')m4exit(`1')',
6814         `stack_foreach_sep(`$1', `pushdef(`$2',', `)')')')dnl
6815      pushdef(`a', `1')pushdef(`a', defn(`divnum'))
6816      =>
6817      copy(`a', `b')
6818      =>
6819      b
6820      =>0
6821      popdef(`b')
6822      =>
6823      b
6824      =>1
6825      pushdef(`c', `1')pushdef(`c', `2')
6826      =>
6827      stack_foreach_sep_lifo(`c', `', `', `, ')
6828      =>2, 1
6829      undivert(`stack_sep.m4')dnl
6830      =>divert(`-1')
6831      =># stack_foreach_sep(macro, pre, post, sep)
6832      =># Invoke PRE`'defn`'POST with a single argument of each definition
6833      =># from the definition stack of MACRO, starting with the oldest, and
6834      =># separated by SEP between definitions.
6835      =>define(`stack_foreach_sep',
6836      =>`_stack_reverse_sep(`$1', `tmp-$1')'dnl
6837      =>`_stack_reverse_sep(`tmp-$1', `$1', `$2`'defn(`$1')$3', `$4`'')')
6838      =># stack_foreach_sep_lifo(macro, pre, post, sep)
6839      =># Like stack_foreach_sep, but starting with the newest definition.
6840      =>define(`stack_foreach_sep_lifo',
6841      =>`_stack_reverse_sep(`$1', `tmp-$1', `$2`'defn(`$1')$3', `$4`'')'dnl
6842      =>`_stack_reverse_sep(`tmp-$1', `$1')')
6843      =>define(`_stack_reverse_sep',
6844      =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0(
6845      =>  `$1', `$2', `$4$3')')')
6846      =>divert`'dnl
6847
6848 \1f
6849 File: m4.info,  Node: Improved m4wrap,  Next: Improved cleardivert,  Prev: Improved copy,  Up: Answers
6850
6851 17.5 Solution for 'm4wrap'
6852 ==========================
6853
6854 The replacement 'm4wrap' versions presented above, designed to guarantee
6855 FIFO or LIFO order regardless of the underlying M4 implementation, share
6856 a bug when dealing with wrapped text that looks like parameter
6857 expansion.  Note how the invocation of 'm4wrapN' interprets these
6858 parameters, while using the builtin preserves them for their intended
6859 use.
6860
6861      $ m4 -I examples
6862      include(`wraplifo.m4')
6863      =>
6864      m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
6865      ')
6866      =>
6867      builtin(`m4wrap', ``'define(`bar', ``$0:'-$1-$*-$#-')bar(`a', `b')
6868      ')
6869      =>
6870      ^D
6871      =>bar:-a-a,b-2-
6872      =>m4wrap0:---0-
6873
6874    Additionally, the computation of '_m4wrap_level' and creation of
6875 multiple 'm4wrapN' placeholders in the original examples is more
6876 expensive in time and memory than strictly necessary.  Notice how the
6877 improved version grabs the wrapped text via 'defn' to avoid parameter
6878 expansion, then undefines '_m4wrap_text', before stripping a level of
6879 quotes with '_arg1' to expand the text.  That way, each level of
6880 wrapping reuses the single placeholder, which starts each nesting level
6881 in an undefined state.
6882
6883    Finally, it is worth emulating the GNU M4 extension of saving all
6884 arguments to 'm4wrap', separated by a space, rather than saving just the
6885 first argument.  This is done with the 'join' macro documented
6886 previously (*note Shift::).  The improved LIFO example is shipped as
6887 'm4-1.4.18/examples/wraplifo2.m4', and can easily be converted to a FIFO
6888 solution by swapping the adjacent invocations of 'joinall' and 'defn'.
6889
6890      $ m4 -I examples
6891      include(`wraplifo2.m4')
6892      =>
6893      undivert(`wraplifo2.m4')dnl
6894      =>dnl Redefine m4wrap to have LIFO semantics, improved example.
6895      =>include(`join.m4')dnl
6896      =>define(`_m4wrap', defn(`m4wrap'))dnl
6897      =>define(`_arg1', `$1')dnl
6898      =>define(`m4wrap',
6899      =>`ifdef(`_$0_text',
6900      =>       `define(`_$0_text', joinall(` ', $@)defn(`_$0_text'))',
6901      =>       `_$0(`_arg1(defn(`_$0_text')undefine(`_$0_text'))')dnl
6902      =>define(`_$0_text', joinall(` ', $@))')')dnl
6903      m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b')
6904      ')
6905      =>
6906      m4wrap(`lifo text
6907      m4wrap(`nested', `', `$@
6908      ')')
6909      =>
6910      ^D
6911      =>lifo text
6912      =>foo:-a-a,b-2-
6913      =>nested  $@
6914
6915 \1f
6916 File: m4.info,  Node: Improved cleardivert,  Next: Improved capitalize,  Prev: Improved m4wrap,  Up: Answers
6917
6918 17.6 Solution for 'cleardivert'
6919 ===============================
6920
6921 The 'cleardivert' macro (*note Cleardivert::) cannot, as it stands, be
6922 called without arguments to clear all pending diversions.  That is
6923 because using undivert with an empty string for an argument is different
6924 than using it with no arguments at all.  Compare the earlier definition
6925 with one that takes the number of arguments into account:
6926
6927      define(`cleardivert',
6928        `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')')
6929      =>
6930      divert(`1')one
6931      divert
6932      =>
6933      cleardivert
6934      =>
6935      undivert
6936      =>one
6937      =>
6938      define(`cleardivert',
6939        `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0',
6940          `undivert`'', `undivert($@)')divert(_num)popdef(`_num')')
6941      =>
6942      divert(`2')two
6943      divert
6944      =>
6945      cleardivert
6946      =>
6947      undivert
6948      =>
6949
6950 \1f
6951 File: m4.info,  Node: Improved capitalize,  Next: Improved fatal_error,  Prev: Improved cleardivert,  Up: Answers
6952
6953 17.7 Solution for 'capitalize'
6954 ==============================
6955
6956 The 'capitalize' macro (*note Patsubst::) as presented earlier does not
6957 allow clients to follow the quoting rule of thumb.  Consider the three
6958 macros 'active', 'Active', and 'ACTIVE', and the difference between
6959 calling 'capitalize' with the expansion of a macro, expanding the result
6960 of a case change, and changing the case of a double-quoted string:
6961
6962      $ m4 -I examples
6963      include(`capitalize.m4')dnl
6964      define(`active', `act1, ive')dnl
6965      define(`Active', `Act2, Ive')dnl
6966      define(`ACTIVE', `ACT3, IVE')dnl
6967      upcase(active)
6968      =>ACT1,IVE
6969      upcase(`active')
6970      =>ACT3, IVE
6971      upcase(``active'')
6972      =>ACTIVE
6973      downcase(ACTIVE)
6974      =>act3,ive
6975      downcase(`ACTIVE')
6976      =>act1, ive
6977      downcase(``ACTIVE'')
6978      =>active
6979      capitalize(active)
6980      =>Act1
6981      capitalize(`active')
6982      =>Active
6983      capitalize(``active'')
6984      =>_capitalize(`active')
6985      define(`A', `OOPS')
6986      =>
6987      capitalize(active)
6988      =>OOPSct1
6989      capitalize(`active')
6990      =>OOPSctive
6991
6992    First, when 'capitalize' is called with more than one argument, it
6993 was throwing away later arguments, whereas 'upcase' and 'downcase' used
6994 '$*' to collect them all.  The fix is simple: use '$*' consistently.
6995
6996    Next, with single-quoting, 'capitalize' outputs a single character, a
6997 set of quotes, then the rest of the characters, making it impossible to
6998 invoke 'Active' after the fact, and allowing the alternate macro 'A' to
6999 interfere.  Here, the solution is to use additional quoting in the
7000 helper macros, then pass the final over-quoted output string through
7001 '_arg1' to remove the extra quoting and finally invoke the concatenated
7002 portions as a single string.
7003
7004    Finally, when passed a double-quoted string, the nested macro
7005 '_capitalize' is never invoked because it ended up nested inside quotes.
7006 This one is the toughest to fix.  In short, we have no idea how many
7007 levels of quotes are in effect on the substring being altered by
7008 'patsubst'.  If the replacement string cannot be expressed entirely in
7009 terms of literal text and backslash substitutions, then we need a
7010 mechanism to guarantee that the helper macros are invoked outside of
7011 quotes.  In other words, this sounds like a job for 'changequote' (*note
7012 Changequote::).  By changing the active quoting characters, we can
7013 guarantee that replacement text injected by 'patsubst' always occurs in
7014 the middle of a string that has exactly one level of over-quoting using
7015 alternate quotes; so the replacement text closes the quoted string,
7016 invokes the helper macros, then reopens the quoted string.  In turn,
7017 that means the replacement text has unbalanced quotes, necessitating
7018 another round of 'changequote'.
7019
7020    In the fixed version below, (also shipped as
7021 'm4-1.4.18/examples/capitalize2.m4'), 'capitalize' uses the alternate
7022 quotes of '<<[' and ']>>' (the longer strings are chosen so as to be
7023 less likely to appear in the text being converted).  The helpers
7024 '_to_alt' and '_from_alt' merely reduce the number of characters
7025 required to perform a 'changequote', since the definition changes twice.
7026 The outermost pair means that 'patsubst' and '_capitalize_alt' are
7027 invoked with alternate quoting; the innermost pair is used so that the
7028 third argument to 'patsubst' can contain an unbalanced ']>>'/'<<[' pair.
7029 Note that 'upcase' and 'downcase' must be redefined as '_upcase_alt' and
7030 '_downcase_alt', since they contain nested quotes but are invoked with
7031 the alternate quoting scheme in effect.
7032
7033      $ m4 -I examples
7034      include(`capitalize2.m4')dnl
7035      define(`active', `act1, ive')dnl
7036      define(`Active', `Act2, Ive')dnl
7037      define(`ACTIVE', `ACT3, IVE')dnl
7038      define(`A', `OOPS')dnl
7039      capitalize(active; `active'; ``active''; ```actIVE''')
7040      =>Act1,Ive; Act2, Ive; Active; `Active'
7041      undivert(`capitalize2.m4')dnl
7042      =>divert(`-1')
7043      =># upcase(text)
7044      =># downcase(text)
7045      =># capitalize(text)
7046      =>#   change case of text, improved version
7047      =>define(`upcase', `translit(`$*', `a-z', `A-Z')')
7048      =>define(`downcase', `translit(`$*', `A-Z', `a-z')')
7049      =>define(`_arg1', `$1')
7050      =>define(`_to_alt', `changequote(`<<[', `]>>')')
7051      =>define(`_from_alt', `changequote(<<[`]>>, <<[']>>)')
7052      =>define(`_upcase_alt', `translit(<<[$*]>>, <<[a-z]>>, <<[A-Z]>>)')
7053      =>define(`_downcase_alt', `translit(<<[$*]>>, <<[A-Z]>>, <<[a-z]>>)')
7054      =>define(`_capitalize_alt',
7055      =>  `regexp(<<[$1]>>, <<[^\(\w\)\(\w*\)]>>,
7056      =>    <<[_upcase_alt(<<[<<[\1]>>]>>)_downcase_alt(<<[<<[\2]>>]>>)]>>)')
7057      =>define(`capitalize',
7058      =>  `_arg1(_to_alt()patsubst(<<[<<[$*]>>]>>, <<[\w+]>>,
7059      =>    _from_alt()`]>>_$0_alt(<<[\&]>>)<<['_to_alt())_from_alt())')
7060      =>divert`'dnl
7061
7062 \1f
7063 File: m4.info,  Node: Improved fatal_error,  Prev: Improved capitalize,  Up: Answers
7064
7065 17.8 Solution for 'fatal_error'
7066 ===============================
7067
7068 The 'fatal_error' macro (*note M4exit::) is not robust to versions of
7069 GNU M4 earlier than 1.4.8, where invoking '__file__' (*note Location::)
7070 inside 'm4wrap' would result in an empty string, and '__line__' resulted
7071 in '0' even though all files start at line 1.  Furthermore, versions
7072 earlier than 1.4.6 did not support the '__program__' macro.  If you want
7073 'fatal_error' to work across the entire 1.4.x release series, a better
7074 implementation would be:
7075
7076      define(`fatal_error',
7077        `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl
7078      `:ifelse(__line__, `0', `',
7079          `__file__:__line__:')` fatal error: $*
7080      ')m4exit(`1')')
7081      =>
7082      m4wrap(`divnum(`demo of internal message')
7083      fatal_error(`inside wrapped text')')
7084      =>
7085      ^D
7086      error->m4:stdin:6: Warning: excess arguments to builtin `divnum' ignored
7087      =>0
7088      error->m4:stdin:6: fatal error: inside wrapped text
7089
7090 \1f
7091 File: m4.info,  Node: Copying This Package,  Next: Copying This Manual,  Prev: Answers,  Up: Top
7092
7093 Appendix A How to make copies of the overall M4 package
7094 *******************************************************
7095
7096 This appendix covers the license for copying the source code of the
7097 overall M4 package.  This manual is under a different set of
7098 restrictions, covered later (*note Copying This Manual::).
7099
7100 * Menu:
7101
7102 * GNU General Public License::  License for copying the M4 package
7103
7104 \1f
7105 File: m4.info,  Node: GNU General Public License,  Up: Copying This Package
7106
7107 A.1 License for copying the M4 package
7108 ======================================
7109
7110                         Version 3, 29 June 2007
7111
7112      Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
7113
7114      Everyone is permitted to copy and distribute verbatim copies of this
7115      license document, but changing it is not allowed.
7116
7117 Preamble
7118 ========
7119
7120 The GNU General Public License is a free, copyleft license for software
7121 and other kinds of works.
7122
7123    The licenses for most software and other practical works are designed
7124 to take away your freedom to share and change the works.  By contrast,
7125 the GNU General Public License is intended to guarantee your freedom to
7126 share and change all versions of a program--to make sure it remains free
7127 software for all its users.  We, the Free Software Foundation, use the
7128 GNU General Public License for most of our software; it applies also to
7129 any other work released this way by its authors.  You can apply it to
7130 your programs, too.
7131
7132    When we speak of free software, we are referring to freedom, not
7133 price.  Our General Public Licenses are designed to make sure that you
7134 have the freedom to distribute copies of free software (and charge for
7135 them if you wish), that you receive source code or can get it if you
7136 want it, that you can change the software or use pieces of it in new
7137 free programs, and that you know you can do these things.
7138
7139    To protect your rights, we need to prevent others from denying you
7140 these rights or asking you to surrender the rights.  Therefore, you have
7141 certain responsibilities if you distribute copies of the software, or if
7142 you modify it: responsibilities to respect the freedom of others.
7143
7144    For example, if you distribute copies of such a program, whether
7145 gratis or for a fee, you must pass on to the recipients the same
7146 freedoms that you received.  You must make sure that they, too, receive
7147 or can get the source code.  And you must show them these terms so they
7148 know their rights.
7149
7150    Developers that use the GNU GPL protect your rights with two steps:
7151 (1) assert copyright on the software, and (2) offer you this License
7152 giving you legal permission to copy, distribute and/or modify it.
7153
7154    For the developers' and authors' protection, the GPL clearly explains
7155 that there is no warranty for this free software.  For both users' and
7156 authors' sake, the GPL requires that modified versions be marked as
7157 changed, so that their problems will not be attributed erroneously to
7158 authors of previous versions.
7159
7160    Some devices are designed to deny users access to install or run
7161 modified versions of the software inside them, although the manufacturer
7162 can do so.  This is fundamentally incompatible with the aim of
7163 protecting users' freedom to change the software.  The systematic
7164 pattern of such abuse occurs in the area of products for individuals to
7165 use, which is precisely where it is most unacceptable.  Therefore, we
7166 have designed this version of the GPL to prohibit the practice for those
7167 products.  If such problems arise substantially in other domains, we
7168 stand ready to extend this provision to those domains in future versions
7169 of the GPL, as needed to protect the freedom of users.
7170
7171    Finally, every program is threatened constantly by software patents.
7172 States should not allow patents to restrict development and use of
7173 software on general-purpose computers, but in those that do, we wish to
7174 avoid the special danger that patents applied to a free program could
7175 make it effectively proprietary.  To prevent this, the GPL assures that
7176 patents cannot be used to render the program non-free.
7177
7178    The precise terms and conditions for copying, distribution and
7179 modification follow.
7180
7181 TERMS AND CONDITIONS
7182 ====================
7183
7184   0. Definitions.
7185
7186      "This License" refers to version 3 of the GNU General Public
7187      License.
7188
7189      "Copyright" also means copyright-like laws that apply to other
7190      kinds of works, such as semiconductor masks.
7191
7192      "The Program" refers to any copyrightable work licensed under this
7193      License.  Each licensee is addressed as "you".  "Licensees" and
7194      "recipients" may be individuals or organizations.
7195
7196      To "modify" a work means to copy from or adapt all or part of the
7197      work in a fashion requiring copyright permission, other than the
7198      making of an exact copy.  The resulting work is called a "modified
7199      version" of the earlier work or a work "based on" the earlier work.
7200
7201      A "covered work" means either the unmodified Program or a work
7202      based on the Program.
7203
7204      To "propagate" a work means to do anything with it that, without
7205      permission, would make you directly or secondarily liable for
7206      infringement under applicable copyright law, except executing it on
7207      a computer or modifying a private copy.  Propagation includes
7208      copying, distribution (with or without modification), making
7209      available to the public, and in some countries other activities as
7210      well.
7211
7212      To "convey" a work means any kind of propagation that enables other
7213      parties to make or receive copies.  Mere interaction with a user
7214      through a computer network, with no transfer of a copy, is not
7215      conveying.
7216
7217      An interactive user interface displays "Appropriate Legal Notices"
7218      to the extent that it includes a convenient and prominently visible
7219      feature that (1) displays an appropriate copyright notice, and (2)
7220      tells the user that there is no warranty for the work (except to
7221      the extent that warranties are provided), that licensees may convey
7222      the work under this License, and how to view a copy of this
7223      License.  If the interface presents a list of user commands or
7224      options, such as a menu, a prominent item in the list meets this
7225      criterion.
7226
7227   1. Source Code.
7228
7229      The "source code" for a work means the preferred form of the work
7230      for making modifications to it.  "Object code" means any non-source
7231      form of a work.
7232
7233      A "Standard Interface" means an interface that either is an
7234      official standard defined by a recognized standards body, or, in
7235      the case of interfaces specified for a particular programming
7236      language, one that is widely used among developers working in that
7237      language.
7238
7239      The "System Libraries" of an executable work include anything,
7240      other than the work as a whole, that (a) is included in the normal
7241      form of packaging a Major Component, but which is not part of that
7242      Major Component, and (b) serves only to enable use of the work with
7243      that Major Component, or to implement a Standard Interface for
7244      which an implementation is available to the public in source code
7245      form.  A "Major Component", in this context, means a major
7246      essential component (kernel, window system, and so on) of the
7247      specific operating system (if any) on which the executable work
7248      runs, or a compiler used to produce the work, or an object code
7249      interpreter used to run it.
7250
7251      The "Corresponding Source" for a work in object code form means all
7252      the source code needed to generate, install, and (for an executable
7253      work) run the object code and to modify the work, including scripts
7254      to control those activities.  However, it does not include the
7255      work's System Libraries, or general-purpose tools or generally
7256      available free programs which are used unmodified in performing
7257      those activities but which are not part of the work.  For example,
7258      Corresponding Source includes interface definition files associated
7259      with source files for the work, and the source code for shared
7260      libraries and dynamically linked subprograms that the work is
7261      specifically designed to require, such as by intimate data
7262      communication or control flow between those subprograms and other
7263      parts of the work.
7264
7265      The Corresponding Source need not include anything that users can
7266      regenerate automatically from other parts of the Corresponding
7267      Source.
7268
7269      The Corresponding Source for a work in source code form is that
7270      same work.
7271
7272   2. Basic Permissions.
7273
7274      All rights granted under this License are granted for the term of
7275      copyright on the Program, and are irrevocable provided the stated
7276      conditions are met.  This License explicitly affirms your unlimited
7277      permission to run the unmodified Program.  The output from running
7278      a covered work is covered by this License only if the output, given
7279      its content, constitutes a covered work.  This License acknowledges
7280      your rights of fair use or other equivalent, as provided by
7281      copyright law.
7282
7283      You may make, run and propagate covered works that you do not
7284      convey, without conditions so long as your license otherwise
7285      remains in force.  You may convey covered works to others for the
7286      sole purpose of having them make modifications exclusively for you,
7287      or provide you with facilities for running those works, provided
7288      that you comply with the terms of this License in conveying all
7289      material for which you do not control copyright.  Those thus making
7290      or running the covered works for you must do so exclusively on your
7291      behalf, under your direction and control, on terms that prohibit
7292      them from making any copies of your copyrighted material outside
7293      their relationship with you.
7294
7295      Conveying under any other circumstances is permitted solely under
7296      the conditions stated below.  Sublicensing is not allowed; section
7297      10 makes it unnecessary.
7298
7299   3. Protecting Users' Legal Rights From Anti-Circumvention Law.
7300
7301      No covered work shall be deemed part of an effective technological
7302      measure under any applicable law fulfilling obligations under
7303      article 11 of the WIPO copyright treaty adopted on 20 December
7304      1996, or similar laws prohibiting or restricting circumvention of
7305      such measures.
7306
7307      When you convey a covered work, you waive any legal power to forbid
7308      circumvention of technological measures to the extent such
7309      circumvention is effected by exercising rights under this License
7310      with respect to the covered work, and you disclaim any intention to
7311      limit operation or modification of the work as a means of
7312      enforcing, against the work's users, your or third parties' legal
7313      rights to forbid circumvention of technological measures.
7314
7315   4. Conveying Verbatim Copies.
7316
7317      You may convey verbatim copies of the Program's source code as you
7318      receive it, in any medium, provided that you conspicuously and
7319      appropriately publish on each copy an appropriate copyright notice;
7320      keep intact all notices stating that this License and any
7321      non-permissive terms added in accord with section 7 apply to the
7322      code; keep intact all notices of the absence of any warranty; and
7323      give all recipients a copy of this License along with the Program.
7324
7325      You may charge any price or no price for each copy that you convey,
7326      and you may offer support or warranty protection for a fee.
7327
7328   5. Conveying Modified Source Versions.
7329
7330      You may convey a work based on the Program, or the modifications to
7331      produce it from the Program, in the form of source code under the
7332      terms of section 4, provided that you also meet all of these
7333      conditions:
7334
7335        a. The work must carry prominent notices stating that you
7336           modified it, and giving a relevant date.
7337
7338        b. The work must carry prominent notices stating that it is
7339           released under this License and any conditions added under
7340           section 7.  This requirement modifies the requirement in
7341           section 4 to "keep intact all notices".
7342
7343        c. You must license the entire work, as a whole, under this
7344           License to anyone who comes into possession of a copy.  This
7345           License will therefore apply, along with any applicable
7346           section 7 additional terms, to the whole of the work, and all
7347           its parts, regardless of how they are packaged.  This License
7348           gives no permission to license the work in any other way, but
7349           it does not invalidate such permission if you have separately
7350           received it.
7351
7352        d. If the work has interactive user interfaces, each must display
7353           Appropriate Legal Notices; however, if the Program has
7354           interactive interfaces that do not display Appropriate Legal
7355           Notices, your work need not make them do so.
7356
7357      A compilation of a covered work with other separate and independent
7358      works, which are not by their nature extensions of the covered
7359      work, and which are not combined with it such as to form a larger
7360      program, in or on a volume of a storage or distribution medium, is
7361      called an "aggregate" if the compilation and its resulting
7362      copyright are not used to limit the access or legal rights of the
7363      compilation's users beyond what the individual works permit.
7364      Inclusion of a covered work in an aggregate does not cause this
7365      License to apply to the other parts of the aggregate.
7366
7367   6. Conveying Non-Source Forms.
7368
7369      You may convey a covered work in object code form under the terms
7370      of sections 4 and 5, provided that you also convey the
7371      machine-readable Corresponding Source under the terms of this
7372      License, in one of these ways:
7373
7374        a. Convey the object code in, or embodied in, a physical product
7375           (including a physical distribution medium), accompanied by the
7376           Corresponding Source fixed on a durable physical medium
7377           customarily used for software interchange.
7378
7379        b. Convey the object code in, or embodied in, a physical product
7380           (including a physical distribution medium), accompanied by a
7381           written offer, valid for at least three years and valid for as
7382           long as you offer spare parts or customer support for that
7383           product model, to give anyone who possesses the object code
7384           either (1) a copy of the Corresponding Source for all the
7385           software in the product that is covered by this License, on a
7386           durable physical medium customarily used for software
7387           interchange, for a price no more than your reasonable cost of
7388           physically performing this conveying of source, or (2) access
7389           to copy the Corresponding Source from a network server at no
7390           charge.
7391
7392        c. Convey individual copies of the object code with a copy of the
7393           written offer to provide the Corresponding Source.  This
7394           alternative is allowed only occasionally and noncommercially,
7395           and only if you received the object code with such an offer,
7396           in accord with subsection 6b.
7397
7398        d. Convey the object code by offering access from a designated
7399           place (gratis or for a charge), and offer equivalent access to
7400           the Corresponding Source in the same way through the same
7401           place at no further charge.  You need not require recipients
7402           to copy the Corresponding Source along with the object code.
7403           If the place to copy the object code is a network server, the
7404           Corresponding Source may be on a different server (operated by
7405           you or a third party) that supports equivalent copying
7406           facilities, provided you maintain clear directions next to the
7407           object code saying where to find the Corresponding Source.
7408           Regardless of what server hosts the Corresponding Source, you
7409           remain obligated to ensure that it is available for as long as
7410           needed to satisfy these requirements.
7411
7412        e. Convey the object code using peer-to-peer transmission,
7413           provided you inform other peers where the object code and
7414           Corresponding Source of the work are being offered to the
7415           general public at no charge under subsection 6d.
7416
7417      A separable portion of the object code, whose source code is
7418      excluded from the Corresponding Source as a System Library, need
7419      not be included in conveying the object code work.
7420
7421      A "User Product" is either (1) a "consumer product", which means
7422      any tangible personal property which is normally used for personal,
7423      family, or household purposes, or (2) anything designed or sold for
7424      incorporation into a dwelling.  In determining whether a product is
7425      a consumer product, doubtful cases shall be resolved in favor of
7426      coverage.  For a particular product received by a particular user,
7427      "normally used" refers to a typical or common use of that class of
7428      product, regardless of the status of the particular user or of the
7429      way in which the particular user actually uses, or expects or is
7430      expected to use, the product.  A product is a consumer product
7431      regardless of whether the product has substantial commercial,
7432      industrial or non-consumer uses, unless such uses represent the
7433      only significant mode of use of the product.
7434
7435      "Installation Information" for a User Product means any methods,
7436      procedures, authorization keys, or other information required to
7437      install and execute modified versions of a covered work in that
7438      User Product from a modified version of its Corresponding Source.
7439      The information must suffice to ensure that the continued
7440      functioning of the modified object code is in no case prevented or
7441      interfered with solely because modification has been made.
7442
7443      If you convey an object code work under this section in, or with,
7444      or specifically for use in, a User Product, and the conveying
7445      occurs as part of a transaction in which the right of possession
7446      and use of the User Product is transferred to the recipient in
7447      perpetuity or for a fixed term (regardless of how the transaction
7448      is characterized), the Corresponding Source conveyed under this
7449      section must be accompanied by the Installation Information.  But
7450      this requirement does not apply if neither you nor any third party
7451      retains the ability to install modified object code on the User
7452      Product (for example, the work has been installed in ROM).
7453
7454      The requirement to provide Installation Information does not
7455      include a requirement to continue to provide support service,
7456      warranty, or updates for a work that has been modified or installed
7457      by the recipient, or for the User Product in which it has been
7458      modified or installed.  Access to a network may be denied when the
7459      modification itself materially and adversely affects the operation
7460      of the network or violates the rules and protocols for
7461      communication across the network.
7462
7463      Corresponding Source conveyed, and Installation Information
7464      provided, in accord with this section must be in a format that is
7465      publicly documented (and with an implementation available to the
7466      public in source code form), and must require no special password
7467      or key for unpacking, reading or copying.
7468
7469   7. Additional Terms.
7470
7471      "Additional permissions" are terms that supplement the terms of
7472      this License by making exceptions from one or more of its
7473      conditions.  Additional permissions that are applicable to the
7474      entire Program shall be treated as though they were included in
7475      this License, to the extent that they are valid under applicable
7476      law.  If additional permissions apply only to part of the Program,
7477      that part may be used separately under those permissions, but the
7478      entire Program remains governed by this License without regard to
7479      the additional permissions.
7480
7481      When you convey a copy of a covered work, you may at your option
7482      remove any additional permissions from that copy, or from any part
7483      of it.  (Additional permissions may be written to require their own
7484      removal in certain cases when you modify the work.)  You may place
7485      additional permissions on material, added by you to a covered work,
7486      for which you have or can give appropriate copyright permission.
7487
7488      Notwithstanding any other provision of this License, for material
7489      you add to a covered work, you may (if authorized by the copyright
7490      holders of that material) supplement the terms of this License with
7491      terms:
7492
7493        a. Disclaiming warranty or limiting liability differently from
7494           the terms of sections 15 and 16 of this License; or
7495
7496        b. Requiring preservation of specified reasonable legal notices
7497           or author attributions in that material or in the Appropriate
7498           Legal Notices displayed by works containing it; or
7499
7500        c. Prohibiting misrepresentation of the origin of that material,
7501           or requiring that modified versions of such material be marked
7502           in reasonable ways as different from the original version; or
7503
7504        d. Limiting the use for publicity purposes of names of licensors
7505           or authors of the material; or
7506
7507        e. Declining to grant rights under trademark law for use of some
7508           trade names, trademarks, or service marks; or
7509
7510        f. Requiring indemnification of licensors and authors of that
7511           material by anyone who conveys the material (or modified
7512           versions of it) with contractual assumptions of liability to
7513           the recipient, for any liability that these contractual
7514           assumptions directly impose on those licensors and authors.
7515
7516      All other non-permissive additional terms are considered "further
7517      restrictions" within the meaning of section 10.  If the Program as
7518      you received it, or any part of it, contains a notice stating that
7519      it is governed by this License along with a term that is a further
7520      restriction, you may remove that term.  If a license document
7521      contains a further restriction but permits relicensing or conveying
7522      under this License, you may add to a covered work material governed
7523      by the terms of that license document, provided that the further
7524      restriction does not survive such relicensing or conveying.
7525
7526      If you add terms to a covered work in accord with this section, you
7527      must place, in the relevant source files, a statement of the
7528      additional terms that apply to those files, or a notice indicating
7529      where to find the applicable terms.
7530
7531      Additional terms, permissive or non-permissive, may be stated in
7532      the form of a separately written license, or stated as exceptions;
7533      the above requirements apply either way.
7534
7535   8. Termination.
7536
7537      You may not propagate or modify a covered work except as expressly
7538      provided under this License.  Any attempt otherwise to propagate or
7539      modify it is void, and will automatically terminate your rights
7540      under this License (including any patent licenses granted under the
7541      third paragraph of section 11).
7542
7543      However, if you cease all violation of this License, then your
7544      license from a particular copyright holder is reinstated (a)
7545      provisionally, unless and until the copyright holder explicitly and
7546      finally terminates your license, and (b) permanently, if the
7547      copyright holder fails to notify you of the violation by some
7548      reasonable means prior to 60 days after the cessation.
7549
7550      Moreover, your license from a particular copyright holder is
7551      reinstated permanently if the copyright holder notifies you of the
7552      violation by some reasonable means, this is the first time you have
7553      received notice of violation of this License (for any work) from
7554      that copyright holder, and you cure the violation prior to 30 days
7555      after your receipt of the notice.
7556
7557      Termination of your rights under this section does not terminate
7558      the licenses of parties who have received copies or rights from you
7559      under this License.  If your rights have been terminated and not
7560      permanently reinstated, you do not qualify to receive new licenses
7561      for the same material under section 10.
7562
7563   9. Acceptance Not Required for Having Copies.
7564
7565      You are not required to accept this License in order to receive or
7566      run a copy of the Program.  Ancillary propagation of a covered work
7567      occurring solely as a consequence of using peer-to-peer
7568      transmission to receive a copy likewise does not require
7569      acceptance.  However, nothing other than this License grants you
7570      permission to propagate or modify any covered work.  These actions
7571      infringe copyright if you do not accept this License.  Therefore,
7572      by modifying or propagating a covered work, you indicate your
7573      acceptance of this License to do so.
7574
7575   10. Automatic Licensing of Downstream Recipients.
7576
7577      Each time you convey a covered work, the recipient automatically
7578      receives a license from the original licensors, to run, modify and
7579      propagate that work, subject to this License.  You are not
7580      responsible for enforcing compliance by third parties with this
7581      License.
7582
7583      An "entity transaction" is a transaction transferring control of an
7584      organization, or substantially all assets of one, or subdividing an
7585      organization, or merging organizations.  If propagation of a
7586      covered work results from an entity transaction, each party to that
7587      transaction who receives a copy of the work also receives whatever
7588      licenses to the work the party's predecessor in interest had or
7589      could give under the previous paragraph, plus a right to possession
7590      of the Corresponding Source of the work from the predecessor in
7591      interest, if the predecessor has it or can get it with reasonable
7592      efforts.
7593
7594      You may not impose any further restrictions on the exercise of the
7595      rights granted or affirmed under this License.  For example, you
7596      may not impose a license fee, royalty, or other charge for exercise
7597      of rights granted under this License, and you may not initiate
7598      litigation (including a cross-claim or counterclaim in a lawsuit)
7599      alleging that any patent claim is infringed by making, using,
7600      selling, offering for sale, or importing the Program or any portion
7601      of it.
7602
7603   11. Patents.
7604
7605      A "contributor" is a copyright holder who authorizes use under this
7606      License of the Program or a work on which the Program is based.
7607      The work thus licensed is called the contributor's "contributor
7608      version".
7609
7610      A contributor's "essential patent claims" are all patent claims
7611      owned or controlled by the contributor, whether already acquired or
7612      hereafter acquired, that would be infringed by some manner,
7613      permitted by this License, of making, using, or selling its
7614      contributor version, but do not include claims that would be
7615      infringed only as a consequence of further modification of the
7616      contributor version.  For purposes of this definition, "control"
7617      includes the right to grant patent sublicenses in a manner
7618      consistent with the requirements of this License.
7619
7620      Each contributor grants you a non-exclusive, worldwide,
7621      royalty-free patent license under the contributor's essential
7622      patent claims, to make, use, sell, offer for sale, import and
7623      otherwise run, modify and propagate the contents of its contributor
7624      version.
7625
7626      In the following three paragraphs, a "patent license" is any
7627      express agreement or commitment, however denominated, not to
7628      enforce a patent (such as an express permission to practice a
7629      patent or covenant not to sue for patent infringement).  To "grant"
7630      such a patent license to a party means to make such an agreement or
7631      commitment not to enforce a patent against the party.
7632
7633      If you convey a covered work, knowingly relying on a patent
7634      license, and the Corresponding Source of the work is not available
7635      for anyone to copy, free of charge and under the terms of this
7636      License, through a publicly available network server or other
7637      readily accessible means, then you must either (1) cause the
7638      Corresponding Source to be so available, or (2) arrange to deprive
7639      yourself of the benefit of the patent license for this particular
7640      work, or (3) arrange, in a manner consistent with the requirements
7641      of this License, to extend the patent license to downstream
7642      recipients.  "Knowingly relying" means you have actual knowledge
7643      that, but for the patent license, your conveying the covered work
7644      in a country, or your recipient's use of the covered work in a
7645      country, would infringe one or more identifiable patents in that
7646      country that you have reason to believe are valid.
7647
7648      If, pursuant to or in connection with a single transaction or
7649      arrangement, you convey, or propagate by procuring conveyance of, a
7650      covered work, and grant a patent license to some of the parties
7651      receiving the covered work authorizing them to use, propagate,
7652      modify or convey a specific copy of the covered work, then the
7653      patent license you grant is automatically extended to all
7654      recipients of the covered work and works based on it.
7655
7656      A patent license is "discriminatory" if it does not include within
7657      the scope of its coverage, prohibits the exercise of, or is
7658      conditioned on the non-exercise of one or more of the rights that
7659      are specifically granted under this License.  You may not convey a
7660      covered work if you are a party to an arrangement with a third
7661      party that is in the business of distributing software, under which
7662      you make payment to the third party based on the extent of your
7663      activity of conveying the work, and under which the third party
7664      grants, to any of the parties who would receive the covered work
7665      from you, a discriminatory patent license (a) in connection with
7666      copies of the covered work conveyed by you (or copies made from
7667      those copies), or (b) primarily for and in connection with specific
7668      products or compilations that contain the covered work, unless you
7669      entered into that arrangement, or that patent license was granted,
7670      prior to 28 March 2007.
7671
7672      Nothing in this License shall be construed as excluding or limiting
7673      any implied license or other defenses to infringement that may
7674      otherwise be available to you under applicable patent law.
7675
7676   12. No Surrender of Others' Freedom.
7677
7678      If conditions are imposed on you (whether by court order, agreement
7679      or otherwise) that contradict the conditions of this License, they
7680      do not excuse you from the conditions of this License.  If you
7681      cannot convey a covered work so as to satisfy simultaneously your
7682      obligations under this License and any other pertinent obligations,
7683      then as a consequence you may not convey it at all.  For example,
7684      if you agree to terms that obligate you to collect a royalty for
7685      further conveying from those to whom you convey the Program, the
7686      only way you could satisfy both those terms and this License would
7687      be to refrain entirely from conveying the Program.
7688
7689   13. Use with the GNU Affero General Public License.
7690
7691      Notwithstanding any other provision of this License, you have
7692      permission to link or combine any covered work with a work licensed
7693      under version 3 of the GNU Affero General Public License into a
7694      single combined work, and to convey the resulting work.  The terms
7695      of this License will continue to apply to the part which is the
7696      covered work, but the special requirements of the GNU Affero
7697      General Public License, section 13, concerning interaction through
7698      a network will apply to the combination as such.
7699
7700   14. Revised Versions of this License.
7701
7702      The Free Software Foundation may publish revised and/or new
7703      versions of the GNU General Public License from time to time.  Such
7704      new versions will be similar in spirit to the present version, but
7705      may differ in detail to address new problems or concerns.
7706
7707      Each version is given a distinguishing version number.  If the
7708      Program specifies that a certain numbered version of the GNU
7709      General Public License "or any later version" applies to it, you
7710      have the option of following the terms and conditions either of
7711      that numbered version or of any later version published by the Free
7712      Software Foundation.  If the Program does not specify a version
7713      number of the GNU General Public License, you may choose any
7714      version ever published by the Free Software Foundation.
7715
7716      If the Program specifies that a proxy can decide which future
7717      versions of the GNU General Public License can be used, that
7718      proxy's public statement of acceptance of a version permanently
7719      authorizes you to choose that version for the Program.
7720
7721      Later license versions may give you additional or different
7722      permissions.  However, no additional obligations are imposed on any
7723      author or copyright holder as a result of your choosing to follow a
7724      later version.
7725
7726   15. Disclaimer of Warranty.
7727
7728      THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
7729      APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE
7730      COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
7731      WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
7732      INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
7733      MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE
7734      RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
7735      SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
7736      NECESSARY SERVICING, REPAIR OR CORRECTION.
7737
7738   16. Limitation of Liability.
7739
7740      IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
7741      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
7742      AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
7743      DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
7744      CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
7745      THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
7746      BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
7747      PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
7748      PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
7749      THE POSSIBILITY OF SUCH DAMAGES.
7750
7751   17. Interpretation of Sections 15 and 16.
7752
7753      If the disclaimer of warranty and limitation of liability provided
7754      above cannot be given local legal effect according to their terms,
7755      reviewing courts shall apply local law that most closely
7756      approximates an absolute waiver of all civil liability in
7757      connection with the Program, unless a warranty or assumption of
7758      liability accompanies a copy of the Program in return for a fee.
7759
7760 END OF TERMS AND CONDITIONS
7761 ===========================
7762
7763 How to Apply These Terms to Your New Programs
7764 =============================================
7765
7766 If you develop a new program, and you want it to be of the greatest
7767 possible use to the public, the best way to achieve this is to make it
7768 free software which everyone can redistribute and change under these
7769 terms.
7770
7771    To do so, attach the following notices to the program.  It is safest
7772 to attach them to the start of each source file to most effectively
7773 state the exclusion of warranty; and each file should have at least the
7774 "copyright" line and a pointer to where the full notice is found.
7775
7776      ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
7777      Copyright (C) YEAR NAME OF AUTHOR
7778
7779      This program is free software: you can redistribute it and/or modify
7780      it under the terms of the GNU General Public License as published by
7781      the Free Software Foundation, either version 3 of the License, or (at
7782      your option) any later version.
7783
7784      This program is distributed in the hope that it will be useful, but
7785      WITHOUT ANY WARRANTY; without even the implied warranty of
7786      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
7787      General Public License for more details.
7788
7789      You should have received a copy of the GNU General Public License
7790      along with this program.  If not, see <http://www.gnu.org/licenses/>.
7791
7792    Also add information on how to contact you by electronic and paper
7793 mail.
7794
7795    If the program does terminal interaction, make it output a short
7796 notice like this when it starts in an interactive mode:
7797
7798      PROGRAM Copyright (C) YEAR NAME OF AUTHOR
7799      This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
7800      This is free software, and you are welcome to redistribute it
7801      under certain conditions; type 'show c' for details.
7802
7803    The hypothetical commands 'show w' and 'show c' should show the
7804 appropriate parts of the General Public License.  Of course, your
7805 program's commands might be different; for a GUI interface, you would
7806 use an "about box".
7807
7808    You should also get your employer (if you work as a programmer) or
7809 school, if any, to sign a "copyright disclaimer" for the program, if
7810 necessary.  For more information on this, and how to apply and follow
7811 the GNU GPL, see <http://www.gnu.org/licenses/>.
7812
7813    The GNU General Public License does not permit incorporating your
7814 program into proprietary programs.  If your program is a subroutine
7815 library, you may consider it more useful to permit linking proprietary
7816 applications with the library.  If this is what you want to do, use the
7817 GNU Lesser General Public License instead of this License.  But first,
7818 please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.
7819