diff options
Diffstat (limited to 'doc/m4.info-1')
| -rw-r--r-- | doc/m4.info-1 | 7818 |
1 files changed, 7818 insertions, 0 deletions
diff --git a/doc/m4.info-1 b/doc/m4.info-1 new file mode 100644 index 0000000..db2ee65 --- /dev/null +++ b/doc/m4.info-1 @@ -0,0 +1,7818 @@ +This is m4.info, produced by makeinfo version 5.1 from m4.texi. + +This manual (22 September 2013) is for GNU M4 (version 1.4.17), a +package containing an implementation of the m4 macro language. + + Copyright (C) 1989-1994, 2004-2013 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License." +INFO-DIR-SECTION Text creation and manipulation +START-INFO-DIR-ENTRY +* M4: (m4). A powerful macro processor. +END-INFO-DIR-ENTRY + + +File: m4.info, Node: Top, Next: Preliminaries, Up: (dir) + +GNU M4 +****** + +This manual (22 September 2013) is for GNU M4 (version 1.4.17), a +package containing an implementation of the m4 macro language. + + Copyright (C) 1989-1994, 2004-2013 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License." + + GNU 'm4' is an implementation of the traditional UNIX macro +processor. It is mostly SVR4 compatible, although it has some +extensions (for example, handling more than 9 positional parameters to +macros). 'm4' also has builtin functions for including files, running +shell commands, doing arithmetic, etc. Autoconf needs GNU 'm4' for +generating 'configure' scripts, but not for running them. + + GNU 'm4' was originally written by Rene' Seindal, with subsequent +changes by Franc,ois Pinard and other volunteers on the Internet. All +names and email addresses can be found in the files 'm4-1.4.17/AUTHORS' +and 'm4-1.4.17/THANKS' from the GNU M4 distribution. + + This is release 1.4.17. It is now considered stable: future releases +in the 1.4.x series are only meant to fix bugs, increase speed, or +improve documentation. However... + + An experimental feature, which would improve 'm4' usefulness, allows +for changing the syntax for what is a "word" in 'm4'. You should use: + ./configure --enable-changeword +if you want this feature compiled in. The current implementation slows +down 'm4' considerably and is hardly acceptable. In the future, 'm4' +2.0 will come with a different set of new features that provide similar +capabilities, but without the inefficiencies, so changeword will go away +and _you should not count on it_. + +* Menu: + +* Preliminaries:: Introduction and preliminaries +* Invoking m4:: Invoking 'm4' +* Syntax:: Lexical and syntactic conventions + +* Macros:: How to invoke macros +* Definitions:: How to define new macros +* Conditionals:: Conditionals, loops, and recursion + +* Debugging:: How to debug macros and input + +* Input Control:: Input control +* File Inclusion:: File inclusion +* Diversions:: Diverting and undiverting output + +* Text handling:: Macros for text handling +* Arithmetic:: Macros for doing arithmetic +* Shell commands:: Macros for running shell commands +* Miscellaneous:: Miscellaneous builtin macros +* Frozen files:: Fast loading of frozen state + +* Compatibility:: Compatibility with other versions of 'm4' +* Answers:: Correct version of some examples + +* Copying This Package:: How to make copies of the overall M4 package +* Copying This Manual:: How to make copies of this manual +* Indices:: Indices of concepts and macros + + -- The Detailed Node Listing -- + +Introduction and preliminaries + +* Intro:: Introduction to 'm4' +* History:: Historical references +* Bugs:: Problems and bugs +* Manual:: Using this manual + +Invoking 'm4' + +* Operation modes:: Command line options for operation modes +* Preprocessor features:: Command line options for preprocessor features +* Limits control:: Command line options for limits control +* Frozen state:: Command line options for frozen state +* Debugging options:: Command line options for debugging +* Command line files:: Specifying input files on the command line + +Lexical and syntactic conventions + +* Names:: Macro names +* Quoted strings:: Quoting input to 'm4' +* Comments:: Comments in 'm4' input +* Other tokens:: Other kinds of input tokens +* Input processing:: How 'm4' copies input to output + +How to invoke macros + +* Invocation:: Macro invocation +* Inhibiting Invocation:: Preventing macro invocation +* Macro Arguments:: Macro arguments +* Quoting Arguments:: On Quoting Arguments to macros +* Macro expansion:: Expanding macros + +How to define new macros + +* Define:: Defining a new macro +* Arguments:: Arguments to macros +* Pseudo Arguments:: Special arguments to macros +* Undefine:: Deleting a macro +* Defn:: Renaming macros +* Pushdef:: Temporarily redefining macros + +* Indir:: Indirect call of macros +* Builtin:: Indirect call of builtins + +Conditionals, loops, and recursion + +* Ifdef:: Testing if a macro is defined +* Ifelse:: If-else construct, or multibranch +* Shift:: Recursion in 'm4' +* Forloop:: Iteration by counting +* Foreach:: Iteration by list contents +* Stacks:: Working with definition stacks +* Composition:: Building macros with macros + +How to debug macros and input + +* Dumpdef:: Displaying macro definitions +* Trace:: Tracing macro calls +* Debug Levels:: Controlling debugging output +* Debug Output:: Saving debugging output + +Input control + +* Dnl:: Deleting whitespace in input +* Changequote:: Changing the quote characters +* Changecom:: Changing the comment delimiters +* Changeword:: Changing the lexical structure of words +* M4wrap:: Saving text until end of input + +File inclusion + +* Include:: Including named files +* Search Path:: Searching for include files + +Diverting and undiverting output + +* Divert:: Diverting output +* Undivert:: Undiverting output +* Divnum:: Diversion numbers +* Cleardivert:: Discarding diverted text + +Macros for text handling + +* Len:: Calculating length of strings +* Index macro:: Searching for substrings +* Regexp:: Searching for regular expressions +* Substr:: Extracting substrings +* Translit:: Translating characters +* Patsubst:: Substituting text by regular expression +* Format:: Formatting strings (printf-like) + +Macros for doing arithmetic + +* Incr:: Decrement and increment operators +* Eval:: Evaluating integer expressions + +Macros for running shell commands + +* Platform macros:: Determining the platform +* Syscmd:: Executing simple commands +* Esyscmd:: Reading the output of commands +* Sysval:: Exit status +* Mkstemp:: Making temporary files + +Miscellaneous builtin macros + +* Errprint:: Printing error messages +* Location:: Printing current location +* M4exit:: Exiting from 'm4' + +Fast loading of frozen state + +* Using frozen files:: Using frozen files +* Frozen file format:: Frozen file format + +Compatibility with other versions of 'm4' + +* Extensions:: Extensions in GNU M4 +* Incompatibilities:: Facilities in System V m4 not in GNU M4 +* Other Incompatibilities:: Other incompatibilities + +Correct version of some examples + +* Improved exch:: Solution for 'exch' +* Improved forloop:: Solution for 'forloop' +* Improved foreach:: Solution for 'foreach' +* Improved copy:: Solution for 'copy' +* Improved m4wrap:: Solution for 'm4wrap' +* Improved cleardivert:: Solution for 'cleardivert' +* Improved capitalize:: Solution for 'capitalize' +* Improved fatal_error:: Solution for 'fatal_error' + +How to make copies of the overall M4 package + +* GNU General Public License:: License for copying the M4 package + +How to make copies of this manual + +* GNU Free Documentation License:: License for copying this manual + +Indices of concepts and macros + +* Macro index:: Index for all 'm4' macros +* Concept index:: Index for many concepts + + + +File: m4.info, Node: Preliminaries, Next: Invoking m4, Prev: Top, Up: Top + +1 Introduction and preliminaries +******************************** + +This first chapter explains what GNU 'm4' is, where 'm4' comes from, how +to read and use this documentation, how to call the 'm4' program, and +how to report bugs about it. It concludes by giving tips for reading +the remainder of the manual. + + The following chapters then detail all the features of the 'm4' +language. + +* Menu: + +* Intro:: Introduction to 'm4' +* History:: Historical references +* Bugs:: Problems and bugs +* Manual:: Using this manual + + +File: m4.info, Node: Intro, Next: History, Up: Preliminaries + +1.1 Introduction to 'm4' +======================== + +'m4' is a macro processor, in the sense that it copies its input to the +output, expanding macros as it goes. Macros are either builtin or +user-defined, and can take any number of arguments. Besides just doing +macro expansion, 'm4' has builtin functions for including named files, +running shell commands, doing integer arithmetic, manipulating text in +various ways, performing recursion, etc.... 'm4' can be used either as a +front-end to a compiler, or as a macro processor in its own right. + + The 'm4' macro processor is widely available on all UNIXes, and has +been standardized by POSIX. Usually, only a small percentage of users +are aware of its existence. However, those who find it often become +committed users. The popularity of GNU Autoconf, which requires GNU +'m4' for _generating_ 'configure' scripts, is an incentive for many to +install it, while these people will not themselves program in 'm4'. GNU +'m4' is mostly compatible with the System V, Release 4 version, except +for some minor differences. *Note Compatibility::, for more details. + + Some people find 'm4' to be fairly addictive. They first use 'm4' +for simple problems, then take bigger and bigger challenges, learning +how to write complex sets of 'm4' macros along the way. Once really +addicted, users pursue writing of sophisticated 'm4' applications even +to solve simple problems, devoting more time debugging their 'm4' +scripts than doing real work. Beware that 'm4' may be dangerous for the +health of compulsive programmers. + + +File: m4.info, Node: History, Next: Bugs, Prev: Intro, Up: Preliminaries + +1.2 Historical references +========================= + +Macro languages were invented early in the history of computing. In the +1950s Alan Perlis suggested that the macro language be independent of +the language being processed. Techniques such as conditional and +recursive macros, and using macros to define other macros, were +described by Doug McIlroy of Bell Labs in "Macro Instruction Extensions +of Compiler Languages", _Communications of the ACM_ 3, 4 (1960), 214-20, +<http://dx.doi.org/10.1145/367177.367223>. + + An important precursor of 'm4' was GPM; see C. Strachey, "A general +purpose macrogenerator", _Computer Journal_ 8, 3 (1965), 225-41, +<http://dx.doi.org/10.1093/comjnl/8.3.225>. GPM is also succinctly +described in David Gries's book _Compiler Construction for Digital +Computers_, Wiley (1971). Strachey was a brilliant programmer: GPM fit +into 250 machine instructions! + + Inspired by GPM while visiting Strachey's Lab in 1968, McIlroy wrote +a model preprocessor in that fit into a page of Snobol 3 code, and +McIlroy and Robert Morris developed a series of further models at Bell +Labs. Andrew D. Hall followed up with M6, a general purpose macro +processor used to port the Fortran source code of the Altran computer +algebra system; see Hall's "The M6 Macro Processor", Computing Science +Technical Report #2, Bell Labs (1972), +<http://cm.bell-labs.com/cm/cs/cstr/2.pdf>. M6's source code consisted +of about 600 Fortran statements. Its name was the first of the 'm4' +line. + + The Brian Kernighan and P.J. Plauger book _Software Tools_, +Addison-Wesley (1976), describes and implements a Unix macro-processor +language, which inspired Dennis Ritchie to write 'm3', a macro processor +for the AP-3 minicomputer. + + Kernighan and Ritchie then joined forces to develop the original +'m4', described in "The M4 Macro Processor", Bell Laboratories (1977), +<http://wolfram.schneider.org/bsd/7thEdManVol2/m4/m4.pdf>. It had only +21 builtin macros. + + While 'GPM' was more _pure_, 'm4' is meant to deal with the true +intricacies of real life: macros can be recognized without being +pre-announced, skipping whitespace or end-of-lines is easier, more +constructs are builtin instead of derived, etc. + + Originally, the Kernighan and Plauger macro-processor, and then 'm3', +formed the engine for the Rational FORTRAN preprocessor, that is, the +'Ratfor' equivalent of 'cpp'. Later, 'm4' was used as a front-end for +'Ratfor', 'C' and 'Cobol'. + + Rene' Seindal released his implementation of 'm4', GNU 'm4', in 1990, +with the aim of removing the artificial limitations in many of the +traditional 'm4' implementations, such as maximum line length, macro +size, or number of macros. + + The late Professor A. Dain Samples described and implemented a +further evolution in the form of 'M5': "User's Guide to the M5 Macro +Language: 2nd edition", Electronic Announcement on comp.compilers +newsgroup (1992). + + Franc,ois Pinard took over maintenance of GNU 'm4' in 1992, until +1994 when he released GNU 'm4' 1.4, which was the stable release for 10 +years. It was at this time that GNU Autoconf decided to require GNU +'m4' as its underlying engine, since all other implementations of 'm4' +had too many limitations. + + More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which +addressed some long standing bugs in the venerable 1.4 release. Then in +2005, Gary V. Vaughan collected together the many patches to GNU 'm4' +1.4 that were floating around the net and released 1.4.3 and 1.4.4. And +in 2006, Eric Blake joined the team and prepared patches for the release +of 1.4.5, 1.4.6, 1.4.7, and 1.4.8. More bug fixes were incorporated in +2007, with releases 1.4.9 and 1.4.10. Eric continued with some +portability fixes for 1.4.11 and 1.4.12 in 2008, 1.4.13 in 2009, 1.4.14 +and 1.4.15 in 2010, and 1.4.16 in 2011. + + Meanwhile, development has continued on new features for 'm4', such +as dynamic module loading and additional builtins. When complete, GNU +'m4' 2.0 will start a new series of releases. + + +File: m4.info, Node: Bugs, Next: Manual, Prev: History, Up: Preliminaries + +1.3 Problems and bugs +===================== + +If you have problems with GNU M4 or think you've found a bug, please +report it. Before reporting a bug, make sure you've actually found a +real bug. Carefully reread the documentation and see if it really says +you can do what you're trying to do. If it's not clear whether you +should be able to do something or not, report that too; it's a bug in +the documentation! + + Before reporting a bug or trying to fix it yourself, try to isolate +it to the smallest possible input file that reproduces the problem. +Then send us the input file and the exact results 'm4' gave you. Also +say what you expected to occur; this will help us decide whether the +problem was really in the documentation. + + Once you've got a precise problem, send e-mail to <bug-m4@gnu.org>. +Please include the version number of 'm4' you are using. You can get +this information with the command 'm4 --version'. Also provide details +about the platform you are executing on. + + Non-bug suggestions are always welcome as well. If you have +questions about things that are unclear in the documentation or are just +obscure features, please report them too. + + +File: m4.info, Node: Manual, Prev: Bugs, Up: Preliminaries + +1.4 Using this manual +===================== + +This manual contains a number of examples of 'm4' input and output, and +a simple notation is used to distinguish input, output and error +messages from 'm4'. Examples are set out from the normal text, and +shown in a fixed width font, like this + + This is an example of an example! + + To distinguish input from output, all output from 'm4' is prefixed by +the string '=>', and all error messages by the string 'error->'. When +showing how command line options affect matters, the command line is +shown with a prompt '$ 'like this'', otherwise, you can assume that a +simple 'm4' invocation will work. Thus: + + $ command line to invoke m4 + Example of input line + =>Output line from m4 + error->and an error message + + The sequence '^D' in an example indicates the end of the input file. +The sequence '<NL>' refers to the newline character. The majority of +these examples are self-contained, and you can run them with similar +results by invoking 'm4 -d'. In fact, the testsuite that is bundled in +the GNU M4 package consists of the examples in this document! Some of +the examples assume that your current directory is located where you +unpacked the installation, so if you plan on following along, you may +find it helpful to do this now: + + $ cd m4-1.4.17 + + As each of the predefined macros in 'm4' is described, a prototype +call of the macro will be shown, giving descriptive names to the +arguments, e.g., + + -- Composite: example (STRING, [COUNT = '1'] + [ARGUMENT]This is a sample prototype. There is not really a macro + named 'example', but this documents that if there were, it would be + a Composite macro, rather than a Builtin. It requires at least one + argument, STRING. Remember that in 'm4', there must not be a space + between the macro name and the opening parenthesis, unless it was + intended to call the macro without any arguments. The brackets + around COUNT and ARGUMENT show that these arguments are optional. + If COUNT is omitted, the macro behaves as if count were '1', + whereas if ARGUMENT is omitted, the macro behaves as if it were the + empty string. A blank argument is not the same as an omitted + argument. For example, 'example(`a')', 'example(`a',`1')', and + 'example(`a',`1',)' would behave identically with COUNT set to '1'; + while 'example(`a',)' and 'example(`a',`')' would explicitly pass + the empty string for COUNT. The ellipses ('...') show that the + macro processes additional arguments after ARGUMENT, rather than + ignoring them. + + All macro arguments in 'm4' are strings, but some are given special +interpretation, e.g., as numbers, file names, regular expressions, etc. +The documentation for each macro will state how the parameters are +interpreted, and what happens if the argument cannot be parsed according +to the desired interpretation. Unless specified otherwise, a parameter +specified to be a number is parsed as a decimal, even if the argument +has leading zeros; and parsing the empty string as a number results in 0 +rather than an error, although a warning will be issued. + + This document consistently writes and uses "builtin", without a +hyphen, as if it were an English word. This is how the 'builtin' +primitive is spelled within 'm4'. + + +File: m4.info, Node: Invoking m4, Next: Syntax, Prev: Preliminaries, Up: Top + +2 Invoking 'm4' +*************** + +The format of the 'm4' command is: + + m4 [OPTION...] [FILE...] + + All options begin with '-', or if long option names are used, with +'--'. A long option name need not be written completely, any +unambiguous prefix is sufficient. POSIX requires 'm4' to recognize +arguments intermixed with files, even when 'POSIXLY_CORRECT' is set in +the environment. Most options take effect at startup regardless of +their position, but some are documented below as taking effect after any +files that occurred earlier in the command line. The argument '--' is a +marker to denote the end of options. + + With short options, options that do not take arguments may be +combined into a single command line argument with subsequent options, +options with mandatory arguments may be provided either as a single +command line argument or as two arguments, and options with optional +arguments must be provided as a single argument. In other words, 'm4 +-QPDfoo -d a -df' is equivalent to 'm4 -Q -P -D foo -d -df -- ./a', +although the latter form is considered canonical. + + With long options, options with mandatory arguments may be provided +with an equal sign ('=') in a single argument, or as two arguments, and +options with optional arguments must be provided as a single argument. +In other words, 'm4 --def foo --debug a' is equivalent to 'm4 +--define=foo --debug= -- ./a', although the latter form is considered +canonical (not to mention more robust, in case a future version of 'm4' +introduces an option named '--default'). + + 'm4' understands the following options, grouped by functionality. + +* Menu: + +* Operation modes:: Command line options for operation modes +* Preprocessor features:: Command line options for preprocessor features +* Limits control:: Command line options for limits control +* Frozen state:: Command line options for frozen state +* Debugging options:: Command line options for debugging +* Command line files:: Specifying input files on the command line + + +File: m4.info, Node: Operation modes, Next: Preprocessor features, Up: Invoking m4 + +2.1 Command line options for operation modes +============================================ + +Several options control the overall operation of 'm4': + +'--help' + Print a help summary on standard output, then immediately exit 'm4' + without reading any input files or performing any other actions. + +'--version' + Print the version number of the program on standard output, then + immediately exit 'm4' without reading any input files or performing + any other actions. + +'-E' +'--fatal-warnings' + Controls the effect of warnings. If unspecified, then execution + continues and exit status is unaffected when a warning is printed. + If specified exactly once, warnings become fatal; when one is + issued, execution continues, but the exit status will be non-zero. + If specified multiple times, then execution halts with non-zero + status the first time a warning is issued. The introduction of + behavior levels is new to M4 1.4.9; for behavior consistent with + earlier versions, you should specify '-E' twice. + +'-i' +'--interactive' +'-e' + Makes this invocation of 'm4' interactive. This means that all + output will be unbuffered, and interrupts will be ignored. The + spelling '-e' exists for compatibility with other 'm4' + implementations, and issues a warning because it may be withdrawn + in a future version of GNU M4. + +'-P' +'--prefix-builtins' + Internally modify _all_ builtin macro names so they all start with + the prefix 'm4_'. For example, using this option, one should write + 'm4_define' instead of 'define', and 'm4___file__' instead of + '__file__'. This option has no effect if '-R' is also specified. + +'-Q' +'--quiet' +'--silent' + Suppress warnings, such as missing or superfluous arguments in + macro calls, or treating the empty string as zero. + +'--warn-macro-sequence[=REGEXP]' + Issue a warning if the regular expression REGEXP has a non-empty + match in any macro definition (either by 'define' or 'pushdef'). + Empty matches are ignored; therefore, supplying the empty string as + REGEXP disables any warning. If the optional REGEXP is not + supplied, then the default regular expression is + '\$\({[^}]*}\|[0-9][0-9]+\)' (a literal '$' followed by multiple + digits or by an open brace), since these sequences will change + semantics in the default operation of GNU M4 2.0 (due to a change + in how more than 9 arguments in a macro definition will be handled, + *note Arguments::). Providing an alternate regular expression can + provide a useful reverse lookup feature of finding where a macro is + defined to have a given definition. + +'-W REGEXP' +'--word-regexp=REGEXP' + Use REGEXP as an alternative syntax for macro names. This + experimental option will not be present in all GNU 'm4' + implementations (*note Changeword::). + + +File: m4.info, Node: Preprocessor features, Next: Limits control, Prev: Operation modes, Up: Invoking m4 + +2.2 Command line options for preprocessor features +================================================== + +Several options allow 'm4' to behave more like a preprocessor. Macro +definitions and deletions can be made on the command line, the search +path can be altered, and the output file can track where the input came +from. These features occur with the following options: + +'-D NAME[=VALUE]' +'--define=NAME[=VALUE]' + This enters NAME into the symbol table. If '=VALUE' is missing, + the value is taken to be the empty string. The VALUE can be any + string, and the macro can be defined to take arguments, just as if + it was defined from within the input. This option may be given + more than once; order with respect to file names is significant, + and redefining the same NAME loses the previous value. + +'-I DIRECTORY' +'--include=DIRECTORY' + Make 'm4' search DIRECTORY for included files that are not found in + the current working directory. *Note Search Path::, for more + details. This option may be given more than once. + +'-s' +'--synclines' + Generate synchronization lines, for use by the C preprocessor or + other similar tools. Order is significant with respect to file + names. This option is useful, for example, when 'm4' is used as a + front end to a compiler. Source file name and line number + information is conveyed by directives of the form '#line LINENUM + "FILE"', which are inserted as needed into the middle of the + output. Such directives mean that the following line originated or + was expanded from the contents of input file FILE at line LINENUM. + The '"FILE"' part is often omitted when the file name did not + change from the previous directive. + + Synchronization directives are always given on complete lines by + themselves. When a synchronization discrepancy occurs in the + middle of an output line, the associated synchronization directive + is delayed until the next newline that does not occur in the middle + of a quoted string or comment. + + define(`twoline', `1 + 2') + =>#line 2 "stdin" + => + changecom(`/*', `*/') + => + define(`comment', `/*1 + 2*/') + =>#line 5 + => + dnl no line + hello + =>#line 7 + =>hello + twoline + =>1 + =>#line 8 + =>2 + comment + =>/*1 + =>2*/ + one comment `two + three' + =>#line 10 + =>one /*1 + =>2*/ two + =>three + goodbye + =>#line 12 + =>goodbye + +'-U NAME' +'--undefine=NAME' + This deletes any predefined meaning NAME might have. Obviously, + only predefined macros can be deleted in this way. This option may + be given more than once; undefining a NAME that does not have a + definition is silently ignored. Order is significant with respect + to file names. + + +File: m4.info, Node: Limits control, Next: Frozen state, Prev: Preprocessor features, Up: Invoking m4 + +2.3 Command line options for limits control +=========================================== + +There are some limits within 'm4' that can be tuned. For compatibility, +'m4' also accepts some options that control limits in other +implementations, but which are automatically unbounded (limited only by +your hardware and operating system constraints) in GNU 'm4'. + +'-g' +'--gnu' + Enable all the extensions in this implementation. In this release + of M4, this option is always on by default; it is currently only + useful when overriding a prior use of '--traditional'. However, + having GNU behavior as default makes it impossible to write a + strictly POSIX-compliant client that avoids all incompatible GNU M4 + extensions, since such a client would have to use the non-POSIX + command-line option to force full POSIX behavior. Thus, a future + version of M4 will be changed to implicitly use the option + '--traditional' if the environment variable 'POSIXLY_CORRECT' is + set. Projects that intentionally use GNU extensions should + consider using '--gnu' to state their intentions, so that the + project will not mysteriously break if the user upgrades to a newer + M4 and has 'POSIXLY_CORRECT' set in their environment. + +'-G' +'--traditional' + Suppress all the extensions made in this implementation, compared + to the System V version. *Note Compatibility::, for a list of + these. + +'-H NUM' +'--hashsize=NUM' + Make the internal hash table for symbol lookup be NUM entries big. + For better performance, the number should be prime, but this is not + checked. The default is 509 entries. It should not be necessary + to increase this value, unless you define an excessive number of + macros. + +'-L NUM' +'--nesting-limit=NUM' + Artificially limit the nesting of macro calls to NUM levels, + stopping program execution if this limit is ever exceeded. When + not specified, nesting defaults to unlimited on platforms that can + detect stack overflow, and to 1024 levels otherwise. A value of + zero means unlimited; but then heavily nested code could + potentially cause a stack overflow. + + The precise effect of this option is more correctly associated with + textual nesting than dynamic recursion. It has been useful when + some complex 'm4' input was generated by mechanical means, and also + in diagnosing recursive algorithms that do not scale well. Most + users never need to change this option from its default. + + This option does _not_ have the ability to break endless rescanning + loops, since these do not necessarily consume much memory or stack + space. Through clever usage of rescanning loops, one can request + complex, time-consuming computations from 'm4' with useful results. + Putting limitations in this area would break 'm4' power. There are + many pathological cases: 'define(`a', `a')a' is only the simplest + example (but *note Compatibility::). Expecting GNU 'm4' to detect + these would be a little like expecting a compiler system to detect + and diagnose endless loops: it is a quite _hard_ problem in + general, if not undecidable! + +'-B NUM' +'-S NUM' +'-T NUM' + These options are present for compatibility with System V 'm4', but + do nothing in this implementation. They may disappear in future + releases, and issue a warning to that effect. + +'-N NUM' +'--diversions=NUM' + These options are present only for compatibility with previous + versions of GNU 'm4', and were controlling the number of possible + diversions which could be used at the same time. They do nothing, + because there is no fixed limit anymore. They may disappear in + future releases, and issue a warning to that effect. + + +File: m4.info, Node: Frozen state, Next: Debugging options, Prev: Limits control, Up: Invoking m4 + +2.4 Command line options for frozen state +========================================= + +GNU 'm4' comes with a feature of freezing internal state (*note Frozen +files::). This can be used to speed up 'm4' execution when reusing a +common initialization script. + +'-F FILE' +'--freeze-state=FILE' + Once execution is finished, write out the frozen state on the + specified FILE. It is conventional, but not required, for FILE to + end in '.m4f'. + +'-R FILE' +'--reload-state=FILE' + Before execution starts, recover the internal state from the + specified frozen FILE. The options '-D', '-U', and '-t' take + effect after state is reloaded, but before the input files are + read. + + +File: m4.info, Node: Debugging options, Next: Command line files, Prev: Frozen state, Up: Invoking m4 + +2.5 Command line options for debugging +====================================== + +Finally, there are several options for aiding in debugging 'm4' scripts. + +'-d[FLAGS]' +'--debug[=FLAGS]' + Set the debug-level according to the flags FLAGS. The debug-level + controls the format and amount of information presented by the + debugging functions. *Note Debug Levels::, for more details on the + format and meaning of FLAGS. If omitted, FLAGS defaults to 'aeq'. + +'--debugfile[=FILE]' +'-o FILE' +'--error-output=FILE' + Redirect 'dumpdef' output, debug messages, and trace output to the + named FILE. Warnings, error messages, and 'errprint' output are + still printed to standard error. If these options are not used, or + if FILE is unspecified (only possible for '--debugfile'), debug + output goes to standard error; if FILE is the empty string, debug + output is discarded. *Note Debug Output::, for more details. The + option '--debugfile' may be given more than once, and order is + significant with respect to file names. The spellings '-o' and + '--error-output' are misleading and inconsistent with other GNU + tools; for now they are silently accepted as synonyms of + '--debugfile' and only recognized once, but in a future version of + M4, using them will cause a warning to be issued. + +'-l NUM' +'--arglength=NUM' + Restrict the size of the output generated by macro tracing to NUM + characters per trace line. If unspecified or zero, output is + unlimited. *Note Debug Levels::, for more details. + +'-t NAME' +'--trace=NAME' + This enables tracing for the macro NAME, at any point where it is + defined. NAME need not be defined when this option is given. This + option may be given more than once, and order is significant with + respect to file names. *Note Trace::, for more details. + + +File: m4.info, Node: Command line files, Prev: Debugging options, Up: Invoking m4 + +2.6 Specifying input files on the command line +============================================== + +The remaining arguments on the command line are taken to be input file +names. If no names are present, standard input is read. A file name of +'-' is taken to mean standard input. It is conventional, but not +required, for input files to end in '.m4'. + + The input files are read in the sequence given. Standard input can +be read more than once, so the file name '-' may appear multiple times +on the command line; this makes a difference when input is from a +terminal or other special file type. It is an error if an input file +ends in the middle of argument collection, a comment, or a quoted +string. + + The options '--define' ('-D'), '--undefine' ('-U'), '--synclines' +('-s'), and '--trace' ('-t') only take effect after processing input +from any file names that occur earlier on the command line. For +example, assume the file 'foo' contains: + + $ cat foo + bar + + The text 'bar' can then be redefined over multiple uses of 'foo': + + $ m4 -Dbar=hello foo -Dbar=world foo + =>hello + =>world + + If none of the input files invoked 'm4exit' (*note M4exit::), the +exit status of 'm4' will be 0 for success, 1 for general failure (such +as problems with reading an input file), and 63 for version mismatch +(*note Using frozen files::). + + If you need to read a file whose name starts with a '-', you can +specify it as './-file', or use '--' to mark the end of options. + + +File: m4.info, Node: Syntax, Next: Macros, Prev: Invoking m4, Up: Top + +3 Lexical and syntactic conventions +*********************************** + +As 'm4' reads its input, it separates it into "tokens". A token is +either a name, a quoted string, or any single character, that is not a +part of either a name or a string. Input to 'm4' can also contain +comments. GNU 'm4' does not yet understand multibyte locales; all +operations are byte-oriented rather than character-oriented (although if +your locale uses a single byte encoding, such as ISO-8859-1, you will +not notice a difference). However, 'm4' is eight-bit clean, so you can +use non-ASCII characters in quoted strings (*note Changequote::), +comments (*note Changecom::), and macro names (*note Indir::), with the +exception of the NUL character (the zero byte ''\0''). + +* Menu: + +* Names:: Macro names +* Quoted strings:: Quoting input to 'm4' +* Comments:: Comments in 'm4' input +* Other tokens:: Other kinds of input tokens +* Input processing:: How 'm4' copies input to output + + +File: m4.info, Node: Names, Next: Quoted strings, Up: Syntax + +3.1 Macro names +=============== + +A name is any sequence of letters, digits, and the character '_' +(underscore), where the first character is not a digit. 'm4' will use +the longest such sequence found in the input. If a name has a macro +definition, it will be subject to macro expansion (*note Macros::). +Names are case-sensitive. + + Examples of legal names are: 'foo', '_tmp', and 'name01'. + + +File: m4.info, Node: Quoted strings, Next: Comments, Prev: Names, Up: Syntax + +3.2 Quoting input to 'm4' +========================= + +A quoted string is a sequence of characters surrounded by quote strings, +defaulting to '`' and ''', where the nested begin and end quotes within +the string are balanced. The value of a string token is the text, with +one level of quotes stripped off. Thus + + `' + => + +is the empty string, and double-quoting turns into single-quoting. + + ``quoted'' + =>`quoted' + + The quote characters can be changed at any time, using the builtin +macro 'changequote'. *Note Changequote::, for more information. + + +File: m4.info, Node: Comments, Next: Other tokens, Prev: Quoted strings, Up: Syntax + +3.3 Comments in 'm4' input +========================== + +Comments in 'm4' are normally delimited by the characters '#' and +newline. All characters between the comment delimiters are ignored, but +the entire comment (including the delimiters) is passed through to the +output--comments are _not_ discarded by 'm4'. + + Comments cannot be nested, so the first newline after a '#' ends the +comment. The commenting effect of the begin-comment string can be +inhibited by quoting it. + + $ m4 + `quoted text' # `commented text' + =>quoted text # `commented text' + `quoting inhibits' `#' `comments' + =>quoting inhibits # comments + + The comment delimiters can be changed to any string at any time, +using the builtin macro 'changecom'. *Note Changecom::, for more +information. + + +File: m4.info, Node: Other tokens, Next: Input processing, Prev: Comments, Up: Syntax + +3.4 Other kinds of input tokens +=============================== + +Any character, that is neither a part of a name, nor of a quoted string, +nor a comment, is a token by itself. When not in the context of macro +expansion, all of these tokens are just copied to output. However, +during macro expansion, whitespace characters (space, tab, newline, +formfeed, carriage return, vertical tab), parentheses ('(' and ')'), +comma (','), and dollar ('$') have additional roles, explained later. + + +File: m4.info, Node: Input processing, Prev: Other tokens, Up: Syntax + +3.5 How 'm4' copies input to output +=================================== + +As 'm4' reads the input token by token, it will copy each token directly +to the output immediately. + + The exception is when it finds a word with a macro definition. In +that case 'm4' will calculate the macro's expansion, possibly reading +more input to get the arguments. It then inserts the expansion in front +of the remaining input. In other words, the resulting text from a macro +call will be read and parsed into tokens again. + + 'm4' expands a macro as soon as possible. If it finds a macro call +when collecting the arguments to another, it will expand the second call +first. This process continues until there are no more macro calls to +expand and all the input has been consumed. + + For a running example, examine how 'm4' handles this input: + + format(`Result is %d', eval(`2**15')) + +First, 'm4' sees that the token 'format' is a macro name, so it collects +the tokens '(', '`Result is %d'', ',', and ' ', before encountering +another potential macro. Sure enough, 'eval' is a macro name, so the +nested argument collection picks up '(', '`2**15'', and ')', invoking +the eval macro with the lone argument of '2**15'. The expansion of +'eval(2**15)' is '32768', which is then rescanned as the five tokens +'3', '2', '7', '6', and '8'; and combined with the next ')', the format +macro now has all its arguments, as if the user had typed: + + format(`Result is %d', 32768) + +The format macro expands to 'Result is 32768', and we have another round +of scanning for the tokens 'Result', ' ', 'is', ' ', '3', '2', '7', '6', +and '8'. None of these are macros, so the final output is + + =>Result is 32768 + + As a more complicated example, we will contrast an actual code +example from the Gnulib project(1), showing both a buggy approach and +the desired results. The user desires to output a shell assignment +statement that takes its argument and turns it into a shell variable by +converting it to uppercase and prepending a prefix. The original +attempt looks like this: + + changequote([,])dnl + define([gl_STRING_MODULE_INDICATOR], + [ + dnl comment + GNULIB_]translit([$1],[a-z],[A-Z])[=1 + ])dnl + gl_STRING_MODULE_INDICATOR([strcase]) + => + => GNULIB_strcase=1 + => + + Oops - the argument did not get capitalized. And although the manual +is not able to easily show it, both lines that appear empty actually +contain two trailing spaces. By stepping through the parse, it is easy +to see what happened. First, 'm4' sees the token 'changequote', which +it recognizes as a macro, followed by '(', '[', ',', ']', and ')' to +form the argument list. The macro expands to the empty string, but +changes the quoting characters to something more useful for generating +shell code (unbalanced '`' and ''' appear all the time in shell scripts, +but unbalanced '[]' tend to be rare). Also in the first line, 'm4' sees +the token 'dnl', which it recognizes as a builtin macro that consumes +the rest of the line, resulting in no output for that line. + + The second line starts a macro definition. 'm4' sees the token +'define', which it recognizes as a macro, followed by a '(', +'[gl_STRING_MODULE_INDICATOR]', and ','. Because an unquoted comma was +encountered, the first argument is known to be the expansion of the +single-quoted string token, or 'gl_STRING_MODULE_INDICATOR'. Next, 'm4' +sees '<NL>', ' ', and ' ', but this whitespace is discarded as part of +argument collection. Then comes a rather lengthy single-quoted string +token, '[<NL> dnl comment<NL> GNULIB_]'. This is followed by the +token 'translit', which 'm4' recognizes as a macro name, so a nested +macro expansion has started. + + The arguments to the 'translit' are found by the tokens '(', '[$1]', +',', '[a-z]', ',', '[A-Z]', and finally ')'. All three string arguments +are expanded (or in other words, the quotes are stripped), and since +neither '$' nor '1' need capitalization, the result of the macro is +'$1'. This expansion is rescanned, resulting in the two literal +characters '$' and '1'. + + Scanning of the outer macro resumes, and picks up with '[=1<NL> ]', +and finally ')'. The collected pieces of expanded text are +concatenated, with the end result that the macro +'gl_STRING_MODULE_INDICATOR' is now defined to be the sequence +'<NL> dnl comment<NL> GNULIB_$1=1<NL> '. Once again, 'dnl' is +recognized and avoids a newline in the output. + + The final line is then parsed, beginning with ' ' and ' ' that are +output literally. Then 'gl_STRING_MODULE_INDICATOR' is recognized as a +macro name, with an argument list of '(', '[strcase]', and ')'. Since +the definition of the macro contains the sequence '$1', that sequence is +replaced with the argument 'strcase' prior to starting the rescan. The +rescan sees '<NL>' and four spaces, which are output literally, then +'dnl', which discards the text ' comment<NL>'. Next comes four more +spaces, also output literally, and the token 'GNULIB_strcase', which +resulted from the earlier parameter substitution. Since that is not a +macro name, it is output literally, followed by the literal tokens '=', +'1', '<NL>', and two more spaces. Finally, the original '<NL>' seen +after the macro invocation is scanned and output literally. + + Now for a corrected approach. This rearranges the use of newlines +and whitespace so that less whitespace is output (which, although +harmless to shell scripts, can be visually unappealing), and fixes the +quoting issues so that the capitalization occurs when the macro +'gl_STRING_MODULE_INDICATOR' is invoked, rather then when it is defined. +It also adds another layer of quoting to the first argument of +'translit', to ensure that the output will be rescanned as a string +rather than a potential uppercase macro name needing further expansion. + + changequote([,])dnl + define([gl_STRING_MODULE_INDICATOR], + [dnl comment + GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl + ])dnl + gl_STRING_MODULE_INDICATOR([strcase]) + => GNULIB_STRCASE=1 + + The parsing of the first line is unchanged. The second line sees the +name of the macro to define, then sees the discarded '<NL>' and two +spaces, as before. But this time, the next token is '[dnl +comment<NL> GNULIB_[]translit([[$1]], [a-z], [A-Z])=1dnl<NL>]', which +includes nested quotes, followed by ')' to end the macro definition and +'dnl' to skip the newline. No early expansion of 'translit' occurs, so +the entire string becomes the definition of the macro. + + The final line is then parsed, beginning with two spaces that are +output literally, and an invocation of 'gl_STRING_MODULE_INDICATOR' with +the argument 'strcase'. Again, the '$1' in the macro definition is +substituted prior to rescanning. Rescanning first encounters 'dnl', and +discards ' comment<NL>'. Then two spaces are output literally. Next +comes the token 'GNULIB_', but that is not a macro, so it is output +literally. The token '[]' is an empty string, so it does not affect +output. Then the token 'translit' is encountered. + + This time, the arguments to 'translit' are parsed as '(', +'[[strcase]]', ',', ' ', '[a-z]', ',', ' ', '[A-Z]', and ')'. The two +spaces are discarded, and the translit results in the desired result +'[STRCASE]'. This is rescanned, but since it is a string, the quotes +are stripped and the only output is a literal 'STRCASE'. Then the +scanner sees '=' and '1', which are output literally, followed by 'dnl' +which discards the rest of the definition of +'gl_STRING_MODULE_INDICATOR'. The newline at the end of output is the +literal '<NL>' that appeared after the invocation of the macro. + + The order in which 'm4' expands the macros can be further explored +using the trace facilities of GNU 'm4' (*note Trace::). + + ---------- Footnotes ---------- + + (1) Derived from a patch in +<http://lists.gnu.org/archive/html/bug-gnulib/2007-01/msg00389.html>, +and a followup patch in +<http://lists.gnu.org/archive/html/bug-gnulib/2007-02/msg00000.html> + + +File: m4.info, Node: Macros, Next: Definitions, Prev: Syntax, Up: Top + +4 How to invoke macros +********************** + +This chapter covers macro invocation, macro arguments and how macro +expansion is treated. + +* Menu: + +* Invocation:: Macro invocation +* Inhibiting Invocation:: Preventing macro invocation +* Macro Arguments:: Macro arguments +* Quoting Arguments:: On Quoting Arguments to macros +* Macro expansion:: Expanding macros + + +File: m4.info, Node: Invocation, Next: Inhibiting Invocation, Up: Macros + +4.1 Macro invocation +==================== + +Macro invocations has one of the forms + + name + +which is a macro invocation without any arguments, or + + name(arg1, arg2, ..., argN) + +which is a macro invocation with N arguments. Macros can have any +number of arguments. All arguments are strings, but different macros +might interpret the arguments in different ways. + + The opening parenthesis _must_ follow the NAME directly, with no +spaces in between. If it does not, the macro is called with no +arguments at all. + + For a macro call to have no arguments, the parentheses _must_ be left +out. The macro call + + name() + +is a macro call with one argument, which is the empty string, not a call +with no arguments. + + +File: m4.info, Node: Inhibiting Invocation, Next: Macro Arguments, Prev: Invocation, Up: Macros + +4.2 Preventing macro invocation +=============================== + +An innovation of the 'm4' language, compared to some of its predecessors +(like Strachey's 'GPM', for example), is the ability to recognize macro +calls without resorting to any special, prefixed invocation character. +While generally useful, this feature might sometimes be the source of +spurious, unwanted macro calls. So, GNU 'm4' offers several mechanisms +or techniques for inhibiting the recognition of names as macro calls. + + First of all, many builtin macros cannot meaningfully be called +without arguments. As a GNU extension, for any of these macros, +whenever an opening parenthesis does not immediately follow their name, +the builtin macro call is not triggered. This solves the most usual +cases, like for 'include' or 'eval'. Later in this document, the +sentence "This macro is recognized only with parameters" refers to this +specific provision of GNU M4, also known as a blind builtin macro. For +the builtins defined by POSIX that bear this disclaimer, POSIX +specifically states that invoking those builtins without arguments is +unspecified, because many other implementations simply invoke the +builtin as though it were given one empty argument instead. + + $ m4 + eval + =>eval + eval(`1') + =>1 + + There is also a command line option ('--prefix-builtins', or '-P', +*note Invoking m4: Operation modes.) that renames all builtin macros +with a prefix of 'm4_' at startup. The option has no effect whatsoever +on user defined macros. For example, with this option, one has to write +'m4_dnl' and even 'm4_m4exit'. It also has no effect on whether a macro +requires parameters. + + $ m4 -P + eval + =>eval + eval(`1') + =>eval(1) + m4_eval + =>m4_eval + m4_eval(`1') + =>1 + + Another alternative is to redefine problematic macros to a name less +likely to cause conflicts, using *note Definitions::. + + If your version of GNU 'm4' has the 'changeword' feature compiled in, +it offers far more flexibility in specifying the syntax of macro names, +both builtin or user-defined. *Note Changeword::, for more information +on this experimental feature. + + Of course, the simplest way to prevent a name from being interpreted +as a call to an existing macro is to quote it. The remainder of this +section studies a little more deeply how quoting affects macro +invocation, and how quoting can be used to inhibit macro invocation. + + Even if quoting is usually done over the whole macro name, it can +also be done over only a few characters of this name (provided, of +course, that the unquoted portions are not also a macro). It is also +possible to quote the empty string, but this works only _inside_ the +name. For example: + + `divert' + =>divert + `d'ivert + =>divert + di`ver't + =>divert + div`'ert + =>divert + +all yield the string 'divert'. While in both: + + `'divert + => + divert`' + => + +the 'divert' builtin macro will be called, which expands to the empty +string. + + The output of macro evaluations is always rescanned. In the +following example, the input 'x`'y' yields the string 'bCD', exactly as +if 'm4' has been given 'substr(ab`'cde, `1', `3')' as input: + + define(`cde', `CDE') + => + define(`x', `substr(ab') + => + define(`y', `cde, `1', `3')') + => + x`'y + =>bCD + + Unquoted strings on either side of a quoted string are subject to +being recognized as macro names. In the following example, quoting the +empty string allows for the second 'macro' to be recognized as such: + + define(`macro', `m') + => + macro(`m')macro + =>mmacro + macro(`m')`'macro + =>mm + + Quoting may prevent recognizing as a macro name the concatenation of +a macro expansion with the surrounding characters. In this example: + + define(`macro', `di$1') + => + macro(`v')`ert' + =>divert + macro(`v')ert + => + +the input will produce the string 'divert'. When the quotes were +removed, the 'divert' builtin was called instead. + + +File: m4.info, Node: Macro Arguments, Next: Quoting Arguments, Prev: Inhibiting Invocation, Up: Macros + +4.3 Macro arguments +=================== + +When a name is seen, and it has a macro definition, it will be expanded +as a macro. + + If the name is followed by an opening parenthesis, the arguments will +be collected before the macro is called. If too few arguments are +supplied, the missing arguments are taken to be the empty string. +However, some builtins are documented to behave differently for a +missing optional argument than for an explicit empty string. If there +are too many arguments, the excess arguments are ignored. Unquoted +leading whitespace is stripped off all arguments, but whitespace +generated by a macro expansion or occurring after a macro that expanded +to an empty string remains intact. Whitespace includes space, tab, +newline, carriage return, vertical tab, and formfeed. + + define(`macro', `$1') + => + macro( unquoted leading space lost) + =>unquoted leading space lost + macro(` quoted leading space kept') + => quoted leading space kept + macro( + divert `unquoted space kept after expansion') + => unquoted space kept after expansion + macro(macro(` + ')`whitespace from expansion kept') + => + =>whitespace from expansion kept + macro(`unquoted trailing whitespace kept' + ) + =>unquoted trailing whitespace kept + => + + Normally 'm4' will issue warnings if a builtin macro is called with +an inappropriate number of arguments, but it can be suppressed with the +'--quiet' command line option (or '--silent', or '-Q', *note Invoking +m4: Operation modes.). For user defined macros, there is no check of +the number of arguments given. + + $ m4 + index(`abc') + error->m4:stdin:1: Warning: too few arguments to builtin `index' + =>0 + index(`abc',) + =>0 + index(`abc', `b', `ignored') + error->m4:stdin:3: Warning: excess arguments to builtin `index' ignored + =>1 + + $ m4 -Q + index(`abc') + =>0 + index(`abc',) + =>0 + index(`abc', `b', `ignored') + =>1 + + Macros are expanded normally during argument collection, and whatever +commas, quotes and parentheses that might show up in the resulting +expanded text will serve to define the arguments as well. Thus, if FOO +expands to ', b, c', the macro call + + bar(a foo, d) + +is a macro call with four arguments, which are 'a ', 'b', 'c' and 'd'. +To understand why the first argument contains whitespace, remember that +unquoted leading whitespace is never part of an argument, but trailing +whitespace always is. + + It is possible for a macro's definition to change during argument +collection, in which case the expansion uses the definition that was in +effect at the time the opening '(' was seen. + + define(`f', `1') + => + f(define(`f', `2')) + =>1 + f + =>2 + + It is an error if the end of file occurs while collecting arguments. + + hello world + =>hello world + define( + ^D + error->m4:stdin:2: ERROR: end of file in argument list + + +File: m4.info, Node: Quoting Arguments, Next: Macro expansion, Prev: Macro Arguments, Up: Macros + +4.4 On Quoting Arguments to macros +================================== + +Each argument has unquoted leading whitespace removed. Within each +argument, all unquoted parentheses must match. For example, if FOO is a +macro, + + foo(() (`(') `(') + +is a macro call, with one argument, whose value is '() (() ('. Commas +separate arguments, except when they occur inside quotes, comments, or +unquoted parentheses. *Note Pseudo Arguments::, for examples. + + It is common practice to quote all arguments to macros, unless you +are sure you want the arguments expanded. Thus, in the above example +with the parentheses, the 'right' way to do it is like this: + + foo(`() (() (') + + It is, however, in certain cases necessary (because nested expansion +must occur to create the arguments for the outer macro) or convenient +(because it uses fewer characters) to leave out quotes for some +arguments, and there is nothing wrong in doing it. It just makes life a +bit harder, if you are not careful to follow a consistent quoting style. +For consistency, this manual follows the rule of thumb that each layer +of parentheses introduces another layer of single quoting, except when +showing the consequences of quoting rules. This is done even when the +quoted string cannot be a macro, such as with integers when you have not +changed the syntax via 'changeword' (*note Changeword::). + + The quoting rule of thumb of one level of quoting per parentheses has +a nice property: when a macro name appears inside parentheses, you can +determine when it will be expanded. If it is not quoted, it will be +expanded prior to the outer macro, so that its expansion becomes the +argument. If it is single-quoted, it will be expanded after the outer +macro. And if it is double-quoted, it will be used as literal text +instead of a macro name. + + define(`active', `ACT, IVE') + => + define(`show', `$1 $1') + => + show(active) + =>ACT ACT + show(`active') + =>ACT, IVE ACT, IVE + show(``active'') + =>active active + + +File: m4.info, Node: Macro expansion, Prev: Quoting Arguments, Up: Macros + +4.5 Macro expansion +=================== + +When the arguments, if any, to a macro call have been collected, the +macro is expanded, and the expansion text is pushed back onto the input +(unquoted), and reread. The expansion text from one macro call might +therefore result in more macros being called, if the calls are included, +completely or partially, in the first macro calls' expansion. + + Taking a very simple example, if FOO expands to 'bar', and BAR +expands to 'Hello', the input + + $ m4 -Dbar=Hello -Dfoo=bar + foo + =>Hello + +will expand first to 'bar', and when this is reread and expanded, into +'Hello'. + + +File: m4.info, Node: Definitions, Next: Conditionals, Prev: Macros, Up: Top + +5 How to define new macros +************************** + +Macros can be defined, redefined and deleted in several different ways. +Also, it is possible to redefine a macro without losing a previous +value, and bring back the original value at a later time. + +* Menu: + +* Define:: Defining a new macro +* Arguments:: Arguments to macros +* Pseudo Arguments:: Special arguments to macros +* Undefine:: Deleting a macro +* Defn:: Renaming macros +* Pushdef:: Temporarily redefining macros + +* Indir:: Indirect call of macros +* Builtin:: Indirect call of builtins + + +File: m4.info, Node: Define, Next: Arguments, Up: Definitions + +5.1 Defining a macro +==================== + +The normal way to define or redefine macros is to use the builtin +'define': + + -- Builtin: define (NAME, [EXPANSION] + Defines NAME to expand to EXPANSION. If EXPANSION is not given, it + is taken to be empty. + + The expansion of 'define' is void. The macro 'define' is + recognized only with parameters. + + The following example defines the macro FOO to expand to the text +'Hello World.'. + + define(`foo', `Hello world.') + => + foo + =>Hello world. + + The empty line in the output is there because the newline is not a +part of the macro definition, and it is consequently copied to the +output. This can be avoided by use of the macro 'dnl'. *Note Dnl::, +for details. + + The first argument to 'define' should be quoted; otherwise, if the +macro is already defined, you will be defining a different macro. This +example shows the problems with underquoting, since we did not want to +redefine 'one': + + define(foo, one) + => + define(foo, two) + => + one + =>two + + GNU 'm4' normally replaces only the _topmost_ definition of a macro +if it has several definitions from 'pushdef' (*note Pushdef::). Some +other implementations of 'm4' replace all definitions of a macro with +'define'. *Note Incompatibilities::, for more details. + + As a GNU extension, the first argument to 'define' does not have to +be a simple word. It can be any text string, even the empty string. A +macro with a non-standard name cannot be invoked in the normal way, as +the name is not recognized. It can only be referenced by the builtins +'indir' (*note Indir::) and 'defn' (*note Defn::). + + Arrays and associative arrays can be simulated by using non-standard +macro names. + + -- Composite: array (INDEX) + -- Composite: array_set (INDEX, [VALUE] + Provide access to entries within an array. 'array' reads the entry + at location INDEX, and 'array_set' assigns VALUE to location INDEX. + + define(`array', `defn(format(``array[%d]'', `$1'))') + => + define(`array_set', `define(format(``array[%d]'', `$1'), `$2')') + => + array_set(`4', `array element no. 4') + => + array_set(`17', `array element no. 17') + => + array(`4') + =>array element no. 4 + array(eval(`10 + 7')) + =>array element no. 17 + + Change the '%d' to '%s' and it is an associative array. + + +File: m4.info, Node: Arguments, Next: Pseudo Arguments, Prev: Define, Up: Definitions + +5.2 Arguments to macros +======================= + +Macros can have arguments. The Nth argument is denoted by '$n' in the +expansion text, and is replaced by the Nth actual argument, when the +macro is expanded. Replacement of arguments happens before rescanning, +regardless of how many nesting levels of quoting appear in the +expansion. Here is an example of a macro with two arguments. + + -- Composite: exch (ARG1, ARG2) + Expands to ARG2 followed by ARG1, effectively exchanging their + order. + + define(`exch', `$2, $1') + => + exch(`arg1', `arg2') + =>arg2, arg1 + + This can be used, for example, if you like the arguments to 'define' +to be reversed. + + define(`exch', `$2, $1') + => + define(exch(``expansion text'', ``macro'')) + => + macro + =>expansion text + + *Note Quoting Arguments::, for an explanation of the double quotes. +(You should try and improve this example so that clients of 'exch' do +not have to double quote; or *note Answers: Improved exch.). + + As a special case, the zeroth argument, '$0', is always the name of +the macro being expanded. + + define(`test', ``Macro name: $0'') + => + test + =>Macro name: test + + If you want quoted text to appear as part of the expansion text, +remember that quotes can be nested in quoted strings. Thus, in + + define(`foo', `This is macro `foo'.') + => + foo + =>This is macro foo. + +The 'foo' in the expansion text is _not_ expanded, since it is a quoted +string, and not a name. + + GNU 'm4' allows the number following the '$' to consist of one or +more digits, allowing macros to have any number of arguments. The +extension of accepting multiple digits is incompatible with POSIX, and +is different than traditional implementations of 'm4', which only +recognize one digit. Therefore, future versions of GNU M4 will phase +out this feature. To portably access beyond the ninth argument, you can +use the 'argn' macro documented later (*note Shift::). + + POSIX also states that '$' followed immediately by '{' in a macro +definition is implementation-defined. This version of M4 passes the +literal characters '${' through unchanged, but M4 2.0 will implement an +optional feature similar to 'sh', where '${11}' expands to the eleventh +argument, to replace the current recognition of '$11'. Meanwhile, if +you want to guarantee that you will get a literal '${' in output when +expanding a macro, even when you upgrade to M4 2.0, you can use nested +quoting to your advantage: + + define(`foo', `single quoted $`'{1} output') + => + define(`bar', ``double quoted $'`{2} output'') + => + foo(`a', `b') + =>single quoted ${1} output + bar(`a', `b') + =>double quoted ${2} output + + To help you detect places in your M4 input files that might change in +behavior due to the changed behavior of M4 2.0, you can use the +'--warn-macro-sequence' command-line option (*note Invoking m4: +Operation modes.) with the default regular expression. This will add a +warning any time a macro definition includes '$' followed by multiple +digits, or by '{'. The warning is not enabled by default, because it +triggers a number of warnings in Autoconf 2.61 (and Autoconf uses '-E' +to treat warnings as errors), and because it will still be possible to +restore older behavior in M4 2.0. + + $ m4 --warn-macro-sequence + define(`foo', `$001 ${1} $1') + error->m4:stdin:1: Warning: definition of `foo' contains sequence `$001' + error->m4:stdin:1: Warning: definition of `foo' contains sequence `${1}' + => + foo(`bar') + =>bar ${1} bar + + +File: m4.info, Node: Pseudo Arguments, Next: Undefine, Prev: Arguments, Up: Definitions + +5.3 Special arguments to macros +=============================== + +There is a special notation for the number of actual arguments supplied, +and for all the actual arguments. + + The number of actual arguments in a macro call is denoted by '$#' in +the expansion text. + + -- Composite: nargs (...) + Expands to a count of the number of arguments supplied. + + define(`nargs', `$#') + => + nargs + =>0 + nargs() + =>1 + nargs(`arg1', `arg2', `arg3') + =>3 + nargs(`commas can be quoted, like this') + =>1 + nargs(arg1#inside comments, commas do not separate arguments + still arg1) + =>1 + nargs((unquoted parentheses, like this, group arguments)) + =>1 + + Remember that '#' defaults to the comment character; if you forget +quotes to inhibit the comment behavior, your macro definition may not +end where you expected. + + dnl Attempt to define a macro to just `$#' + define(underquoted, $#) + oops) + => + underquoted + =>0) + =>oops + + The notation '$*' can be used in the expansion text to denote all the +actual arguments, unquoted, with commas in between. For example + + define(`echo', `$*') + => + echo(arg1, arg2, arg3 , arg4) + =>arg1,arg2,arg3 ,arg4 + + Often each argument should be quoted, and the notation '$@' handles +that. It is just like '$*', except that it quotes each argument. A +simple example of that is: + + define(`echo', `$@') + => + echo(arg1, arg2, arg3 , arg4) + =>arg1,arg2,arg3 ,arg4 + + Where did the quotes go? Of course, they were eaten, when the +expanded text were reread by 'm4'. To show the difference, try + + define(`echo1', `$*') + => + define(`echo2', `$@') + => + define(`foo', `This is macro `foo'.') + => + echo1(foo) + =>This is macro This is macro foo.. + echo1(`foo') + =>This is macro foo. + echo2(foo) + =>This is macro foo. + echo2(`foo') + =>foo + +*Note Trace::, if you do not understand this. As another example of the +difference, remember that comments encountered in arguments are passed +untouched to the macro, and that quoting disables comments. + + define(`echo1', `$*') + => + define(`echo2', `$@') + => + define(`foo', `bar') + => + echo1(#foo'foo + foo) + =>#foo'foo + =>bar + echo2(#foo'foo + foo) + =>#foobar + =>bar' + + A '$' sign in the expansion text, that is not followed by anything +'m4' understands, is simply copied to the macro expansion, as any other +text is. + + define(`foo', `$$$ hello $$$') + => + foo + =>$$$ hello $$$ + + If you want a macro to expand to something like '$12', the judicious +use of nested quoting can put a safe character between the '$' and the +next character, relying on the rescanning to remove the nested quote. +This will prevent 'm4' from interpreting the '$' sign as a reference to +an argument. + + define(`foo', `no nested quote: $1') + => + foo(`arg') + =>no nested quote: arg + define(`foo', `nested quote around $: `$'1') + => + foo(`arg') + =>nested quote around $: $1 + define(`foo', `nested empty quote after $: $`'1') + => + foo(`arg') + =>nested empty quote after $: $1 + define(`foo', `nested quote around next character: $`1'') + => + foo(`arg') + =>nested quote around next character: $1 + define(`foo', `nested quote around both: `$1'') + => + foo(`arg') + =>nested quote around both: arg + + +File: m4.info, Node: Undefine, Next: Defn, Prev: Pseudo Arguments, Up: Definitions + +5.4 Deleting a macro +==================== + +A macro definition can be removed with 'undefine': + + -- Builtin: undefine (NAME...) + For each argument, remove the macro NAME. The macro names must + necessarily be quoted, since they will be expanded otherwise. + + The expansion of 'undefine' is void. The macro 'undefine' is + recognized only with parameters. + + foo bar blah + =>foo bar blah + define(`foo', `some')define(`bar', `other')define(`blah', `text') + => + foo bar blah + =>some other text + undefine(`foo') + => + foo bar blah + =>foo other text + undefine(`bar', `blah') + => + foo bar blah + =>foo bar blah + + Undefining a macro inside that macro's expansion is safe; the macro +still expands to the definition that was in effect at the '('. + + define(`f', ``$0':$1') + => + f(f(f(undefine(`f')`hello world'))) + =>f:f:f:hello world + f(`bye') + =>f(bye) + + It is not an error for NAME to have no macro definition. In that +case, 'undefine' does nothing. + + +File: m4.info, Node: Defn, Next: Pushdef, Prev: Undefine, Up: Definitions + +5.5 Renaming macros +=================== + +It is possible to rename an already defined macro. To do this, you need +the builtin 'defn': + + -- Builtin: defn (NAME...) + Expands to the _quoted definition_ of each NAME. If an argument is + not a defined macro, the expansion for that argument is empty. + + If NAME is a user-defined macro, the quoted definition is simply + the quoted expansion text. If, instead, there is only one NAME and + it is a builtin, the expansion is a special token, which points to + the builtin's internal definition. This token is only meaningful + as the second argument to 'define' (and 'pushdef'), and is silently + converted to an empty string in most other contexts. Combining a + builtin with anything else is not supported; a warning is issued + and the builtin is omitted from the final expansion. + + The macro 'defn' is recognized only with parameters. + + Its normal use is best understood through an example, which shows how +to rename 'undefine' to 'zap': + + define(`zap', defn(`undefine')) + => + zap(`undefine') + => + undefine(`zap') + =>undefine(zap) + + In this way, 'defn' can be used to copy macro definitions, and also +definitions of builtin macros. Even if the original macro is removed, +the other name can still be used to access the definition. + + The fact that macro definitions can be transferred also explains why +you should use '$0', rather than retyping a macro's name in its +definition: + + define(`foo', `This is `$0'') + => + define(`bar', defn(`foo')) + => + bar + =>This is bar + + Macros used as string variables should be referred through 'defn', to +avoid unwanted expansion of the text: + + define(`string', `The macro dnl is very useful + ') + => + string + =>The macro + defn(`string') + =>The macro dnl is very useful + => + + However, it is important to remember that 'm4' rescanning is purely +textual. If an unbalanced end-quote string occurs in a macro +definition, the rescan will see that embedded quote as the termination +of the quoted string, and the remainder of the macro's definition will +be rescanned unquoted. Thus it is a good idea to avoid unbalanced +end-quotes in macro definitions or arguments to macros. + + define(`foo', a'a) + => + define(`a', `A') + => + define(`echo', `$@') + => + foo + =>A'A + defn(`foo') + =>aA' + echo(foo) + =>AA' + + On the other hand, it is possible to exploit the fact that 'defn' can +concatenate multiple macros prior to the rescanning phase, in order to +join the definitions of macros that, in isolation, have unbalanced +quotes. This is particularly useful when one has used several macros to +accumulate text that M4 should rescan as a whole. In the example below, +note how the use of 'defn' on 'l' in isolation opens a string, which is +not closed until the next line; but used on 'l' and 'r' together results +in nested quoting. + + define(`l', `<[>')define(`r', `<]>') + => + changequote(`[', `]') + => + defn([l])defn([r]) + ]) + =><[>]defn([r]) + =>) + defn([l], [r]) + =><[>][<]> + + Using 'defn' to generate special tokens for builtin macros outside of +expected contexts can sometimes trigger warnings. But most of the time, +such tokens are silently converted to the empty string. + + $ m4 -d + defn(`defn') + => + define(defn(`divnum'), `cannot redefine a builtin token') + error->m4:stdin:2: Warning: define: invalid macro name ignored + => + divnum + =>0 + len(defn(`divnum')) + =>0 + + Also note that 'defn' with multiple arguments can only join text +macros, not builtins, although a future version of GNU M4 may lift this +restriction. + + $ m4 -d + define(`a', `A')define(`AA', `b') + => + traceon(`defn', `define') + => + defn(`a', `divnum', `a') + error->m4:stdin:3: Warning: cannot concatenate builtin `divnum' + error->m4trace: -1- defn(`a', `divnum', `a') -> ``A'`A'' + =>AA + define(`mydivnum', defn(`divnum', `divnum'))mydivnum + error->m4:stdin:4: Warning: cannot concatenate builtin `divnum' + error->m4:stdin:4: Warning: cannot concatenate builtin `divnum' + error->m4trace: -2- defn(`divnum', `divnum') + error->m4trace: -1- define(`mydivnum', `') + => + traceoff(`defn', `define') + => + + +File: m4.info, Node: Pushdef, Next: Indir, Prev: Defn, Up: Definitions + +5.6 Temporarily redefining macros +================================= + +It is possible to redefine a macro temporarily, reverting to the +previous definition at a later time. This is done with the builtins +'pushdef' and 'popdef': + + -- Builtin: pushdef (NAME, [EXPANSION] + -- Builtin: popdef (NAME...) + Analogous to 'define' and 'undefine'. + + These macros work in a stack-like fashion. A macro is temporarily + redefined with 'pushdef', which replaces an existing definition of + NAME, while saving the previous definition, before the new one is + installed. If there is no previous definition, 'pushdef' behaves + exactly like 'define'. + + If a macro has several definitions (of which only one is + accessible), the topmost definition can be removed with 'popdef'. + If there is no previous definition, 'popdef' behaves like + 'undefine'. + + The expansion of both 'pushdef' and 'popdef' is void. The macros + 'pushdef' and 'popdef' are recognized only with parameters. + + define(`foo', `Expansion one.') + => + foo + =>Expansion one. + pushdef(`foo', `Expansion two.') + => + foo + =>Expansion two. + pushdef(`foo', `Expansion three.') + => + pushdef(`foo', `Expansion four.') + => + popdef(`foo') + => + foo + =>Expansion three. + popdef(`foo', `foo') + => + foo + =>Expansion one. + popdef(`foo') + => + foo + =>foo + + If a macro with several definitions is redefined with 'define', the +topmost definition is _replaced_ with the new definition. If it is +removed with 'undefine', _all_ the definitions are removed, and not only +the topmost one. However, POSIX allows other implementations that treat +'define' as replacing an entire stack of definitions with a single new +definition, so to be portable to other implementations, it may be worth +explicitly using 'popdef' and 'pushdef' rather than relying on the GNU +behavior of 'define'. + + define(`foo', `Expansion one.') + => + foo + =>Expansion one. + pushdef(`foo', `Expansion two.') + => + foo + =>Expansion two. + define(`foo', `Second expansion two.') + => + foo + =>Second expansion two. + undefine(`foo') + => + foo + =>foo + + Local variables within macros are made with 'pushdef' and 'popdef'. +At the start of the macro a new definition is pushed, within the macro +it is manipulated and at the end it is popped, revealing the former +definition. + + It is possible to temporarily redefine a builtin with 'pushdef' and +'defn'. + + +File: m4.info, Node: Indir, Next: Builtin, Prev: Pushdef, Up: Definitions + +5.7 Indirect call of macros +=========================== + +Any macro can be called indirectly with 'indir': + + -- Builtin: indir (NAME, [ARGS...] + Results in a call to the macro NAME, which is passed the rest of + the arguments ARGS. If NAME is not defined, an error message is + printed, and the expansion is void. + + The macro 'indir' is recognized only with parameters. + + This can be used to call macros with computed or "invalid" names +('define' allows such names to be defined): + + define(`$$internal$macro', `Internal macro (name `$0')') + => + $$internal$macro + =>$$internal$macro + indir(`$$internal$macro') + =>Internal macro (name $$internal$macro) + + The point is, here, that larger macro packages can have private +macros defined, that will not be called by accident. They can _only_ be +called through the builtin 'indir'. + + One other point to observe is that argument collection occurs before +'indir' invokes NAME, so if argument collection changes the value of +NAME, that will be reflected in the final expansion. This is different +than the behavior when invoking macros directly, where the definition +that was in effect before argument collection is used. + + $ m4 -d + define(`f', `1') + => + f(define(`f', `2')) + =>1 + indir(`f', define(`f', `3')) + =>3 + indir(`f', undefine(`f')) + error->m4:stdin:4: undefined macro `f' + => + + When handed the result of 'defn' (*note Defn::) as one of its +arguments, 'indir' defers to the invoked NAME for whether a token +representing a builtin is recognized or flattened to the empty string. + + $ m4 -d + indir(defn(`defn'), `divnum') + error->m4:stdin:1: Warning: indir: invalid macro name ignored + => + indir(`define', defn(`defn'), `divnum') + error->m4:stdin:2: Warning: define: invalid macro name ignored + => + indir(`define', `foo', defn(`divnum')) + => + foo + =>0 + indir(`divert', defn(`foo')) + error->m4:stdin:5: empty string treated as 0 in builtin `divert' + => + + +File: m4.info, Node: Builtin, Prev: Indir, Up: Definitions + +5.8 Indirect call of builtins +============================= + +Builtin macros can be called indirectly with 'builtin': + + -- Builtin: builtin (NAME, [ARGS...] + Results in a call to the builtin NAME, which is passed the rest of + the arguments ARGS. If NAME does not name a builtin, an error + message is printed, and the expansion is void. + + The macro 'builtin' is recognized only with parameters. + + This can be used even if NAME has been given another definition that +has covered the original, or been undefined so that no macro maps to the +builtin. + + pushdef(`define', `hidden') + => + undefine(`undefine') + => + define(`foo', `bar') + =>hidden + foo + =>foo + builtin(`define', `foo', defn(`divnum')) + => + foo + =>0 + builtin(`define', `foo', `BAR') + => + foo + =>BAR + undefine(`foo') + =>undefine(foo) + foo + =>BAR + builtin(`undefine', `foo') + => + foo + =>foo + + The NAME argument only matches the original name of the builtin, even +when the '--prefix-builtins' option (or '-P', *note Invoking m4: +Operation modes.) is in effect. This is different from 'indir', which +only tracks current macro names. + + $ m4 -P + m4_builtin(`divnum') + =>0 + m4_builtin(`m4_divnum') + error->m4:stdin:2: undefined builtin `m4_divnum' + => + m4_indir(`divnum') + error->m4:stdin:3: undefined macro `divnum' + => + m4_indir(`m4_divnum') + =>0 + + Note that 'indir' and 'builtin' can be used to invoke builtins +without arguments, even when they normally require parameters to be +recognized; but it will provoke a warning, and result in a void +expansion. + + builtin + =>builtin + builtin() + error->m4:stdin:2: undefined builtin `' + => + builtin(`builtin') + error->m4:stdin:3: Warning: too few arguments to builtin `builtin' + => + builtin(`builtin',) + error->m4:stdin:4: undefined builtin `' + => + builtin(`builtin', ``' + ') + error->m4:stdin:5: undefined builtin ``' + error->' + => + indir(`index') + error->m4:stdin:7: Warning: too few arguments to builtin `index' + => + + +File: m4.info, Node: Conditionals, Next: Debugging, Prev: Definitions, Up: Top + +6 Conditionals, loops, and recursion +************************************ + +Macros, expanding to plain text, perhaps with arguments, are not quite +enough. We would like to have macros expand to different things, based +on decisions taken at run-time. For that, we need some kind of +conditionals. Also, we would like to have some kind of loop construct, +so we could do something a number of times, or while some condition is +true. + +* Menu: + +* Ifdef:: Testing if a macro is defined +* Ifelse:: If-else construct, or multibranch +* Shift:: Recursion in 'm4' +* Forloop:: Iteration by counting +* Foreach:: Iteration by list contents +* Stacks:: Working with definition stacks +* Composition:: Building macros with macros + + +File: m4.info, Node: Ifdef, Next: Ifelse, Up: Conditionals + +6.1 Testing if a macro is defined +================================= + +There are two different builtin conditionals in 'm4'. The first is +'ifdef': + + -- Builtin: ifdef (NAME, STRING-1, [STRING-2] + If NAME is defined as a macro, 'ifdef' expands to STRING-1, + otherwise to STRING-2. If STRING-2 is omitted, it is taken to be + the empty string (according to the normal rules). + + The macro 'ifdef' is recognized only with parameters. + + ifdef(`foo', ``foo' is defined', ``foo' is not defined') + =>foo is not defined + define(`foo', `') + => + ifdef(`foo', ``foo' is defined', ``foo' is not defined') + =>foo is defined + ifdef(`no_such_macro', `yes', `no', `extra argument') + error->m4:stdin:4: Warning: excess arguments to builtin `ifdef' ignored + =>no + + +File: m4.info, Node: Ifelse, Next: Shift, Prev: Ifdef, Up: Conditionals + +6.2 If-else construct, or multibranch +===================================== + +The other conditional, 'ifelse', is much more powerful. It can be used +as a way to introduce a long comment, as an if-else construct, or as a +multibranch, depending on the number of arguments supplied: + + -- Builtin: ifelse (COMMENT) + -- Builtin: ifelse (STRING-1, STRING-2, EQUAL, [NOT-EQUAL] + -- Builtin: ifelse (STRING-1, STRING-2, EQUAL-1, STRING-3, STRING-4, + EQUAL-2, ..., [NOT-EQUAL] + Used with only one argument, the 'ifelse' simply discards it and + produces no output. + + If called with three or four arguments, 'ifelse' expands into + EQUAL, if STRING-1 and STRING-2 are equal (character for + character), otherwise it expands to NOT-EQUAL. A final fifth + argument is ignored, after triggering a warning. + + If called with six or more arguments, and STRING-1 and STRING-2 are + equal, 'ifelse' expands into EQUAL-1, otherwise the first three + arguments are discarded and the processing starts again. + + The macro 'ifelse' is recognized only with parameters. + + Using only one argument is a common 'm4' idiom for introducing a +block comment, as an alternative to repeatedly using 'dnl'. This +special usage is recognized by GNU 'm4', so that in this case, the +warning about missing arguments is never triggered. + + ifelse(`some comments') + => + ifelse(`foo', `bar') + error->m4:stdin:2: Warning: too few arguments to builtin `ifelse' + => + + Using three or four arguments provides decision points. + + ifelse(`foo', `bar', `true') + => + ifelse(`foo', `foo', `true') + =>true + define(`foo', `bar') + => + ifelse(foo, `bar', `true', `false') + =>true + ifelse(foo, `foo', `true', `false') + =>false + + Notice how the first argument was used unquoted; it is common to +compare the expansion of a macro with a string. With this macro, you +can now reproduce the behavior of blind builtins, where the macro is +recognized only with arguments. + + define(`foo', `ifelse(`$#', `0', ``$0'', `arguments:$#')') + => + foo + =>foo + foo() + =>arguments:1 + foo(`a', `b', `c') + =>arguments:3 + + For an example of a way to make defining blind macros easier, see +*note Composition::. + + The macro 'ifelse' can take more than four arguments. If given more +than four arguments, 'ifelse' works like a 'case' or 'switch' statement +in traditional programming languages. If STRING-1 and STRING-2 are +equal, 'ifelse' expands into EQUAL-1, otherwise the procedure is +repeated with the first three arguments discarded. This calls for an +example: + + ifelse(`foo', `bar', `third', `gnu', `gnats') + error->m4:stdin:1: Warning: excess arguments to builtin `ifelse' ignored + =>gnu + ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth') + => + ifelse(`foo', `bar', `third', `gnu', `gnats', `sixth', `seventh') + =>seventh + ifelse(`foo', `bar', `3', `gnu', `gnats', `6', `7', `8') + error->m4:stdin:4: Warning: excess arguments to builtin `ifelse' ignored + =>7 + + Naturally, the normal case will be slightly more advanced than these +examples. A common use of 'ifelse' is in macros implementing loops of +various kinds. + + +File: m4.info, Node: Shift, Next: Forloop, Prev: Ifelse, Up: Conditionals + +6.3 Recursion in 'm4' +===================== + +There is no direct support for loops in 'm4', but macros can be +recursive. There is no limit on the number of recursion levels, other +than those enforced by your hardware and operating system. + + Loops can be programmed using recursion and the conditionals +described previously. + + There is a builtin macro, 'shift', which can, among other things, be +used for iterating through the actual arguments to a macro: + + -- Builtin: shift (ARG1, ...) + Takes any number of arguments, and expands to all its arguments + except ARG1, separated by commas, with each argument quoted. + + The macro 'shift' is recognized only with parameters. + + shift + =>shift + shift(`bar') + => + shift(`foo', `bar', `baz') + =>bar,baz + + An example of the use of 'shift' is this macro: + + -- Composite: reverse (...) + Takes any number of arguments, and reverses their order. + + It is implemented as: + + define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'', + `reverse(shift($@)), `$1'')') + => + reverse + => + reverse(`foo') + =>foo + reverse(`foo', `bar', `gnats', `and gnus') + =>and gnus, gnats, bar, foo + + While not a very interesting macro, it does show how simple loops can +be made with 'shift', 'ifelse' and recursion. It also shows that +'shift' is usually used with '$@'. Another example of this is an +implementation of a short-circuiting conditional operator. + + -- Composite: cond (TEST-1, STRING-1, EQUAL-1, [TEST-2] + Similar to 'ifelse', where an equal comparison between the first + two strings results in the third, otherwise the first three + arguments are discarded and the process repeats. The difference is + that each TEST-<N> is expanded only when it is encountered. This + means that every third argument to 'cond' is normally given one + more level of quoting than the corresponding argument to 'ifelse'. + + Here is the implementation of 'cond', along with a demonstration of +how it can short-circuit the side effects in 'side'. Notice how all the +unquoted side effects happen regardless of how many comparisons are made +with 'ifelse', compared with only the relevant effects with 'cond'. + + define(`cond', + `ifelse(`$#', `1', `$1', + `ifelse($1, `$2', `$3', + `$0(shift(shift(shift($@))))')')')dnl + define(`side', `define(`counter', incr(counter))$1')dnl + define(`example1', + `define(`counter', `0')dnl + ifelse(side(`$1'), `yes', `one comparison: ', + side(`$1'), `no', `two comparisons: ', + side(`$1'), `maybe', `three comparisons: ', + `side(`default answer: ')')counter')dnl + define(`example2', + `define(`counter', `0')dnl + cond(`side(`$1')', `yes', `one comparison: ', + `side(`$1')', `no', `two comparisons: ', + `side(`$1')', `maybe', `three comparisons: ', + `side(`default answer: ')')counter')dnl + example1(`yes') + =>one comparison: 3 + example1(`no') + =>two comparisons: 3 + example1(`maybe') + =>three comparisons: 3 + example1(`feeling rather indecisive today') + =>default answer: 4 + example2(`yes') + =>one comparison: 1 + example2(`no') + =>two comparisons: 2 + example2(`maybe') + =>three comparisons: 3 + example2(`feeling rather indecisive today') + =>default answer: 4 + + Another common task that requires iteration is joining a list of +arguments into a single string. + + -- Composite: join ([SEPARATOR] + -- Composite: joinall ([SEPARATOR] + Generate a single-quoted string, consisting of each ARG separated + by SEPARATOR. While 'joinall' always outputs a SEPARATOR between + arguments, 'join' avoids the SEPARATOR for an empty ARG. + + Here are some examples of its usage, based on the implementation +'m4-1.4.17/examples/join.m4' distributed in this package: + + $ m4 -I examples + include(`join.m4') + => + join,join(`-'),join(`-', `'),join(`-', `', `') + =>,,, + joinall,joinall(`-'),joinall(`-', `'),joinall(`-', `', `') + =>,,,- + join(`-', `1') + =>1 + join(`-', `1', `2', `3') + =>1-2-3 + join(`', `1', `2', `3') + =>123 + join(`-', `', `1', `', `', `2', `') + =>1-2 + joinall(`-', `', `1', `', `', `2', `') + =>-1---2- + join(`,', `1', `2', `3') + =>1,2,3 + define(`nargs', `$#')dnl + nargs(join(`,', `1', `2', `3')) + =>1 + + Examining the implementation shows some interesting points about +several m4 programming idioms. + + $ m4 -I examples + undivert(`join.m4')dnl + =>divert(`-1') + =># join(sep, args) - join each non-empty ARG into a single + =># string, with each element separated by SEP + =>define(`join', + =>`ifelse(`$#', `2', ``$2'', + => `ifelse(`$2', `', `', ``$2'_')$0(`$1', shift(shift($@)))')') + =>define(`_join', + =>`ifelse(`$#$2', `2', `', + => `ifelse(`$2', `', `', ``$1$2'')$0(`$1', shift(shift($@)))')') + =># joinall(sep, args) - join each ARG, including empty ones, + =># into a single string, with each element separated by SEP + =>define(`joinall', ``$2'_$0(`$1', shift($@))') + =>define(`_joinall', + =>`ifelse(`$#', `2', `', ``$1$3'$0(`$1', shift(shift($@)))')') + =>divert`'dnl + + First, notice that this implementation creates helper macros '_join' +and '_joinall'. This division of labor makes it easier to output the +correct number of SEPARATOR instances: 'join' and 'joinall' are +responsible for the first argument, without a separator, while '_join' +and '_joinall' are responsible for all remaining arguments, always +outputting a separator when outputting an argument. + + Next, observe how 'join' decides to iterate to itself, because the +first ARG was empty, or to output the argument and swap over to '_join'. +If the argument is non-empty, then the nested 'ifelse' results in an +unquoted '_', which is concatenated with the '$0' to form the next macro +name to invoke. The 'joinall' implementation is simpler since it does +not have to suppress empty ARG; it always executes once then defers to +'_joinall'. + + Another important idiom is the idea that SEPARATOR is reused for each +iteration. Each iteration has one less argument, but rather than +discarding '$1' by iterating with '$0(shift($@))', the macro discards +'$2' by using '$0(`$1', shift(shift($@)))'. + + Next, notice that it is possible to compare more than one condition +in a single 'ifelse' test. The test of '$#$2' against '2' allows +'_join' to iterate for two separate reasons--either there are still more +than two arguments, or there are exactly two arguments but the last +argument is not empty. + + Finally, notice that these macros require exactly two arguments to +terminate recursion, but that they still correctly result in empty +output when given no ARGS (i.e., zero or one macro argument). On the +first pass when there are too few arguments, the 'shift' results in no +output, but leaves an empty string to serve as the required second +argument for the second pass. Put another way, '`$1', shift($@)' is not +the same as '$@', since only the former guarantees at least two +arguments. + + Sometimes, a recursive algorithm requires adding quotes to each +element, or treating multiple arguments as a single element: + + -- Composite: quote (...) + -- Composite: dquote (...) + -- Composite: dquote_elt (...) + Takes any number of arguments, and adds quoting. With 'quote', + only one level of quoting is added, effectively removing whitespace + after commas and turning multiple arguments into a single string. + With 'dquote', two levels of quoting are added, one around each + element, and one around the list. And with 'dquote_elt', two + levels of quoting are added around each element. + + An actual implementation of these three macros is distributed as +'m4-1.4.17/examples/quote.m4' in this package. First, let's examine +their usage: + + $ m4 -I examples + include(`quote.m4') + => + -quote-dquote-dquote_elt- + =>---- + -quote()-dquote()-dquote_elt()- + =>--`'-`'- + -quote(`1')-dquote(`1')-dquote_elt(`1')- + =>-1-`1'-`1'- + -quote(`1', `2')-dquote(`1', `2')-dquote_elt(`1', `2')- + =>-1,2-`1',`2'-`1',`2'- + define(`n', `$#')dnl + -n(quote(`1', `2'))-n(dquote(`1', `2'))-n(dquote_elt(`1', `2'))- + =>-1-1-2- + dquote(dquote_elt(`1', `2')) + =>``1'',``2'' + dquote_elt(dquote(`1', `2')) + =>``1',`2'' + + The last two lines show that when given two arguments, 'dquote' +results in one string, while 'dquote_elt' results in two. Now, examine +the implementation. Note that 'quote' and 'dquote_elt' make decisions +based on their number of arguments, so that when called without +arguments, they result in nothing instead of a quoted empty string; this +is so that it is possible to distinguish between no arguments and an +empty first argument. 'dquote', on the other hand, results in a string +no matter what, since it is still possible to tell whether it was +invoked without arguments based on the resulting string. + + $ m4 -I examples + undivert(`quote.m4')dnl + =>divert(`-1') + =># quote(args) - convert args to single-quoted string + =>define(`quote', `ifelse(`$#', `0', `', ``$*'')') + =># dquote(args) - convert args to quoted list of quoted strings + =>define(`dquote', ``$@'') + =># dquote_elt(args) - convert args to list of double-quoted strings + =>define(`dquote_elt', `ifelse(`$#', `0', `', `$#', `1', ```$1''', + => ```$1'',$0(shift($@))')') + =>divert`'dnl + + It is worth pointing out that 'quote(ARGS)' is more efficient than +'joinall(`,', ARGS)' for producing the same output. + + One more useful macro based on 'shift' allows portably selecting an +arbitrary argument (usually greater than the ninth argument), without +relying on the GNU extension of multi-digit arguments (*note +Arguments::). + + -- Composite: argn (N, ...) + Expands to argument N out of the remaining arguments. N must be a + positive number. Usually invoked as 'argn(`N',$@)'. + + It is implemented as: + + define(`argn', `ifelse(`$1', 1, ``$2'', + `argn(decr(`$1'), shift(shift($@)))')') + => + argn(`1', `a') + =>a + define(`foo', `argn(`11', $@)') + => + foo(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k', `l') + =>k + + +File: m4.info, Node: Forloop, Next: Foreach, Prev: Shift, Up: Conditionals + +6.4 Iteration by counting +========================= + +Here is an example of a loop macro that implements a simple for loop. + + -- Composite: forloop (ITERATOR, START, END, TEXT) + Takes the name in ITERATOR, which must be a valid macro name, and + successively assign it each integer value from START to END, + inclusive. For each assignment to ITERATOR, append TEXT to the + expansion of the 'forloop'. TEXT may refer to ITERATOR. Any + definition of ITERATOR prior to this invocation is restored. + + It can, for example, be used for simple counting: + + $ m4 -I examples + include(`forloop.m4') + => + forloop(`i', `1', `8', `i ') + =>1 2 3 4 5 6 7 8 + + For-loops can be nested, like: + + $ m4 -I examples + include(`forloop.m4') + => + forloop(`i', `1', `4', `forloop(`j', `1', `8', ` (i, j)') + ') + => (1, 1) (1, 2) (1, 3) (1, 4) (1, 5) (1, 6) (1, 7) (1, 8) + => (2, 1) (2, 2) (2, 3) (2, 4) (2, 5) (2, 6) (2, 7) (2, 8) + => (3, 1) (3, 2) (3, 3) (3, 4) (3, 5) (3, 6) (3, 7) (3, 8) + => (4, 1) (4, 2) (4, 3) (4, 4) (4, 5) (4, 6) (4, 7) (4, 8) + => + + The implementation of the 'forloop' macro is fairly straightforward. +The 'forloop' macro itself is simply a wrapper, which saves the previous +definition of the first argument, calls the internal macro '_forloop', +and re-establishes the saved definition of the first argument. + + The macro '_forloop' expands the fourth argument once, and tests to +see if the iterator has reached the final value. If it has not +finished, it increments the iterator (using the predefined macro 'incr', +*note Incr::), and recurses. + + Here is an actual implementation of 'forloop', distributed as +'m4-1.4.17/examples/forloop.m4' in this package: + + $ m4 -I examples + undivert(`forloop.m4')dnl + =>divert(`-1') + =># forloop(var, from, to, stmt) - simple version + =>define(`forloop', `pushdef(`$1', `$2')_forloop($@)popdef(`$1')') + =>define(`_forloop', + => `$4`'ifelse($1, `$3', `', `define(`$1', incr($1))$0($@)')') + =>divert`'dnl + + Notice the careful use of quotes. Certain macro arguments are left +unquoted, each for its own reason. Try to find out _why_ these +arguments are left unquoted, and see what happens if they are quoted. +(As presented, these two macros are useful but not very robust for +general use. They lack even basic error handling for cases like START +less than END, END not numeric, or ITERATOR not being a macro name. See +if you can improve these macros; or *note Answers: Improved forloop.). + + +File: m4.info, Node: Foreach, Next: Stacks, Prev: Forloop, Up: Conditionals + +6.5 Iteration by list contents +============================== + +Here is an example of a loop macro that implements list iteration. + + -- Composite: foreach (ITERATOR, PAREN-LIST, TEXT) + -- Composite: foreachq (ITERATOR, QUOTE-LIST, TEXT) + Takes the name in ITERATOR, which must be a valid macro name, and + successively assign it each value from PAREN-LIST or QUOTE-LIST. + In 'foreach', PAREN-LIST is a comma-separated list of elements + contained in parentheses. In 'foreachq', QUOTE-LIST is a + comma-separated list of elements contained in a quoted string. For + each assignment to ITERATOR, append TEXT to the overall expansion. + TEXT may refer to ITERATOR. Any definition of ITERATOR prior to + this invocation is restored. + + As an example, this displays each word in a list inside of a +sentence, using an implementation of 'foreach' distributed as +'m4-1.4.17/examples/foreach.m4', and 'foreachq' in +'m4-1.4.17/examples/foreachq.m4'. + + $ m4 -I examples + include(`foreach.m4') + => + foreach(`x', (foo, bar, foobar), `Word was: x + ')dnl + =>Word was: foo + =>Word was: bar + =>Word was: foobar + include(`foreachq.m4') + => + foreachq(`x', `foo, bar, foobar', `Word was: x + ')dnl + =>Word was: foo + =>Word was: bar + =>Word was: foobar + + It is possible to be more complex; each element of the PAREN-LIST or +QUOTE-LIST can itself be a list, to pass as further arguments to a +helper macro. This example generates a shell case statement: + + $ m4 -I examples + include(`foreach.m4') + => + define(`_case', ` $1) + $2=" $1";; + ')dnl + define(`_cat', `$1$2')dnl + case $`'1 in + =>case $1 in + foreach(`x', `(`(`a', `vara')', `(`b', `varb')', `(`c', `varc')')', + `_cat(`_case', x)')dnl + => a) + => vara=" a";; + => b) + => varb=" b";; + => c) + => varc=" c";; + esac + =>esac + + The implementation of the 'foreach' macro is a bit more involved; it +is a wrapper around two helper macros. First, '_arg1' is needed to grab +the first element of a list. Second, '_foreach' implements the +recursion, successively walking through the original list. Here is a +simple implementation of 'foreach': + + $ m4 -I examples + undivert(`foreach.m4')dnl + =>divert(`-1') + =># foreach(x, (item_1, item_2, ..., item_n), stmt) + =># parenthesized list, simple version + =>define(`foreach', `pushdef(`$1')_foreach($@)popdef(`$1')') + =>define(`_arg1', `$1') + =>define(`_foreach', `ifelse(`$2', `()', `', + => `define(`$1', _arg1$2)$3`'$0(`$1', (shift$2), `$3')')') + =>divert`'dnl + + Unfortunately, that implementation is not robust to macro names as +list elements. Each iteration of '_foreach' is stripping another layer +of quotes, leading to erratic results if list elements are not already +fully expanded. The first cut at implementing 'foreachq' takes this +into account. Also, when using quoted elements in a PAREN-LIST, the +overall list must be quoted. A QUOTE-LIST has the nice property of +requiring fewer characters to create a list containing the same quoted +elements. To see the difference between the two macros, we attempt to +pass double-quoted macro names in a list, expecting the macro name on +output after one layer of quotes is removed during list iteration and +the final layer removed during the final rescan: + + $ m4 -I examples + define(`a', `1')define(`b', `2')define(`c', `3') + => + include(`foreach.m4') + => + include(`foreachq.m4') + => + foreach(`x', `(``a'', ``(b'', ``c)'')', `x + ') + =>1 + =>(2)1 + => + =>, x + =>) + foreachq(`x', ```a'', ``(b'', ``c)''', `x + ')dnl + =>a + =>(b + =>c) + + Obviously, 'foreachq' did a better job; here is its implementation: + + $ m4 -I examples + undivert(`foreachq.m4')dnl + =>include(`quote.m4')dnl + =>divert(`-1') + =># foreachq(x, `item_1, item_2, ..., item_n', stmt) + =># quoted list, simple version + =>define(`foreachq', `pushdef(`$1')_foreachq($@)popdef(`$1')') + =>define(`_arg1', `$1') + =>define(`_foreachq', `ifelse(quote($2), `', `', + => `define(`$1', `_arg1($2)')$3`'$0(`$1', `shift($2)', `$3')')') + =>divert`'dnl + + Notice that '_foreachq' had to use the helper macro 'quote' defined +earlier (*note Shift::), to ensure that the embedded 'ifelse' call does +not go haywire if a list element contains a comma. Unfortunately, this +implementation of 'foreachq' has its own severe flaw. Whereas the +'foreach' implementation was linear, this macro is quadratic in the +number of list elements, and is much more likely to trip up the limit +set by the command line option '--nesting-limit' (or '-L', *note +Invoking m4: Limits control.). Additionally, this implementation does +not expand 'defn(`ITERATOR')' very well, when compared with 'foreach'. + + $ m4 -I examples + include(`foreach.m4')include(`foreachq.m4') + => + foreach(`name', `(`a', `b')', ` defn(`name')') + => a b + foreachq(`name', ``a', `b'', ` defn(`name')') + => _arg1(`a', `b') _arg1(shift(`a', `b')) + + It is possible to have robust iteration with linear behavior and sane +ITERATOR contents for either list style. See if you can learn from the +best elements of both of these implementations to create robust macros +(or *note Answers: Improved foreach.). + + +File: m4.info, Node: Stacks, Next: Composition, Prev: Foreach, Up: Conditionals + +6.6 Working with definition stacks +================================== + +Thanks to 'pushdef', manipulation of a stack is an intrinsic operation +in 'm4'. Normally, only the topmost definition in a stack is important, +but sometimes, it is desirable to manipulate the entire definition +stack. + + -- Composite: stack_foreach (MACRO, ACTION) + -- Composite: stack_foreach_lifo (MACRO, ACTION) + For each of the 'pushdef' definitions associated with MACRO, invoke + the macro ACTION with a single argument of that definition. + 'stack_foreach' visits the oldest definition first, while + 'stack_foreach_lifo' visits the current definition first. ACTION + should not modify or dereference MACRO. There are a few special + macros, such as 'defn', which cannot be used as the MACRO + parameter. + + A sample implementation of these macros is distributed in the file +'m4-1.4.17/examples/stack.m4'. + + $ m4 -I examples + include(`stack.m4') + => + pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3') + => + define(`show', ``$1' + ') + => + stack_foreach(`a', `show')dnl + =>1 + =>2 + =>3 + stack_foreach_lifo(`a', `show')dnl + =>3 + =>2 + =>1 + + Now for the implementation. Note the definition of a helper macro, +'_stack_reverse', which destructively swaps the contents of one stack of +definitions into the reverse order in the temporary macro 'tmp-$1'. By +calling the helper twice, the original order is restored back into the +macro '$1'; since the operation is destructive, this explains why '$1' +must not be modified or dereferenced during the traversal. The caller +can then inject additional code to pass the definition currently being +visited to '$2'. The choice of helper names is intentional; since '-' +is not valid as part of a macro name, there is no risk of conflict with +a valid macro name, and the code is guaranteed to use 'defn' where +necessary. Finally, note that any macro used in the traversal of a +'pushdef' stack, such as 'pushdef' or 'defn', cannot be handled by +'stack_foreach', since the macro would temporarily be undefined during +the algorithm. + + $ m4 -I examples + undivert(`stack.m4')dnl + =>divert(`-1') + =># stack_foreach(macro, action) + =># Invoke ACTION with a single argument of each definition + =># from the definition stack of MACRO, starting with the oldest. + =>define(`stack_foreach', + =>`_stack_reverse(`$1', `tmp-$1')'dnl + =>`_stack_reverse(`tmp-$1', `$1', `$2(defn(`$1'))')') + =># stack_foreach_lifo(macro, action) + =># Invoke ACTION with a single argument of each definition + =># from the definition stack of MACRO, starting with the newest. + =>define(`stack_foreach_lifo', + =>`_stack_reverse(`$1', `tmp-$1', `$2(defn(`$1'))')'dnl + =>`_stack_reverse(`tmp-$1', `$1')') + =>define(`_stack_reverse', + =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0($@)')') + =>divert`'dnl + + +File: m4.info, Node: Composition, Prev: Stacks, Up: Conditionals + +6.7 Building macros with macros +=============================== + +Since m4 is a macro language, it is possible to write macros that can +build other macros. First on the list is a way to automate the creation +of blind macros. + + -- Composite: define_blind (NAME, [VALUE] + Defines NAME as a blind macro, such that NAME will expand to VALUE + only when given explicit arguments. VALUE should not be the result + of 'defn' (*note Defn::). This macro is only recognized with + parameters, and results in an empty string. + + Defining a macro to define another macro can be a bit tricky. We +want to use a literal '$#' in the argument to the nested 'define'. +However, if '$' and '#' are adjacent in the definition of +'define_blind', then it would be expanded as the number of arguments to +'define_blind' rather than the intended number of arguments to NAME. +The solution is to pass the difficult characters through extra arguments +to a helper macro '_define_blind'. When composing macros, it is a +common idiom to need a helper macro to concatenate text that forms +parameters in the composed macro, rather than interpreting the text as a +parameter of the composing macro. + + As for the limitation against using 'defn', there are two reasons. +If a macro was previously defined with 'define_blind', then it can +safely be renamed to a new blind macro using plain 'define'; using +'define_blind' to rename it just adds another layer of 'ifelse', +occupying memory and slowing down execution. And if a macro is a +builtin, then it would result in an attempt to define a macro consisting +of both text and a builtin token; this is not supported, and the builtin +token is flattened to an empty string. + + With that explanation, here's the definition, and some sample usage. +Notice that 'define_blind' is itself a blind macro. + + $ m4 -d + define(`define_blind', `ifelse(`$#', `0', ``$0'', + `_$0(`$1', `$2', `$'`#', `$'`0')')') + => + define(`_define_blind', `define(`$1', + `ifelse(`$3', `0', ``$4'', `$2')')') + => + define_blind + =>define_blind + define_blind(`foo', `arguments were $*') + => + foo + =>foo + foo(`bar') + =>arguments were bar + define(`blah', defn(`foo')) + => + blah + =>blah + blah(`a', `b') + =>arguments were a,b + defn(`blah') + =>ifelse(`$#', `0', ``$0'', `arguments were $*') + + Another interesting composition tactic is argument "currying", or +factoring a macro that takes multiple arguments for use in a context +that provides exactly one argument. + + -- Composite: curry (MACRO, ...) + Expand to a macro call that takes exactly one argument, then + appends that argument to the original arguments and invokes MACRO + with the resulting list of arguments. + + A demonstration of currying makes the intent of this macro a little +more obvious. The macro 'stack_foreach' mentioned earlier is an example +of a context that provides exactly one argument to a macro name. But +coupled with currying, we can invoke 'reverse' with two arguments for +each definition of a macro stack. This example uses the file +'m4-1.4.17/examples/curry.m4' included in the distribution. + + $ m4 -I examples + include(`curry.m4')include(`stack.m4') + => + define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'', + `reverse(shift($@)), `$1'')') + => + pushdef(`a', `1')pushdef(`a', `2')pushdef(`a', `3') + => + stack_foreach(`a', `:curry(`reverse', `4')') + =>:1, 4:2, 4:3, 4 + curry(`curry', `reverse', `1')(`2')(`3') + =>3, 2, 1 + + Now for the implementation. Notice how 'curry' leaves off with a +macro name but no open parenthesis, while still in the middle of +collecting arguments for '$1'. The macro '_curry' is the helper macro +that takes one argument, then adds it to the list and finally supplies +the closing parenthesis. The use of a comma inside the 'shift' call +allows currying to also work for a macro that takes one argument, +although it often makes more sense to invoke that macro directly rather +than going through 'curry'. + + $ m4 -I examples + undivert(`curry.m4')dnl + =>divert(`-1') + =># curry(macro, args) + =># Expand to a macro call that takes one argument, then invoke + =># macro(args, extra). + =>define(`curry', `$1(shift($@,)_$0') + =>define(`_curry', ``$1')') + =>divert`'dnl + + Unfortunately, with M4 1.4.x, 'curry' is unable to handle builtin +tokens, which are silently flattened to the empty string when passed +through another text macro. This limitation will be lifted in a future +release of M4. + + Putting the last few concepts together, it is possible to copy or +rename an entire stack of macro definitions. + + -- Composite: copy (SOURCE, DEST) + -- Composite: rename (SOURCE, DEST) + Ensure that DEST is undefined, then define it to the same stack of + definitions currently in SOURCE. 'copy' leaves SOURCE unchanged, + while 'rename' undefines SOURCE. There are only a few macros, such + as 'copy' or 'defn', which cannot be copied via this macro. + + The implementation is relatively straightforward (although since it +uses 'curry', it is unable to copy builtin macros, such as the second +definition of 'a' as a synonym for 'divnum'. See if you can design a +version that works around this limitation, or *note Answers: Improved +copy.). + + $ m4 -I examples + include(`curry.m4')include(`stack.m4') + => + define(`rename', `copy($@)undefine(`$1')')dnl + define(`copy', `ifdef(`$2', `errprint(`$2 already defined + ')m4exit(`1')', + `stack_foreach(`$1', `curry(`pushdef', `$2')')')')dnl + pushdef(`a', `1')pushdef(`a', defn(`divnum'))pushdef(`a', `2') + => + copy(`a', `b') + => + rename(`b', `c') + => + a b c + =>2 b 2 + popdef(`a', `c')c a + => 0 + popdef(`a', `c')a c + =>1 1 + + +File: m4.info, Node: Debugging, Next: Input Control, Prev: Conditionals, Up: Top + +7 How to debug macros and input +******************************* + +When writing macros for 'm4', they often do not work as intended on the +first try (as is the case with most programming languages). +Fortunately, there is support for macro debugging in 'm4'. + +* Menu: + +* Dumpdef:: Displaying macro definitions +* Trace:: Tracing macro calls +* Debug Levels:: Controlling debugging output +* Debug Output:: Saving debugging output + + +File: m4.info, Node: Dumpdef, Next: Trace, Up: Debugging + +7.1 Displaying macro definitions +================================ + +If you want to see what a name expands into, you can use the builtin +'dumpdef': + + -- Builtin: dumpdef ([NAMES...] + Accepts any number of arguments. If called without any arguments, + it displays the definitions of all known names, otherwise it + displays the definitions of the NAMES given. The output is printed + to the current debug file (usually standard error), and is sorted + by name. If an unknown name is encountered, a warning is printed. + + The expansion of 'dumpdef' is void. + + $ m4 -d + define(`foo', `Hello world.') + => + dumpdef(`foo') + error->foo: => + dumpdef(`define') + error->define: => + + The last example shows how builtin macros definitions are displayed. +The definition that is dumped corresponds to what would occur if the +macro were to be called at that point, even if other definitions are +still live due to redefining a macro during argument collection. + + $ m4 -d + pushdef(`f', ``$0'1')pushdef(`f', ``$0'2') + => + f(popdef(`f')dumpdef(`f')) + error->f: =>f2 + f(popdef(`f')dumpdef(`f')) + error->m4:stdin:3: undefined macro `f' + =>f1 + + *Note Debug Levels::, for information on controlling the details of +the display. + + +File: m4.info, Node: Trace, Next: Debug Levels, Prev: Dumpdef, Up: Debugging + +7.2 Tracing macro calls +======================= + +It is possible to trace macro calls and expansions through the builtins +'traceon' and 'traceoff': + + -- Builtin: traceon ([NAMES...] + -- Builtin: traceoff ([NAMES...] + When called without any arguments, 'traceon' and 'traceoff' will + turn tracing on and off, respectively, for all currently defined + macros. + + When called with arguments, only the macros listed in NAMES are + affected, whether or not they are currently defined. + + The expansion of 'traceon' and 'traceoff' is void. + + Whenever a traced macro is called and the arguments have been +collected, the call is displayed. If the expansion of the macro call is +not void, the expansion can be displayed after the call. The output is +printed to the current debug file (defaulting to standard error, *note +Debug Output::). + + $ m4 -d + define(`foo', `Hello World.') + => + define(`echo', `$@') + => + traceon(`foo', `echo') + => + foo + error->m4trace: -1- foo -> `Hello World.' + =>Hello World. + echo(`gnus', `and gnats') + error->m4trace: -1- echo(`gnus', `and gnats') -> ``gnus',`and gnats'' + =>gnus,and gnats + + The number between dashes is the depth of the expansion. It is one +most of the time, signifying an expansion at the outermost level, but it +increases when macro arguments contain unquoted macro calls. The +maximum number that will appear between dashes is controlled by the +option '--nesting-limit' (or '-L', *note Invoking m4: Limits control.). +Additionally, the option '--trace' (or '-t') can be used to invoke +'traceon(NAME)' before parsing input. + + $ m4 -L 3 -t ifelse + ifelse(`one level') + error->m4trace: -1- ifelse + => + ifelse(ifelse(ifelse(`three levels'))) + error->m4trace: -3- ifelse + error->m4trace: -2- ifelse + error->m4trace: -1- ifelse + => + ifelse(ifelse(ifelse(ifelse(`four levels')))) + error->m4:stdin:3: recursion limit of 3 exceeded, use -L<N> to change it + + Tracing by name is an attribute that is preserved whether the macro +is defined or not. This allows the selection of macros to trace before +those macros are defined. + + $ m4 -d + traceoff(`foo') + => + traceon(`foo') + => + foo + =>foo + defn(`foo') + => + define(`foo', `bar') + => + foo + error->m4trace: -1- foo -> `bar' + =>bar + undefine(`foo') + => + ifdef(`foo', `yes', `no') + =>no + indir(`foo') + error->m4:stdin:9: undefined macro `foo' + => + define(`foo', `blah') + => + foo + error->m4trace: -1- foo -> `blah' + =>blah + traceoff + => + foo + =>blah + + Tracing even works on builtins. However, 'defn' (*note Defn::) does +not transfer tracing status. + + $ m4 -d + traceon(`traceon') + => + traceon(`traceoff') + error->m4trace: -1- traceon(`traceoff') + => + traceoff(`traceoff') + error->m4trace: -1- traceoff(`traceoff') + => + traceoff(`traceon') + => + traceon(`eval', `m4_divnum') + => + define(`m4_eval', defn(`eval')) + => + define(`m4_divnum', defn(`divnum')) + => + eval(divnum) + error->m4trace: -1- eval(`0') -> `0' + =>0 + m4_eval(m4_divnum) + error->m4trace: -2- m4_divnum -> `0' + =>0 + + *Note Debug Levels::, for information on controlling the details of +the display. The format of the trace output is not specified by POSIX, +and varies between implementations of 'm4'. + + +File: m4.info, Node: Debug Levels, Next: Debug Output, Prev: Trace, Up: Debugging + +7.3 Controlling debugging output +================================ + +The '-d' option to 'm4' (or '--debug', *note Invoking m4: Debugging +options.) controls the amount of details presented in three categories +of output. Trace output is requested by 'traceon' (*note Trace::), and +each line is prefixed by 'm4trace:' in relation to a macro invocation. +Debug output tracks useful events not associated with a macro +invocation, and each line is prefixed by 'm4debug:'. Finally, 'dumpdef' +(*note Dumpdef::) output is affected, with no prefix added to the output +lines. + + The FLAGS following the option can be one or more of the following: + +'a' + In trace output, show the actual arguments that were collected + before invoking the macro. This applies to all macro calls if the + 't' flag is used, otherwise only the macros covered by calls of + 'traceon'. Arguments are subject to length truncation specified by + the command line option '--arglength' (or '-l'). + +'c' + In trace output, show several trace lines for each macro call. A + line is shown when the macro is seen, but before the arguments are + collected; a second line when the arguments have been collected and + a third line after the call has completed. + +'e' + In trace output, show the expansion of each macro call, if it is + not void. This applies to all macro calls if the 't' flag is used, + otherwise only the macros covered by calls of 'traceon'. The + expansion is subject to length truncation specified by the command + line option '--arglength' (or '-l'). + +'f' + In debug and trace output, include the name of the current input + file in the output line. + +'i' + In debug output, print a message each time the current input file + is changed. + +'l' + In debug and trace output, include the current input line number in + the output line. + +'p' + In debug output, print a message when a named file is found through + the path search mechanism (*note Search Path::), giving the actual + file name used. + +'q' + In trace and dumpdef output, quote actual arguments and macro + expansions in the display with the current quotes. This is useful + in connection with the 'a' and 'e' flags above. + +'t' + In trace output, trace all macro calls made in this invocation of + 'm4', regardless of the settings of 'traceon'. + +'x' + In trace output, add a unique 'macro call id' to each line of the + trace output. This is useful in connection with the 'c' flag + above. + +'V' + A shorthand for all of the above flags. + + If no flags are specified with the '-d' option, the default is 'aeq'. +The examples throughout this manual assume the default flags. + + There is a builtin macro 'debugmode', which allows on-the-fly control +of the debugging output format: + + -- Builtin: debugmode ([FLAGS] + The argument FLAGS should be a subset of the letters listed above. + As special cases, if the argument starts with a '+', the flags are + added to the current debug flags, and if it starts with a '-', they + are removed. If no argument is present, all debugging flags are + cleared (as if no '-d' was given), and with an empty argument the + flags are reset to the default of 'aeq'. + + The expansion of 'debugmode' is void. + + $ m4 + define(`foo', `FOO') + => + traceon(`foo') + => + debugmode() + => + foo + error->m4trace: -1- foo -> `FOO' + =>FOO + debugmode + => + foo + error->m4trace: -1- foo + =>FOO + debugmode(`+l') + => + foo + error->m4trace:8: -1- foo + =>FOO + + The following example demonstrates the behavior of length truncation, +when specified on the command line. Note that each argument and the +final result are individually truncated. Also, the special tokens for +builtin functions are not truncated. + + $ m4 -d -l 6 + define(`echo', `$@')debugmode(`+t') + => + echo(`1', `long string') + error->m4trace: -1- echo(`1', `long s...') -> ``1',`l...' + =>1,long string + indir(`echo', defn(`changequote')) + error->m4trace: -2- defn(`change...') + error->m4trace: -1- indir(`echo', <changequote>) -> ``'' + => + + This example shows the effects of the debug flags that are not +related to macro tracing. + + $ m4 -dip -I examples + error->m4debug: input read from stdin + include(`foo')dnl + error->m4debug: path search for `foo' found `examples/foo' + error->m4debug: input read from examples/foo + =>bar + error->m4debug: input reverted to stdin, line 1 + ^D + error->m4debug: input exhausted + + +File: m4.info, Node: Debug Output, Prev: Debug Levels, Up: Debugging + +7.4 Saving debugging output +=========================== + +Debug and tracing output can be redirected to files using either the +'--debugfile' option to 'm4' (*note Invoking m4: Debugging options.), or +with the builtin macro 'debugfile': + + -- Builtin: debugfile ([FILE] + Sends all further debug and trace output to FILE, opened in append + mode. If FILE is the empty string, debug and trace output are + discarded. If 'debugfile' is called without any arguments, debug + and trace output are sent to standard error. This does not affect + warnings, error messages, or 'errprint' output, which are always + sent to standard error. If FILE cannot be opened, the current + debug file is unchanged, and an error is issued. + + The expansion of 'debugfile' is void. + + $ m4 -d + traceon(`divnum') + => + divnum(`extra') + error->m4:stdin:2: Warning: excess arguments to builtin `divnum' ignored + error->m4trace: -1- divnum(`extra') -> `0' + =>0 + debugfile() + => + divnum(`extra') + error->m4:stdin:4: Warning: excess arguments to builtin `divnum' ignored + =>0 + debugfile + => + divnum + error->m4trace: -1- divnum -> `0' + =>0 + + +File: m4.info, Node: Input Control, Next: File Inclusion, Prev: Debugging, Up: Top + +8 Input control +*************** + +This chapter describes various builtin macros for controlling the input +to 'm4'. + +* Menu: + +* Dnl:: Deleting whitespace in input +* Changequote:: Changing the quote characters +* Changecom:: Changing the comment delimiters +* Changeword:: Changing the lexical structure of words +* M4wrap:: Saving text until end of input + + +File: m4.info, Node: Dnl, Next: Changequote, Up: Input Control + +8.1 Deleting whitespace in input +================================ + +The builtin 'dnl' stands for "Discard to Next Line": + + -- Builtin: dnl + All characters, up to and including the next newline, are discarded + without performing any macro expansion. A warning is issued if the + end of the file is encountered without a newline. + + The expansion of 'dnl' is void. + + It is often used in connection with 'define', to remove the newline +that follows the call to 'define'. Thus + + define(`foo', `Macro `foo'.')dnl A very simple macro, indeed. + foo + =>Macro foo. + + The input up to and including the next newline is discarded, as +opposed to the way comments are treated (*note Comments::). + + Usually, 'dnl' is immediately followed by an end of line or some +other whitespace. GNU 'm4' will produce a warning diagnostic if 'dnl' +is followed by an open parenthesis. In this case, 'dnl' will collect +and process all arguments, looking for a matching close parenthesis. +All predictable side effects resulting from this collection will take +place. 'dnl' will return no output. The input following the matching +close parenthesis up to and including the next newline, on whatever line +containing it, will still be discarded. + + dnl(`args are ignored, but side effects occur', + define(`foo', `like this')) while this text is ignored: undefine(`foo') + error->m4:stdin:1: Warning: excess arguments to builtin `dnl' ignored + See how `foo' was defined, foo? + =>See how foo was defined, like this? + + If the end of file is encountered without a newline character, a +warning is issued and dnl stops consuming input. + + m4wrap(`m4wrap(`2 hi + ')0 hi dnl 1 hi') + => + define(`hi', `HI') + => + ^D + error->m4:stdin:1: Warning: end of file treated as newline + =>0 HI 2 HI + + +File: m4.info, Node: Changequote, Next: Changecom, Prev: Dnl, Up: Input Control + +8.2 Changing the quote characters +================================= + +The default quote delimiters can be changed with the builtin +'changequote': + + -- Builtin: changequote ([START = '`'] + This sets START as the new begin-quote delimiter and END as the new + end-quote delimiter. If both arguments are missing, the default + quotes ('`' and ''') are used. If START is void, then quoting is + disabled. Otherwise, if END is missing or void, the default + end-quote delimiter (''') is used. The quote delimiters can be of + any length. + + The expansion of 'changequote' is void. + + changequote(`[', `]') + => + define([foo], [Macro [foo].]) + => + foo + =>Macro foo. + + The quotation strings can safely contain eight-bit characters. If no +single character is appropriate, START and END can be of any length. +Other implementations cap the delimiter length to five characters, but +GNU has no inherent limit. + + changequote(`[[[', `]]]') + => + define([[[foo]]], [[[Macro [[[[[foo]]]]].]]]) + => + foo + =>Macro [[foo]]. + + Calling 'changequote' with START as the empty string will effectively +disable the quoting mechanism, leaving no way to quote text. However, +using an empty string is not portable, as some other implementations of +'m4' revert to the default quoting, while others preserve the prior +non-empty delimiter. If START is not empty, then an empty END will use +the default end-quote delimiter of ''', as otherwise, it would be +impossible to end a quoted string. Again, this is not portable, as some +other 'm4' implementations reuse START as the end-quote delimiter, while +others preserve the previous non-empty value. Omitting both arguments +restores the default begin-quote and end-quote delimiters; fortunately +this behavior is portable to all implementations of 'm4'. + + define(`foo', `Macro `FOO'.') + => + changequote(`', `') + => + foo + =>Macro `FOO'. + `foo' + =>`Macro `FOO'.' + changequote(`,) + => + foo + =>Macro FOO. + + There is no way in 'm4' to quote a string containing an unmatched +begin-quote, except using 'changequote' to change the current quotes. + + If the quotes should be changed from, say, '[' to '[[', temporary +quote characters have to be defined. To achieve this, two calls of +'changequote' must be made, one for the temporary quotes and one for the +new quotes. + + Macros are recognized in preference to the begin-quote string, so if +a prefix of START can be recognized as part of a potential macro name, +the quoting mechanism is effectively disabled. Unless you use +'changeword' (*note Changeword::), this means that START should not +begin with a letter, digit, or '_' (underscore). However, even though +quoted strings are not recognized, the quote characters can still be +discerned in macro expansion and in trace output. + + define(`echo', `$@') + => + define(`hi', `HI') + => + changequote(`q', `Q') + => + q hi Q hi + =>q HI Q HI + echo(hi) + =>qHIQ + changequote + => + changequote(`-', `EOF') + => + - hi EOF hi + => hi HI + changequote + => + changequote(`1', `2') + => + hi1hi2 + =>hi1hi2 + hi 1hi2 + =>HI hi + + Quotes are recognized in preference to argument collection. In +particular, if START is a single '(', then argument collection is +effectively disabled. For portability with other implementations, it is +a good idea to avoid '(', ',', and ')' as the first character in START. + + define(`echo', `$#:$@:') + => + define(`hi', `HI') + => + changequote(`(',`)') + => + echo(hi) + =>0::hi + changequote + => + changequote(`((', `))') + => + echo(hi) + =>1:HI: + echo((hi)) + =>0::hi + changequote + => + changequote(`,', `)') + => + echo(hi,hi)bye) + =>1:HIhibye: + + However, if you are not worried about portability, using '(' and ')' +as quoting characters has an interesting property--you can use it to +compute a quoted string containing the expansion of any quoted text, as +long as the expansion results in both balanced quotes and balanced +parentheses. The trick is realizing 'expand' uses '$1' unquoted, to +trigger its expansion using the normal quoting characters, but uses +extra parentheses to group unquoted commas that occur in the expansion +without consuming whitespace following those commas. Then '_expand' +uses 'changequote' to convert the extra parentheses back into quoting +characters. Note that it takes two more 'changequote' invocations to +restore the original quotes. Contrast the behavior on whitespace when +using '$*', via 'quote', to attempt the same task. + + changequote(`[', `]')dnl + define([a], [1, (b)])dnl + define([b], [2])dnl + define([quote], [[$*]])dnl + define([expand], [_$0(($1))])dnl + define([_expand], + [changequote([(], [)])$1changequote`'changequote(`[', `]')])dnl + expand([a, a, [a, a], [[a, a]]]) + =>1, (2), 1, (2), a, a, [a, a] + quote(a, a, [a, a], [[a, a]]) + =>1,(2),1,(2),a, a,[a, a] + + If END is a prefix of START, the end-quote will be recognized in +preference to a nested begin-quote. In particular, changing the quotes +to have the same string for START and END disables nesting of quotes. +When quote nesting is disabled, it is impossible to double-quote strings +across macro expansions, so using the same string is not done very +often. + + define(`hi', `HI') + => + changequote(`""', `"') + => + ""hi"""hi" + =>hihi + ""hi" ""hi" + =>hi hi + ""hi"" "hi" + =>hi" "HI" + changequote + => + `hi`hi'hi' + =>hi`hi'hi + changequote(`"', `"') + => + "hi"hi"hi" + =>hiHIhi + + It is an error if the end of file occurs within a quoted string. + + `hello world' + =>hello world + `dangling quote + ^D + error->m4:stdin:2: ERROR: end of file in string + + ifelse(`dangling quote + ^D + error->m4:stdin:1: ERROR: end of file in string + + +File: m4.info, Node: Changecom, Next: Changeword, Prev: Changequote, Up: Input Control + +8.3 Changing the comment delimiters +=================================== + +The default comment delimiters can be changed with the builtin macro +'changecom': + + -- Builtin: changecom ([START] + This sets START as the new begin-comment delimiter and END as the + new end-comment delimiter. If both arguments are missing, or START + is void, then comments are disabled. Otherwise, if END is missing + or void, the default end-comment delimiter of newline is used. The + comment delimiters can be of any length. + + The expansion of 'changecom' is void. + + define(`comment', `COMMENT') + => + # A normal comment + =># A normal comment + changecom(`/*', `*/') + => + # Not a comment anymore + =># Not a COMMENT anymore + But: /* this is a comment now */ while this is not a comment + =>But: /* this is a comment now */ while this is not a COMMENT + + Note how comments are copied to the output, much as if they were +quoted strings. If you want the text inside a comment expanded, quote +the begin-comment delimiter. + + Calling 'changecom' without any arguments, or with START as the empty +string, will effectively disable the commenting mechanism. To restore +the original comment start of '#', you must explicitly ask for it. If +START is not empty, then an empty END will use the default end-comment +delimiter of newline, as otherwise, it would be impossible to end a +comment. However, this is not portable, as some other 'm4' +implementations preserve the previous non-empty delimiters instead. + + define(`comment', `COMMENT') + => + changecom + => + # Not a comment anymore + =># Not a COMMENT anymore + changecom(`#', `') + => + # comment again + =># comment again + + The comment strings can safely contain eight-bit characters. If no +single character is appropriate, START and END can be of any length. +Other implementations cap the delimiter length to five characters, but +GNU has no inherent limit. + + Comments are recognized in preference to macros. However, this is +not compatible with other implementations, where macros and even quoting +takes precedence over comments, so it may change in a future release. +For portability, this means that START should not begin with a letter, +digit, or '_' (underscore), and that neither the start-quote nor the +start-comment string should be a prefix of the other. + + define(`hi', `HI') + => + define(`hi1hi2', `hello') + => + changecom(`q', `Q') + => + q hi Q hi + =>q hi Q HI + changecom(`1', `2') + => + hi1hi2 + =>hello + hi 1hi2 + =>HI 1hi2 + + Comments are recognized in preference to argument collection. In +particular, if START is a single '(', then argument collection is +effectively disabled. For portability with other implementations, it is +a good idea to avoid '(', ',', and ')' as the first character in START. + + define(`echo', `$#:$*:$@:') + => + define(`hi', `HI') + => + changecom(`(',`)') + => + echo(hi) + =>0:::(hi) + changecom + => + changecom(`((', `))') + => + echo(hi) + =>1:HI:HI: + echo((hi)) + =>0:::((hi)) + changecom(`,', `)') + => + echo(hi,hi)bye) + =>1:HI,hi)bye:HI,hi)bye: + changecom + => + echo(hi,`,`'hi',hi) + =>3:HI,,HI,HI:HI,,`'hi,HI: + echo(hi,`,`'hi',hi`'changecom(`,,', `hi')) + =>3:HI,,`'hi,HI:HI,,`'hi,HI: + + It is an error if the end of file occurs within a comment. + + changecom(`/*', `*/') + => + /*dangling comment + ^D + error->m4:stdin:2: ERROR: end of file in comment + + +File: m4.info, Node: Changeword, Next: M4wrap, Prev: Changecom, Up: Input Control + +8.4 Changing the lexical structure of words +=========================================== + + The macro 'changeword' and all associated functionality is + experimental. It is only available if the '--enable-changeword' + option was given to 'configure', at GNU 'm4' installation time. + The functionality will go away in the future, to be replaced by + other new features that are more efficient at providing the same + capabilities. _Do not rely on it_. Please direct your comments + about it the same way you would do for bugs. + + A file being processed by 'm4' is split into quoted strings, words +(potential macro names) and simple tokens (any other single character). +Initially a word is defined by the following regular expression: + + [_a-zA-Z][_a-zA-Z0-9]* + + Using 'changeword', you can change this regular expression: + + -- Optional builtin: changeword (REGEX) + Changes the regular expression for recognizing macro names to be + REGEX. If REGEX is empty, use '[_a-zA-Z][_a-zA-Z0-9]*'. REGEX + must obey the constraint that every prefix of the desired final + pattern is also accepted by the regular expression. If REGEX + contains grouping parentheses, the macro invoked is the portion + that matched the first group, rather than the entire matching + string. + + The expansion of 'changeword' is void. The macro 'changeword' is + recognized only with parameters. + + Relaxing the lexical rules of 'm4' might be useful (for example) if +you wanted to apply translations to a file of numbers: + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + changeword(`[_a-zA-Z0-9]+') + => + define(`1', `0')1 + =>0 + + Tightening the lexical rules is less useful, because it will +generally make some of the builtins unavailable. You could use it to +prevent accidental call of builtins, for example: + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + define(`_indir', defn(`indir')) + => + changeword(`_[_a-zA-Z0-9]*') + => + esyscmd(`foo') + =>esyscmd(foo) + _indir(`esyscmd', `echo hi') + =>hi + => + + Because 'm4' constructs its words a character at a time, there is a +restriction on the regular expressions that may be passed to +'changeword'. This is that if your regular expression accepts 'foo', it +must also accept 'f' and 'fo'. + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + define(`foo + ', `bar + ') + => + dnl This example wants to recognize changeword, dnl, and `foo\n'. + dnl First, we check that our regexp will match. + regexp(`changeword', `[cd][a-z]*\|foo[ + ]') + =>0 + regexp(`foo + ', `[cd][a-z]*\|foo[ + ]') + =>0 + regexp(`f', `[cd][a-z]*\|foo[ + ]') + =>-1 + foo + =>foo + changeword(`[cd][a-z]*\|foo[ + ]') + => + dnl Even though `foo\n' matches, we forgot to allow `f'. + foo + =>foo + changeword(`[cd][a-z]*\|fo*[ + ]?') + => + dnl Now we can call `foo\n'. + foo + =>bar + + 'changeword' has another function. If the regular expression +supplied contains any grouped subexpressions, then text outside the +first of these is discarded before symbol lookup. So: + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics + ')m4exit(`77')')dnl + changecom(`/*', `*/')dnl + define(`foo', `bar')dnl + changeword(`#\([_a-zA-Z0-9]*\)') + => + #esyscmd(`echo foo \#foo') + =>foo bar + => + + 'm4' now requires a '#' mark at the beginning of every macro +invocation, so one can use 'm4' to preprocess plain text without losing +various words like 'divert'. + + In 'm4', macro substitution is based on text, while in TeX, it is +based on tokens. 'changeword' can throw this difference into relief. +For example, here is the same idea represented in TeX and 'm4'. First, +the TeX version: + + \def\a{\message{Hello}} + \catcode`\@=0 + \catcode`\\=12 + @a + @bye + =>Hello + +Then, the 'm4' version: + + ifdef(`changeword', `', `errprint(` skipping: no changeword support + ')m4exit(`77')')dnl + define(`a', `errprint(`Hello')')dnl + changeword(`@\([_a-zA-Z0-9]*\)') + => + @a + =>errprint(Hello) + + In the TeX example, the first line defines a macro 'a' to print the +message 'Hello'. The second line defines <@> to be usable instead of +<\> as an escape character. The third line defines <\> to be a normal +printing character, not an escape. The fourth line invokes the macro +'a'. So, when TeX is run on this file, it displays the message 'Hello'. + + When the 'm4' example is passed through 'm4', it outputs +'errprint(Hello)'. The reason for this is that TeX does lexical +analysis of macro definition when the macro is _defined_. 'm4' just +stores the text, postponing the lexical analysis until the macro is +_used_. + + You should note that using 'changeword' will slow 'm4' down by a +factor of about seven, once it is changed to something other than the +default regular expression. You can invoke 'changeword' with the empty +string to restore the default word definition, and regain the parsing +speed. + + +File: m4.info, Node: M4wrap, Prev: Changeword, Up: Input Control + +8.5 Saving text until end of input +================================== + +It is possible to 'save' some text until the end of the normal input has +been seen. Text can be saved, to be read again by 'm4' when the normal +input has been exhausted. This feature is normally used to initiate +cleanup actions before normal exit, e.g., deleting temporary files. + + To save input text, use the builtin 'm4wrap': + + -- Builtin: m4wrap (STRING, ...) + Stores STRING in a safe place, to be reread when end of input is + reached. As a GNU extension, additional arguments are concatenated + with a space to the STRING. + + The expansion of 'm4wrap' is void. The macro 'm4wrap' is + recognized only with parameters. + + define(`cleanup', `This is the `cleanup' action. + ') + => + m4wrap(`cleanup') + => + This is the first and last normal input line. + =>This is the first and last normal input line. + ^D + =>This is the cleanup action. + + The saved input is only reread when the end of normal input is seen, +and not if 'm4exit' is used to exit 'm4'. + + It is safe to call 'm4wrap' from saved text, but then the order in +which the saved text is reread is undefined. If 'm4wrap' is not used +recursively, the saved pieces of text are reread in the opposite order +in which they were saved (LIFO--last in, first out). However, this +behavior is likely to change in a future release, to match POSIX, so you +should not depend on this order. + + It is possible to emulate POSIX behavior even with older versions of +GNU M4 by including the file 'm4-1.4.17/examples/wrapfifo.m4' from the +distribution: + + $ m4 -I examples + undivert(`wrapfifo.m4')dnl + =>dnl Redefine m4wrap to have FIFO semantics. + =>define(`_m4wrap_level', `0')dnl + =>define(`m4wrap', + =>`ifdef(`m4wrap'_m4wrap_level, + => `define(`m4wrap'_m4wrap_level, + => defn(`m4wrap'_m4wrap_level)`$1')', + => `builtin(`m4wrap', `define(`_m4wrap_level', + => incr(_m4wrap_level))dnl + =>m4wrap'_m4wrap_level)dnl + =>define(`m4wrap'_m4wrap_level, `$1')')')dnl + include(`wrapfifo.m4') + => + m4wrap(`a`'m4wrap(`c + ', `d')')m4wrap(`b') + => + ^D + =>abc + + It is likewise possible to emulate LIFO behavior without resorting to +the GNU M4 extension of 'builtin', by including the file +'m4-1.4.17/examples/wraplifo.m4' from the distribution. (Unfortunately, +both examples shown here share some subtle bugs. See if you can find +and correct them; or *note Answers: Improved m4wrap.). + + $ m4 -I examples + undivert(`wraplifo.m4')dnl + =>dnl Redefine m4wrap to have LIFO semantics. + =>define(`_m4wrap_level', `0')dnl + =>define(`_m4wrap', defn(`m4wrap'))dnl + =>define(`m4wrap', + =>`ifdef(`m4wrap'_m4wrap_level, + => `define(`m4wrap'_m4wrap_level, + => `$1'defn(`m4wrap'_m4wrap_level))', + => `_m4wrap(`define(`_m4wrap_level', incr(_m4wrap_level))dnl + =>m4wrap'_m4wrap_level)dnl + =>define(`m4wrap'_m4wrap_level, `$1')')')dnl + include(`wraplifo.m4') + => + m4wrap(`a`'m4wrap(`c + ', `d')')m4wrap(`b') + => + ^D + =>bac + + Here is an example of implementing a factorial function using +'m4wrap': + + define(`f', `ifelse(`$1', `0', `Answer: 0!=1 + ', eval(`$1>1'), `0', `Answer: $2$1=eval(`$2$1') + ', `m4wrap(`f(decr(`$1'), `$2$1*')')')') + => + f(`10') + => + ^D + =>Answer: 10*9*8*7*6*5*4*3*2*1=3628800 + + Invocations of 'm4wrap' at the same recursion level are concatenated +and rescanned as usual: + + define(`aa', `AA + ') + => + m4wrap(`a')m4wrap(`a') + => + ^D + =>AA + +however, the transition between recursion levels behaves like an end of +file condition between two input files. + + m4wrap(`m4wrap(`)')len(abc') + => + ^D + error->m4:stdin:1: ERROR: end of file in argument list + + +File: m4.info, Node: File Inclusion, Next: Diversions, Prev: Input Control, Up: Top + +9 File inclusion +**************** + +'m4' allows you to include named files at any point in the input. + +* Menu: + +* Include:: Including named files +* Search Path:: Searching for include files + + +File: m4.info, Node: Include, Next: Search Path, Up: File Inclusion + +9.1 Including named files +========================= + +There are two builtin macros in 'm4' for including files: + + -- Builtin: include (FILE) + -- Builtin: sinclude (FILE) + Both macros cause the file named FILE to be read by 'm4'. When the + end of the file is reached, input is resumed from the previous + input file. + + The expansion of 'include' and 'sinclude' is therefore the contents + of FILE. + + If FILE does not exist, is a directory, or cannot otherwise be + read, the expansion is void, and 'include' will fail with an error + while 'sinclude' is silent. The empty string counts as a file that + does not exist. + + The macros 'include' and 'sinclude' are recognized only with + parameters. + + include(`none') + error->m4:stdin:1: cannot open `none': No such file or directory + => + include() + error->m4:stdin:2: cannot open `': No such file or directory + => + sinclude(`none') + => + sinclude() + => + + The rest of this section assumes that 'm4' is invoked with the '-I' +option (*note Invoking m4: Preprocessor features.) pointing to the +'m4-1.4.17/examples' directory shipped as part of the GNU 'm4' package. +The file 'm4-1.4.17/examples/incl.m4' in the distribution contains the +lines: + + $ cat examples/incl.m4 + =>Include file start + =>foo + =>Include file end + + Normally file inclusion is used to insert the contents of a file into +the input stream. The contents of the file will be read by 'm4' and +macro calls in the file will be expanded: + + $ m4 -I examples + define(`foo', `FOO') + => + include(`incl.m4') + =>Include file start + =>FOO + =>Include file end + => + + The fact that 'include' and 'sinclude' expand to the contents of the +file can be used to define macros that operate on entire files. Here is +an example, which defines 'bar' to expand to the contents of 'incl.m4': + + $ m4 -I examples + define(`bar', include(`incl.m4')) + => + This is `bar': >>bar<< + =>This is bar: >>Include file start + =>foo + =>Include file end + =><< + + This use of 'include' is not trivial, though, as files can contain +quotes, commas, and parentheses, which can interfere with the way the +'m4' parser works. GNU 'm4' seamlessly concatenates the file contents +with the next character, even if the included file ended in the middle +of a comment, string, or macro call. These conditions are only treated +as end of file errors if specified as input files on the command line. + + In GNU 'm4', an alternative method of reading files is using +'undivert' (*note Undivert::) on a named file. + + +File: m4.info, Node: Search Path, Prev: Include, Up: File Inclusion + +9.2 Searching for include files +=============================== + +GNU 'm4' allows included files to be found in other directories than the +current working directory. + + If the '--prepend-include' or '-B' command-line option was provided +(*note Invoking m4: Preprocessor features.), those directories are +searched first, in reverse order that those options were listed on the +command line. Then 'm4' looks in the current working directory. Next +comes the directories specified with the '--include' or '-I' option, in +the order found on the command line. Finally, if the 'M4PATH' +environment variable is set, it is expected to contain a colon-separated +list of directories, which will be searched in order. + + If the automatic search for include-files causes trouble, the 'p' +debug flag (*note Debug Levels::) can help isolate the problem. + + +File: m4.info, Node: Diversions, Next: Text handling, Prev: File Inclusion, Up: Top + +10 Diverting and undiverting output +*********************************** + +Diversions are a way of temporarily saving output. The output of 'm4' +can at any time be diverted to a temporary file, and be reinserted into +the output stream, "undiverted", again at a later time. + + Numbered diversions are counted from 0 upwards, diversion number 0 +being the normal output stream. GNU 'm4' tries to keep diversions in +memory. However, there is a limit to the overall memory usable by all +diversions taken together (512K, currently). When this maximum is about +to be exceeded, a temporary file is opened to receive the contents of +the biggest diversion still in memory, freeing this memory for other +diversions. When creating the temporary file, 'm4' honors the value of +the environment variable 'TMPDIR', and falls back to '/tmp'. Thus, the +amount of available disk space provides the only real limit on the +number and aggregate size of diversions. + + Diversions make it possible to generate output in a different order +than the input was read. It is possible to implement topological +sorting dependencies. For example, GNU Autoconf makes use of diversions +under the hood to ensure that the expansion of a prerequisite macro +appears in the output prior to the expansion of a dependent macro, +regardless of which order the two macros were invoked in the user's +input file. + +* Menu: + +* Divert:: Diverting output +* Undivert:: Undiverting output +* Divnum:: Diversion numbers +* Cleardivert:: Discarding diverted text + + +File: m4.info, Node: Divert, Next: Undivert, Up: Diversions + +10.1 Diverting output +===================== + +Output is diverted using 'divert': + + -- Builtin: divert ([NUMBER = '0'] + The current diversion is changed to NUMBER. If NUMBER is left out + or empty, it is assumed to be zero. If NUMBER cannot be parsed, + the diversion is unchanged. + + The expansion of 'divert' is void. + + When all the 'm4' input will have been processed, all existing +diversions are automatically undiverted, in numerical order. + + divert(`1') + This text is diverted. + divert + => + This text is not diverted. + =>This text is not diverted. + ^D + => + =>This text is diverted. + + Several calls of 'divert' with the same argument do not overwrite the +previous diverted text, but append to it. Diversions are printed after +any wrapped text is expanded. + + define(`text', `TEXT') + => + divert(`1')`diverted text.' + divert + => + m4wrap(`Wrapped text precedes ') + => + ^D + =>Wrapped TEXT precedes diverted text. + + If output is diverted to a negative diversion, it is simply +discarded. This can be used to suppress unwanted output. A common +example of unwanted output is the trailing newlines after macro +definitions. Here is a common programming idiom in 'm4' for avoiding +them. + + divert(`-1') + define(`foo', `Macro `foo'.') + define(`bar', `Macro `bar'.') + divert + => + + Traditional implementations only supported ten diversions. But as a +GNU extension, diversion numbers can be as large as positive integers +will allow, rather than treating a multi-digit diversion number as a +request to discard text. + + divert(eval(`1<<28'))world + divert(`2')hello + ^D + =>hello + =>world + + Note that 'divert' is an English word, but also an active macro +without arguments. When processing plain text, the word might appear in +normal text and be unintentionally swallowed as a macro invocation. One +way to avoid this is to use the '-P' option to rename all builtins +(*note Invoking m4: Operation modes.). Another is to write a wrapper +that requires a parameter to be recognized. + + We decided to divert the stream for irrigation. + =>We decided to the stream for irrigation. + define(`divert', `ifelse(`$#', `0', ``$0'', `builtin(`$0', $@)')') + => + divert(`-1') + Ignored text. + divert(`0') + => + We decided to divert the stream for irrigation. + =>We decided to divert the stream for irrigation. + + +File: m4.info, Node: Undivert, Next: Divnum, Prev: Divert, Up: Diversions + +10.2 Undiverting output +======================= + +Diverted text can be undiverted explicitly using the builtin 'undivert': + + -- Builtin: undivert ([DIVERSIONS...] + Undiverts the numeric DIVERSIONS given by the arguments, in the + order given. If no arguments are supplied, all diversions are + undiverted, in numerical order. + + As a GNU extension, DIVERSIONS may contain non-numeric strings, + which are treated as the names of files to copy into the output + without expansion. A warning is issued if a file could not be + opened. + + The expansion of 'undivert' is void. + + divert(`1') + This text is diverted. + divert + => + This text is not diverted. + =>This text is not diverted. + undivert(`1') + => + =>This text is diverted. + => + + Notice the last two blank lines. One of them comes from the newline +following 'undivert', the other from the newline that followed the +'divert'! A diversion often starts with a blank line like this. + + When diverted text is undiverted, it is _not_ reread by 'm4', but +rather copied directly to the current output, and it is therefore not an +error to undivert into a diversion. Undiverting the empty string is the +same as specifying diversion 0; in either case nothing happens since the +output has already been flushed. + + divert(`1')diverted text + divert + => + undivert() + => + undivert(`0') + => + undivert + =>diverted text + => + divert(`1')more + divert(`2')undivert(`1')diverted text`'divert + => + undivert(`1') + => + undivert(`2') + =>more + =>diverted text + + When a diversion has been undiverted, the diverted text is discarded, +and it is not possible to bring back diverted text more than once. + + divert(`1') + This text is diverted first. + divert(`0')undivert(`1')dnl + => + =>This text is diverted first. + undivert(`1') + => + divert(`1') + This text is also diverted but not appended. + divert(`0')undivert(`1')dnl + => + =>This text is also diverted but not appended. + + Attempts to undivert the current diversion are silently ignored. +Thus, when the current diversion is not 0, the current diversion does +not get rearranged among the other diversions. + + divert(`1')one + divert(`2')two + divert(`3')three + divert(`2')undivert`'dnl + divert`'undivert`'dnl + =>two + =>one + =>three + + GNU 'm4' allows named files to be undiverted. Given a non-numeric +argument, the contents of the file named will be copied, uninterpreted, +to the current output. This complements the builtin 'include' (*note +Include::). To illustrate the difference, assume the file 'foo' +contains: + + $ cat foo + bar + +then + + define(`bar', `BAR') + => + undivert(`foo') + =>bar + => + include(`foo') + =>BAR + => + + If the file is not found (or cannot be read), an error message is +issued, and the expansion is void. It is possible to intermix files and +diversion numbers. + + divert(`1')diversion one + divert(`2')undivert(`foo')dnl + divert(`3')diversion three + divert`'dnl + undivert(`1', `2', `foo', `3')dnl + =>diversion one + =>bar + =>bar + =>diversion three + + +File: m4.info, Node: Divnum, Next: Cleardivert, Prev: Undivert, Up: Diversions + +10.3 Diversion numbers +====================== + +The current diversion is tracked by the builtin 'divnum': + + -- Builtin: divnum + Expands to the number of the current diversion. + + Initial divnum + =>Initial 0 + divert(`1') + Diversion one: divnum + divert(`2') + Diversion two: divnum + ^D + => + =>Diversion one: 1 + => + =>Diversion two: 2 + + +File: m4.info, Node: Cleardivert, Prev: Divnum, Up: Diversions + +10.4 Discarding diverted text +============================= + +Often it is not known, when output is diverted, whether the diverted +text is actually needed. Since all non-empty diversion are brought back +on the main output stream when the end of input is seen, a method of +discarding a diversion is needed. If all diversions should be +discarded, the easiest is to end the input to 'm4' with 'divert(`-1')' +followed by an explicit 'undivert': + + divert(`1') + Diversion one: divnum + divert(`2') + Diversion two: divnum + divert(`-1') + undivert + ^D + +No output is produced at all. + + Clearing selected diversions can be done with the following macro: + + -- Composite: cleardivert ([DIVERSIONS...] + Discard the contents of each of the listed numeric DIVERSIONS. + + define(`cleardivert', + `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')') + => + + It is called just like 'undivert', but the effect is to clear the +diversions, given by the arguments. (This macro has a nasty bug! You +should try to see if you can find it and correct it; or *note Answers: +Improved cleardivert.). + + +File: m4.info, Node: Text handling, Next: Arithmetic, Prev: Diversions, Up: Top + +11 Macros for text handling +*************************** + +There are a number of builtins in 'm4' for manipulating text in various +ways, extracting substrings, searching, substituting, and so on. + +* Menu: + +* Len:: Calculating length of strings +* Index macro:: Searching for substrings +* Regexp:: Searching for regular expressions +* Substr:: Extracting substrings +* Translit:: Translating characters +* Patsubst:: Substituting text by regular expression +* Format:: Formatting strings (printf-like) + + +File: m4.info, Node: Len, Next: Index macro, Up: Text handling + +11.1 Calculating length of strings +================================== + +The length of a string can be calculated by 'len': + + -- Builtin: len (STRING) + Expands to the length of STRING, as a decimal number. + + The macro 'len' is recognized only with parameters. + + len() + =>0 + len(`abcdef') + =>6 + + +File: m4.info, Node: Index macro, Next: Regexp, Prev: Len, Up: Text handling + +11.2 Searching for substrings +============================= + +Searching for substrings is done with 'index': + + -- Builtin: index (STRING, SUBSTRING) + Expands to the index of the first occurrence of SUBSTRING in + STRING. The first character in STRING has index 0. If SUBSTRING + does not occur in STRING, 'index' expands to '-1'. + + The macro 'index' is recognized only with parameters. + + index(`gnus, gnats, and armadillos', `nat') + =>7 + index(`gnus, gnats, and armadillos', `dag') + =>-1 + + Omitting SUBSTRING evokes a warning, but still produces output; +contrast this with an empty SUBSTRING. + + index(`abc') + error->m4:stdin:1: Warning: too few arguments to builtin `index' + =>0 + index(`abc', `') + =>0 + index(`abc', `b') + =>1 + + +File: m4.info, Node: Regexp, Next: Substr, Prev: Index macro, Up: Text handling + +11.3 Searching for regular expressions +====================================== + +Searching for regular expressions is done with the builtin 'regexp': + + -- Builtin: regexp (STRING, REGEXP, [REPLACEMENT] + Searches for REGEXP in STRING. The syntax for regular expressions + is the same as in GNU Emacs, which is similar to BRE, Basic Regular + Expressions in POSIX. *Note Syntax of Regular Expressions: + (emacs)Regexps. Support for ERE, Extended Regular Expressions is + not available, but will be added in GNU M4 2.0. + + If REPLACEMENT is omitted, 'regexp' expands to the index of the + first match of REGEXP in STRING. If REGEXP does not match anywhere + in STRING, it expands to -1. + + If REPLACEMENT is supplied, and there was a match, 'regexp' changes + the expansion to this argument, with '\N' substituted by the text + matched by the Nth parenthesized sub-expression of REGEXP, up to + nine sub-expressions. The escape '\&' is replaced by the text of + the entire regular expression matched. For all other characters, + '\' treats the next character literally. A warning is issued if + there were fewer sub-expressions than the '\N' requested, or if + there is a trailing '\'. If there was no match, 'regexp' expands + to the empty string. + + The macro 'regexp' is recognized only with parameters. + + regexp(`GNUs not Unix', `\<[a-z]\w+') + =>5 + regexp(`GNUs not Unix', `\<Q\w*') + =>-1 + regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***') + =>*** Unix *** nix *** + regexp(`GNUs not Unix', `\<Q\w*', `*** \& *** \1 ***') + => + + Here are some more examples on the handling of backslash: + + regexp(`abc', `\(b\)', `\\\10\a') + =>\b0a + regexp(`abc', `b', `\1\') + error->m4:stdin:2: Warning: sub-expression 1 not present + error->m4:stdin:2: Warning: trailing \ ignored in replacement + => + regexp(`abc', `\(\(d\)?\)\(c\)', `\1\2\3\4\5\6') + error->m4:stdin:3: Warning: sub-expression 4 not present + error->m4:stdin:3: Warning: sub-expression 5 not present + error->m4:stdin:3: Warning: sub-expression 6 not present + =>c + + Omitting REGEXP evokes a warning, but still produces output; contrast +this with an empty REGEXP argument. + + regexp(`abc') + error->m4:stdin:1: Warning: too few arguments to builtin `regexp' + =>0 + regexp(`abc', `') + =>0 + regexp(`abc', `', `\\def') + =>\def + + +File: m4.info, Node: Substr, Next: Translit, Prev: Regexp, Up: Text handling + +11.4 Extracting substrings +========================== + +Substrings are extracted with 'substr': + + -- Builtin: substr (STRING, FROM, [LENGTH] + Expands to the substring of STRING, which starts at index FROM, and + extends for LENGTH characters, or to the end of STRING, if LENGTH + is omitted. The starting index of a string is always 0. The + expansion is empty if there is an error parsing FROM or LENGTH, if + FROM is beyond the end of STRING, or if LENGTH is negative. + + The macro 'substr' is recognized only with parameters. + + substr(`gnus, gnats, and armadillos', `6') + =>gnats, and armadillos + substr(`gnus, gnats, and armadillos', `6', `5') + =>gnats + + Omitting FROM evokes a warning, but still produces output. + + substr(`abc') + error->m4:stdin:1: Warning: too few arguments to builtin `substr' + =>abc + substr(`abc',) + error->m4:stdin:2: empty string treated as 0 in builtin `substr' + =>abc + + +File: m4.info, Node: Translit, Next: Patsubst, Prev: Substr, Up: Text handling + +11.5 Translating characters +=========================== + +Character translation is done with 'translit': + + -- Builtin: translit (STRING, CHARS, [REPLACEMENT] + Expands to STRING, with each character that occurs in CHARS + translated into the character from REPLACEMENT with the same index. + + If REPLACEMENT is shorter than CHARS, the excess characters of + CHARS are deleted from the expansion; if CHARS is shorter, the + excess characters in REPLACEMENT are silently ignored. If + REPLACEMENT is omitted, all characters in STRING that are present + in CHARS are deleted from the expansion. If a character appears + more than once in CHARS, only the first instance is used in making + the translation. Only a single translation pass is made, even if + characters in REPLACEMENT also appear in CHARS. + + As a GNU extension, both CHARS and REPLACEMENT can contain + character-ranges, e.g., 'a-z' (meaning all lowercase letters) or + '0-9' (meaning all digits). To include a dash '-' in CHARS or + REPLACEMENT, place it first or last in the entire string, or as the + last character of a range. Back-to-back ranges can share a common + endpoint. It is not an error for the last character in the range + to be 'larger' than the first. In that case, the range runs + backwards, i.e., '9-0' means the string '9876543210'. The + expansion of a range is dependent on the underlying encoding of + characters, so using ranges is not always portable between + machines. + + The macro 'translit' is recognized only with parameters. + + translit(`GNUs not Unix', `A-Z') + =>s not nix + translit(`GNUs not Unix', `a-z', `A-Z') + =>GNUS NOT UNIX + translit(`GNUs not Unix', `A-Z', `z-a') + =>tmfs not fnix + translit(`+,-12345', `+--1-5', `<;>a-c-a') + =><;>abcba + translit(`abcdef', `aabdef', `bcged') + =>bgced + + In the ASCII encoding, the first example deletes all uppercase +letters, the second converts lowercase to uppercase, and the third +'mirrors' all uppercase letters, while converting them to lowercase. +The two first cases are by far the most common, even though they are not +portable to EBCDIC or other encodings. The fourth example shows a range +ending in '-', as well as back-to-back ranges. The final example shows +that 'a' is mapped to 'b', not 'c'; the resulting 'b' is not further +remapped to 'g'; the 'd' and 'e' are swapped, and the 'f' is discarded. + + Omitting CHARS evokes a warning, but still produces output. + + translit(`abc') + error->m4:stdin:1: Warning: too few arguments to builtin `translit' + =>abc + + +File: m4.info, Node: Patsubst, Next: Format, Prev: Translit, Up: Text handling + +11.6 Substituting text by regular expression +============================================ + +Global substitution in a string is done by 'patsubst': + + -- Builtin: patsubst (STRING, REGEXP, [REPLACEMENT] + Searches STRING for matches of REGEXP, and substitutes REPLACEMENT + for each match. The syntax for regular expressions is the same as + in GNU Emacs (*note Regexp::). + + The parts of STRING that are not covered by any match of REGEXP are + copied to the expansion. Whenever a match is found, the search + proceeds from the end of the match, so a character from STRING will + never be substituted twice. If REGEXP matches a string of zero + length, the start position for the search is incremented, to avoid + infinite loops. + + When a replacement is to be made, REPLACEMENT is inserted into the + expansion, with '\N' substituted by the text matched by the Nth + parenthesized sub-expression of PATSUBST, for up to nine + sub-expressions. The escape '\&' is replaced by the text of the + entire regular expression matched. For all other characters, '\' + treats the next character literally. A warning is issued if there + were fewer sub-expressions than the '\N' requested, or if there is + a trailing '\'. + + The REPLACEMENT argument can be omitted, in which case the text + matched by REGEXP is deleted. + + The macro 'patsubst' is recognized only with parameters. + + patsubst(`GNUs not Unix', `^', `OBS: ') + =>OBS: GNUs not Unix + patsubst(`GNUs not Unix', `\<', `OBS: ') + =>OBS: GNUs OBS: not OBS: Unix + patsubst(`GNUs not Unix', `\w*', `(\&)') + =>(GNUs)() (not)() (Unix)() + patsubst(`GNUs not Unix', `\w+', `(\&)') + =>(GNUs) (not) (Unix) + patsubst(`GNUs not Unix', `[A-Z][a-z]+') + =>GN not + patsubst(`GNUs not Unix', `not', `NOT\') + error->m4:stdin:6: Warning: trailing \ ignored in replacement + =>GNUs NOT Unix + + Here is a slightly more realistic example, which capitalizes +individual words or whole sentences, by substituting calls of the macros +'upcase' and 'downcase' into the strings. + + -- Composite: upcase (TEXT) + -- Composite: downcase (TEXT) + -- Composite: capitalize (TEXT) + Expand to TEXT, but with capitalization changed: 'upcase' changes + all letters to upper case, 'downcase' changes all letters to lower + case, and 'capitalize' changes the first character of each word to + upper case and the remaining characters to lower case. + + First, an example of their usage, using implementations distributed +in 'm4-1.4.17/examples/capitalize.m4'. + + $ m4 -I examples + include(`capitalize.m4') + => + upcase(`GNUs not Unix') + =>GNUS NOT UNIX + downcase(`GNUs not Unix') + =>gnus not unix + capitalize(`GNUs not Unix') + =>Gnus Not Unix + + Now for the implementation. There is a helper macro '_capitalize' +which puts only its first word in mixed case. Then 'capitalize' merely +parses out the words, and replaces them with an invocation of +'_capitalize'. (As presented here, the 'capitalize' macro has some +subtle flaws. You should try to see if you can find and correct them; +or *note Answers: Improved capitalize.). + + $ m4 -I examples + undivert(`capitalize.m4')dnl + =>divert(`-1') + =># upcase(text) + =># downcase(text) + =># capitalize(text) + =># change case of text, simple version + =>define(`upcase', `translit(`$*', `a-z', `A-Z')') + =>define(`downcase', `translit(`$*', `A-Z', `a-z')') + =>define(`_capitalize', + => `regexp(`$1', `^\(\w\)\(\w*\)', + => `upcase(`\1')`'downcase(`\2')')') + =>define(`capitalize', `patsubst(`$1', `\w+', `_$0(`\&')')') + =>divert`'dnl + + While 'regexp' replaces the whole input with the replacement as soon +as there is a match, 'patsubst' replaces each _occurrence_ of a match +and preserves non-matching pieces: + + define(`patreg', + `patsubst($@) + regexp($@)')dnl + patreg(`bar foo baz Foo', `foo\|Foo', `FOO') + =>bar FOO baz FOO + =>FOO + patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2') + =>bab abb 212 + =>bab + + Omitting REGEXP evokes a warning, but still produces output; contrast +this with an empty REGEXP argument. + + patsubst(`abc') + error->m4:stdin:1: Warning: too few arguments to builtin `patsubst' + =>abc + patsubst(`abc', `') + =>abc + patsubst(`abc', `', `\\-') + =>\-a\-b\-c\- + + +File: m4.info, Node: Format, Prev: Patsubst, Up: Text handling + +11.7 Formatting strings (printf-like) +===================================== + +Formatted output can be made with 'format': + + -- Builtin: format (FORMAT-STRING, ...) + Works much like the C function 'printf'. The first argument + FORMAT-STRING can contain '%' specifications which are satisfied by + additional arguments, and the expansion of 'format' is the + formatted string. + + The macro 'format' is recognized only with parameters. + + Its use is best described by a few examples: + + define(`foo', `The brown fox jumped over the lazy dog') + => + format(`The string "%s" uses %d characters', foo, len(foo)) + =>The string "The brown fox jumped over the lazy dog" uses 38 characters + format(`%*.*d', `-1', `-1', `1') + =>1 + format(`%.0f', `56789.9876') + =>56790 + len(format(`%-*X', `5000', `1')) + =>5000 + ifelse(format(`%010F', `infinity'), ` INF', `success', + format(`%010F', `infinity'), ` INFINITY', `success', + format(`%010F', `infinity')) + =>success + ifelse(format(`%.1A', `1.999'), `0X1.0P+1', `success', + format(`%.1A', `1.999'), `0X2.0P+0', `success', + format(`%.1A', `1.999')) + =>success + format(`%g', `0xa.P+1') + =>20 + + Using the 'forloop' macro defined earlier (*note Forloop::), this +example shows how 'format' can be used to produce tabular output. + + $ m4 -I examples + include(`forloop.m4') + => + forloop(`i', `1', `10', `format(`%6d squared is %10d + ', i, eval(i**2))') + => 1 squared is 1 + => 2 squared is 4 + => 3 squared is 9 + => 4 squared is 16 + => 5 squared is 25 + => 6 squared is 36 + => 7 squared is 49 + => 8 squared is 64 + => 9 squared is 81 + => 10 squared is 100 + => + + The builtin 'format' is modeled after the ANSI C 'printf' function, +and supports these '%' specifiers: 'c', 's', 'd', 'o', 'x', 'X', 'u', +'a', 'A', 'e', 'E', 'f', 'F', 'g', 'G', and '%'; it supports field +widths and precisions, and the flags '+', '-', ' ', '0', '#', and '''. +For integer specifiers, the width modifiers 'hh', 'h', and 'l' are +recognized, and for floating point specifiers, the width modifier 'l' is +recognized. Items not yet supported include positional arguments, the +'n', 'p', 'S', and 'C' specifiers, the 'z', 't', 'j', 'L' and 'll' +modifiers, and any platform extensions available in the native 'printf'. +For more details on the functioning of 'printf', see the C Library +Manual, or the POSIX specification (for example, '%a' is supported even +on platforms that haven't yet implemented C99 hexadecimal floating point +output natively). + + Unrecognized specifiers result in a warning. It is anticipated that +a future release of GNU 'm4' will support more specifiers, and give +better warnings when various problems such as overflow are encountered. +Likewise, escape sequences are not yet recognized. + + format(`%p', `0') + error->m4:stdin:1: Warning: unrecognized specifier in `%p' + => + + +File: m4.info, Node: Arithmetic, Next: Shell commands, Prev: Text handling, Up: Top + +12 Macros for doing arithmetic +****************************** + +Integer arithmetic is included in 'm4', with a C-like syntax. As +convenient shorthands, there are builtins for simple increment and +decrement operations. + +* Menu: + +* Incr:: Decrement and increment operators +* Eval:: Evaluating integer expressions + + +File: m4.info, Node: Incr, Next: Eval, Up: Arithmetic + +12.1 Decrement and increment operators +====================================== + +Increment and decrement of integers are supported using the builtins +'incr' and 'decr': + + -- Builtin: incr (NUMBER) + -- Builtin: decr (NUMBER) + Expand to the numerical value of NUMBER, incremented or + decremented, respectively, by one. Except for the empty string, + the expansion is empty if NUMBER could not be parsed. + + The macros 'incr' and 'decr' are recognized only with parameters. + + incr(`4') + =>5 + decr(`7') + =>6 + incr() + error->m4:stdin:3: empty string treated as 0 in builtin `incr' + =>1 + decr() + error->m4:stdin:4: empty string treated as 0 in builtin `decr' + =>-1 + + +File: m4.info, Node: Eval, Prev: Incr, Up: Arithmetic + +12.2 Evaluating integer expressions +=================================== + +Integer expressions are evaluated with 'eval': + + -- Builtin: eval (EXPRESSION, [RADIX = '10'] + Expands to the value of EXPRESSION. The expansion is empty if a + problem is encountered while parsing the arguments. If specified, + RADIX and WIDTH control the format of the output. + + Calculations are done with 32-bit signed numbers. Overflow + silently results in wraparound. A warning is issued if division by + zero is attempted, or if EXPRESSION could not be parsed. + + Expressions can contain the following operators, listed in order of + decreasing precedence. + + '()' + Parentheses + '+ - ~ !' + Unary plus and minus, and bitwise and logical negation + '**' + Exponentiation + '* / %' + Multiplication, division, and modulo + '+ -' + Addition and subtraction + '<< >>' + Shift left or right + '> >= < <=' + Relational operators + '== !=' + Equality operators + '&' + Bitwise and + '^' + Bitwise exclusive-or + '|' + Bitwise or + '&&' + Logical and + '||' + Logical or + + The macro 'eval' is recognized only with parameters. + + All binary operators, except exponentiation, are left associative. C +operators that perform variable assignment, such as '+=' or '--', are +not implemented, since 'eval' only operates on constants, not variables. +Attempting to use them results in an error. However, since traditional +implementations treated '=' as an undocumented alias for '==' as opposed +to an assignment operator, this usage is supported as a special case. +Be aware that a future version of GNU M4 may support assignment +semantics as an extension when POSIX mode is not requested, and that +using '=' to check equality is not portable. + + eval(`2 = 2') + error->m4:stdin:1: Warning: recommend ==, not =, for equality operator + =>1 + eval(`++0') + error->m4:stdin:2: invalid operator in eval: ++0 + => + eval(`0 |= 1') + error->m4:stdin:3: invalid operator in eval: 0 |= 1 + => + + Note that some older 'm4' implementations use '^' as an alternate +operator for the exponentiation, although POSIX requires the C behavior +of bitwise exclusive-or. The precedence of the negation operators, '~' +and '!', was traditionally lower than equality. The unary operators +could not be used reliably more than once on the same term without +intervening parentheses. The traditional precedence of the equality +operators '==' and '!=' was identical instead of lower than the +relational operators such as '<', even through GNU M4 1.4.8. Starting +with version 1.4.9, GNU M4 correctly follows POSIX precedence rules. M4 +scripts designed to be portable between releases must be aware that +parentheses may be required to enforce C precedence rules. Likewise, +division by zero, even in the unused branch of a short-circuiting +operator, is not always well-defined in other implementations. + + Following are some examples where the current version of M4 follows C +precedence rules, but where older versions and some other +implementations of 'm4' require explicit parentheses to get the correct +result: + + eval(`1 == 2 > 0') + =>1 + eval(`(1 == 2) > 0') + =>0 + eval(`! 0 * 2') + =>2 + eval(`! (0 * 2)') + =>1 + eval(`1 | 1 ^ 1') + =>1 + eval(`(1 | 1) ^ 1') + =>0 + eval(`+ + - ~ ! ~ 0') + =>1 + eval(`2 || 1 / 0') + =>1 + eval(`0 || 1 / 0') + error->m4:stdin:9: divide by zero in eval: 0 || 1 / 0 + => + eval(`0 && 1 % 0') + =>0 + eval(`2 && 1 % 0') + error->m4:stdin:11: modulo by zero in eval: 2 && 1 % 0 + => + + As a GNU extension, the operator '**' performs integral +exponentiation. The operator is right-associative, and if evaluated, +the exponent must be non-negative, and at least one of the arguments +must be non-zero, or a warning is issued. + + eval(`2 ** 3 ** 2') + =>512 + eval(`(2 ** 3) ** 2') + =>64 + eval(`0 ** 1') + =>0 + eval(`2 ** 0') + =>1 + eval(`0 ** 0') + => + error->m4:stdin:5: divide by zero in eval: 0 ** 0 + eval(`4 ** -2') + error->m4:stdin:6: negative exponent in eval: 4 ** -2 + => + + Within EXPRESSION, (but not RADIX or WIDTH), numbers without a +special prefix are decimal. A simple '0' prefix introduces an octal +number. '0x' introduces a hexadecimal number. As GNU extensions, '0b' +introduces a binary number. '0r' introduces a number expressed in any +radix between 1 and 36: the prefix should be immediately followed by the +decimal expression of the radix, a colon, then the digits making the +number. For radix 1, leading zeros are ignored, and all remaining +digits must be '1'; for all other radices, the digits are '0', '1', '2', +.... Beyond '9', the digits are 'a', 'b' ... up to 'z'. Lower and +upper case letters can be used interchangeably in numbers prefixes and +as number digits. + + Parentheses may be used to group subexpressions whenever needed. For +the relational operators, a true relation returns '1', and a false +relation return '0'. + + Here are a few examples of use of 'eval'. + + eval(`-3 * 5') + =>-15 + eval(`-99 / 10') + =>-9 + eval(`-99 % 10') + =>-9 + eval(`99 % -10') + =>9 + eval(index(`Hello world', `llo') >= 0) + =>1 + eval(`0r1:0111 + 0b100 + 0r3:12') + =>12 + define(`square', `eval(`($1) ** 2')') + => + square(`9') + =>81 + square(square(`5')` + 1') + =>676 + define(`foo', `666') + => + eval(`foo / 6') + error->m4:stdin:11: bad expression in eval: foo / 6 + => + eval(foo / 6) + =>111 + + As the last two lines show, 'eval' does not handle macro names, even +if they expand to a valid expression (or part of a valid expression). +Therefore all macros must be expanded before they are passed to 'eval'. + + Some calculations are not portable to other implementations, since +they have undefined semantics in C, but GNU 'm4' has well-defined +behavior on overflow. When shifting, an out-of-range shift amount is +implicitly brought into the range of 32-bit signed integers using an +implicit bit-wise and with 0x1f). + + define(`max_int', eval(`0x7fffffff')) + => + define(`min_int', incr(max_int)) + => + eval(min_int` < 0') + =>1 + eval(max_int` > 0') + =>1 + ifelse(eval(min_int` / -1'), min_int, `overflow occurred') + =>overflow occurred + min_int + =>-2147483648 + eval(`0x80000000 % -1') + =>0 + eval(`-4 >> 1') + =>-2 + eval(`-4 >> 33') + =>-2 + + If RADIX is specified, it specifies the radix to be used in the +expansion. The default radix is 10; this is also the case if RADIX is +the empty string. A warning results if the radix is outside the range +of 1 through 36, inclusive. The result of 'eval' is always taken to be +signed. No radix prefix is output, and for radices greater than 10, the +digits are lower case. The WIDTH argument specifies the minimum output +width, excluding any negative sign. The result is zero-padded to extend +the expansion to the requested width. A warning results if the width is +negative. If RADIX or WIDTH is out of bounds, the expansion of 'eval' +is empty. + + eval(`666', `10') + =>666 + eval(`666', `11') + =>556 + eval(`666', `6') + =>3030 + eval(`666', `6', `10') + =>0000003030 + eval(`-666', `6', `10') + =>-0000003030 + eval(`10', `', `0') + =>10 + `0r1:'eval(`10', `1', `11') + =>0r1:01111111111 + eval(`10', `16') + =>a + eval(`1', `37') + error->m4:stdin:9: radix 37 in builtin `eval' out of range + => + eval(`1', , `-1') + error->m4:stdin:10: negative width to builtin `eval' + => + eval() + error->m4:stdin:11: empty string treated as 0 in builtin `eval' + =>0 + + +File: m4.info, Node: Shell commands, Next: Miscellaneous, Prev: Arithmetic, Up: Top + +13 Macros for running shell commands +************************************ + +There are a few builtin macros in 'm4' that allow you to run shell +commands from within 'm4'. + + Note that the definition of a valid shell command is system +dependent. On UNIX systems, this is the typical '/bin/sh'. But on +other systems, such as native Windows, the shell has a different syntax +of commands that it understands. Some examples in this chapter assume +'/bin/sh', and also demonstrate how to quit early with a known exit +value if this is not the case. + +* Menu: + +* Platform macros:: Determining the platform +* Syscmd:: Executing simple commands +* Esyscmd:: Reading the output of commands +* Sysval:: Exit status +* Mkstemp:: Making temporary files + + +File: m4.info, Node: Platform macros, Next: Syscmd, Up: Shell commands + +13.1 Determining the platform +============================= + +Sometimes it is desirable for an input file to know which platform 'm4' +is running on. GNU 'm4' provides several macros that are predefined to +expand to the empty string; checking for their existence will confirm +platform details. + + -- Optional builtin: __gnu__ + -- Optional builtin: __os2__ + -- Optional builtin: os2 + -- Optional builtin: __unix__ + -- Optional builtin: unix + -- Optional builtin: __windows__ + -- Optional builtin: windows + Each of these macros is conditionally defined as needed to describe + the environment of 'm4'. If defined, each macro expands to the + empty string. For now, these macros silently ignore all arguments, + but in a future release of M4, they might warn if arguments are + present. + + When GNU extensions are in effect (that is, when you did not use the +'-G' option, *note Invoking m4: Limits control.), GNU 'm4' will define +the macro '__gnu__' to expand to the empty string. + + $ m4 + __gnu__ + => + __gnu__(`ignored') + => + Extensions are ifdef(`__gnu__', `active', `inactive') + =>Extensions are active + + $ m4 -G + __gnu__ + =>__gnu__ + __gnu__(`ignored') + =>__gnu__(ignored) + Extensions are ifdef(`__gnu__', `active', `inactive') + =>Extensions are inactive + + On UNIX systems, GNU 'm4' will define '__unix__' by default, or +'unix' when the '-G' option is specified. + + On native Windows systems, GNU 'm4' will define '__windows__' by +default, or 'windows' when the '-G' option is specified. + + On OS/2 systems, GNU 'm4' will define '__os2__' by default, or 'os2' +when the '-G' option is specified. + + If GNU 'm4' does not provide a platform macro for your system, please +report that as a bug. + + define(`provided', `0') + => + ifdef(`__unix__', `define(`provided', incr(provided))') + => + ifdef(`__windows__', `define(`provided', incr(provided))') + => + ifdef(`__os2__', `define(`provided', incr(provided))') + => + provided + =>1 + + +File: m4.info, Node: Syscmd, Next: Esyscmd, Prev: Platform macros, Up: Shell commands + +13.2 Executing simple commands +============================== + +Any shell command can be executed, using 'syscmd': + + -- Builtin: syscmd (SHELL-COMMAND) + Executes SHELL-COMMAND as a shell command. + + The expansion of 'syscmd' is void, _not_ the output from + SHELL-COMMAND! Output or error messages from SHELL-COMMAND are not + read by 'm4'. *Note Esyscmd::, if you need to process the command + output. + + Prior to executing the command, 'm4' flushes its buffers. The + default standard input, output and error of SHELL-COMMAND are the + same as those of 'm4'. + + By default, the SHELL-COMMAND will be used as the argument to the + '-c' option of the '/bin/sh' shell (or the version of 'sh' + specified by 'command -p getconf PATH', if your system supports + that). If you prefer a different shell, the 'configure' script can + be given the option '--with-syscmd-shell=LOCATION' to set the + location of an alternative shell at GNU 'm4' installation; the + alternative shell must still support '-c'. + + The macro 'syscmd' is recognized only with parameters. + + define(`foo', `FOO') + => + syscmd(`echo foo') + =>foo + => + + Note how the expansion of 'syscmd' keeps the trailing newline of the +command, as well as using the newline that appeared after the macro. + + The following is an example of SHELL-COMMAND using the same standard +input as 'm4': + + $ echo "m4wrap(\`syscmd(\`cat')')" | m4 + => + + It tells 'm4' to read all of its input before executing the wrapped +text, then hand a valid (albeit emptied) pipe as standard input for the +'cat' subcommand. Therefore, you should be careful when using standard +input (either by specifying no files, or by passing '-' as a file name +on the command line, *note Invoking m4: Command line files.), and also +invoking subcommands via 'syscmd' or 'esyscmd' that consume data from +standard input. When standard input is a seekable file, the subprocess +will pick up with the next character not yet processed by 'm4'; when it +is a pipe or other non-seekable file, there is no guarantee how much +data will already be buffered by 'm4' and thus unavailable to the child. + + +File: m4.info, Node: Esyscmd, Next: Sysval, Prev: Syscmd, Up: Shell commands + +13.3 Reading the output of commands +=================================== + +If you want 'm4' to read the output of a shell command, use 'esyscmd': + + -- Builtin: esyscmd (SHELL-COMMAND) + Expands to the standard output of the shell command SHELL-COMMAND. + + Prior to executing the command, 'm4' flushes its buffers. The + default standard input and standard error of SHELL-COMMAND are the + same as those of 'm4'. The error output of SHELL-COMMAND is not a + part of the expansion: it will appear along with the error output + of 'm4'. + + By default, the SHELL-COMMAND will be used as the argument to the + '-c' option of the '/bin/sh' shell (or the version of 'sh' + specified by 'command -p getconf PATH', if your system supports + that). If you prefer a different shell, the 'configure' script can + be given the option '--with-syscmd-shell=LOCATION' to set the + location of an alternative shell at GNU 'm4' installation; the + alternative shell must still support '-c'. + + The macro 'esyscmd' is recognized only with parameters. + + define(`foo', `FOO') + => + esyscmd(`echo foo') + =>FOO + => + + Note how the expansion of 'esyscmd' keeps the trailing newline of the +command, as well as using the newline that appeared after the macro. + + Just as with 'syscmd', care must be exercised when sharing standard +input between 'm4' and the child process of 'esyscmd'. + + +File: m4.info, Node: Sysval, Next: Mkstemp, Prev: Esyscmd, Up: Shell commands + +13.4 Exit status +================ + +To see whether a shell command succeeded, use 'sysval': + + -- Builtin: sysval + Expands to the exit status of the last shell command run with + 'syscmd' or 'esyscmd'. Expands to 0 if no command has been run + yet. + + sysval + =>0 + syscmd(`false') + => + ifelse(sysval, `0', `zero', `non-zero') + =>non-zero + syscmd(`exit 2') + => + sysval + =>2 + syscmd(`true') + => + sysval + =>0 + esyscmd(`false') + => + ifelse(sysval, `0', `zero', `non-zero') + =>non-zero + esyscmd(`echo dnl && exit 127') + => + sysval + =>127 + esyscmd(`true') + => + sysval + =>0 + + 'sysval' results in 127 if there was a problem executing the command, +for example, if the system-imposed argument length is exceeded, or if +there were not enough resources to fork. It is not possible to +distinguish between failed execution and successful execution that had +an exit status of 127, unless there was output from the child process. + + On UNIX platforms, where it is possible to detect when command +execution is terminated by a signal, rather than a normal exit, the +result is the signal number shifted left by eight bits. + + dnl This test assumes kill is a shell builtin, and that signals are + dnl recognizable. + ifdef(`__unix__', , + `errprint(` skipping: syscmd does not have unix semantics + ')m4exit(`77')')dnl + syscmd(`kill -9 $$') + => + sysval + =>2304 + syscmd() + => + sysval + =>0 + esyscmd(`kill -9 $$') + => + sysval + =>2304 + + +File: m4.info, Node: Mkstemp, Prev: Sysval, Up: Shell commands + +13.5 Making temporary files +=========================== + +Commands specified to 'syscmd' or 'esyscmd' might need a temporary file, +for output or for some other purpose. There is a builtin macro, +'mkstemp', for making a temporary file: + + -- Builtin: mkstemp (TEMPLATE) + -- Builtin: maketemp (TEMPLATE) + Expands to the quoted name of a new, empty file, made from the + string TEMPLATE, which should end with the string 'XXXXXX'. The + six 'X' characters are then replaced with random characters + matching the regular expression '[a-zA-Z0-9._-]', in order to make + the file name unique. If fewer than six 'X' characters are found + at the end of 'template', the result will be longer than the + template. The created file will have access permissions as if by + 'chmod =rw,go=', meaning that the current umask of the 'm4' process + is taken into account, and at most only the current user can read + and write the file. + + The traditional behavior, standardized by POSIX, is that 'maketemp' + merely replaces the trailing 'X' with the process id, without + creating a file or quoting the expansion, and without ensuring that + the resulting string is a unique file name. In part, this means + that using the same TEMPLATE twice in the same input file will + result in the same expansion. This behavior is a security hole, as + it is very easy for another process to guess the name that will be + generated, and thus interfere with a subsequent use of 'syscmd' + trying to manipulate that file name. Hence, POSIX has recommended + that all new implementations of 'm4' provide the secure 'mkstemp' + builtin, and that users of 'm4' check for its existence. + + The expansion is void and an error issued if a temporary file could + not be created. + + The macros 'mkstemp' and 'maketemp' are recognized only with + parameters. + + If you try this next example, you will most likely get different +output for the two file names, since the replacement characters are +randomly chosen: + + $ m4 + define(`tmp', `oops') + => + maketemp(`/tmp/fooXXXXXX') + =>/tmp/fooa07346 + ifdef(`mkstemp', `define(`maketemp', defn(`mkstemp'))', + `define(`mkstemp', defn(`maketemp'))dnl + errprint(`warning: potentially insecure maketemp implementation + ')') + => + mkstemp(`doc') + =>docQv83Uw + + Unless you use the '--traditional' command line option (or '-G', +*note Invoking m4: Limits control.), the GNU version of 'maketemp' is +secure. This means that using the same template to multiple calls will +generate multiple files. However, we recommend that you use the new +'mkstemp' macro, introduced in GNU M4 1.4.8, which is secure even in +traditional mode. Also, as of M4 1.4.11, the secure implementation +quotes the resulting file name, so that you are guaranteed to know what +file was created even if the random file name happens to match an +existing macro. Notice that this example is careful to use 'defn' to +avoid unintended expansion of 'foo'. + + $ m4 + define(`foo', `errprint(`oops')') + => + syscmd(`rm -f foo-??????')sysval + =>0 + define(`file1', maketemp(`foo-XXXXXX'))dnl + ifelse(esyscmd(`echo \` foo-?????? \''), ` foo-?????? ', + `no file', `created') + =>created + define(`file2', maketemp(`foo-XX'))dnl + define(`file3', mkstemp(`foo-XXXXXX'))dnl + ifelse(len(defn(`file1')), len(defn(`file2')), + `same length', `different') + =>same length + ifelse(defn(`file1'), defn(`file2'), `same', `different file') + =>different file + ifelse(defn(`file2'), defn(`file3'), `same', `different file') + =>different file + ifelse(defn(`file1'), defn(`file3'), `same', `different file') + =>different file + syscmd(`rm 'defn(`file1') defn(`file2') defn(`file3')) + => + sysval + =>0 + + +File: m4.info, Node: Miscellaneous, Next: Frozen files, Prev: Shell commands, Up: Top + +14 Miscellaneous builtin macros +******************************* + +This chapter describes various builtins, that do not really belong in +any of the previous chapters. + +* Menu: + +* Errprint:: Printing error messages +* Location:: Printing current location +* M4exit:: Exiting from 'm4' + + +File: m4.info, Node: Errprint, Next: Location, Up: Miscellaneous + +14.1 Printing error messages +============================ + +You can print error messages using 'errprint': + + -- Builtin: errprint (MESSAGE, ...) + Prints MESSAGE and the rest of the arguments to standard error, + separated by spaces. Standard error is used, regardless of the + '--debugfile' option (*note Invoking m4: Debugging options.). + + The expansion of 'errprint' is void. The macro 'errprint' is + recognized only with parameters. + + errprint(`Invalid arguments to forloop + ') + error->Invalid arguments to forloop + => + errprint(`1')errprint(`2',`3 + ') + error->12 3 + => + + A trailing newline is _not_ printed automatically, so it should be +supplied as part of the argument, as in the example. Unfortunately, the +exact output of 'errprint' is not very portable to other 'm4' +implementations: POSIX requires that all arguments be printed, but some +implementations of 'm4' only print the first. Furthermore, some BSD +implementations always append a newline for each 'errprint' call, +regardless of whether the last argument already had one, and POSIX is +silent on whether this is acceptable. + + +File: m4.info, Node: Location, Next: M4exit, Prev: Errprint, Up: Miscellaneous + +14.2 Printing current location +============================== + +To make it possible to specify the location of an error, three utility +builtins exist: + + -- Builtin: __file__ + -- Builtin: __line__ + -- Builtin: __program__ + Expand to the quoted name of the current input file, the current + input line number in that file, and the quoted name of the current + invocation of 'm4'. + + errprint(__program__:__file__:__line__: `input error + ') + error->m4:stdin:1: input error + => + + Line numbers start at 1 for each file. If the file was found due to +the '-I' option or 'M4PATH' environment variable, that is reflected in +the file name. The syncline option ('-s', *note Invoking m4: +Preprocessor features.), and the 'f' and 'l' flags of 'debugmode' (*note +Debug Levels::), also use this notion of current file and line. +Redefining the three location macros has no effect on syncline, debug, +warning, or error message output. + + This example reuses the file 'incl.m4' mentioned earlier (*note +Include::): + + $ m4 -I examples + define(`foo', ``$0' called at __file__:__line__') + => + foo + =>foo called at stdin:2 + include(`incl.m4') + =>Include file start + =>foo called at examples/incl.m4:2 + =>Include file end + => + + The location of macros invoked during the rescanning of macro +expansion text corresponds to the location in the file where the +expansion was triggered, regardless of how many newline characters the +expansion text contains. As of GNU M4 1.4.8, the location of text +wrapped with 'm4wrap' (*note M4wrap::) is the point at which the +'m4wrap' was invoked. Previous versions, however, behaved as though +wrapped text came from line 0 of the file "". + + define(`echo', `$@') + => + define(`foo', `echo(__line__ + __line__)') + => + echo(__line__ + __line__) + =>4 + =>5 + m4wrap(`foo + ') + => + foo(errprint(__line__ + __line__ + )) + error->8 + error->9 + =>8 + =>8 + __line__ + =>11 + m4wrap(`__line__ + ') + => + ^D + =>12 + =>6 + =>6 + + The '__program__' macro behaves like '$0' in shell terminology. If +you invoke 'm4' through an absolute path or a link with a different +spelling, rather than by relying on a 'PATH' search for plain 'm4', it +will affect how '__program__' expands. The intent is that you can use +it to produce error messages with the same formatting that 'm4' produces +internally. It can also be used within 'syscmd' (*note Syscmd::) to +pick the same version of 'm4' that is currently running, rather than +whatever version of 'm4' happens to be first in 'PATH'. It was first +introduced in GNU M4 1.4.6. + + +File: m4.info, Node: M4exit, Prev: Location, Up: Miscellaneous + +14.3 Exiting from 'm4' +====================== + +If you need to exit from 'm4' before the entire input has been read, you +can use 'm4exit': + + -- Builtin: m4exit ([CODE = '0'] + Causes 'm4' to exit, with exit status CODE. If CODE is left out, + the exit status is zero. If CODE cannot be parsed, or is outside + the range of 0 to 255, the exit status is one. No further input is + read, and all wrapped and diverted text is discarded. + + m4wrap(`This text is lost due to `m4exit'.') + => + divert(`1') So is this. + divert + => + m4exit And this is never read. + + A common use of this is to abort processing: + + -- Composite: fatal_error (MESSAGE) + Abort processing with an error message and non-zero status. Prefix + MESSAGE with details about where the error occurred, and print the + resulting string to standard error. + + define(`fatal_error', + `errprint(__program__:__file__:__line__`: fatal error: $* + ')m4exit(`1')') + => + fatal_error(`this is a BAD one, buster') + error->m4:stdin:4: fatal error: this is a BAD one, buster + + After this macro call, 'm4' will exit with exit status 1. This macro +is only intended for error exits, since the normal exit procedures are +not followed, i.e., diverted text is not undiverted, and saved text +(*note M4wrap::) is not reread. (This macro could be made more robust +to earlier versions of 'm4'. You should try to see if you can find +weaknesses and correct them; or *note Answers: Improved fatal_error.). + + Note that it is still possible for the exit status to be different +than what was requested by 'm4exit'. If 'm4' detects some other error, +such as a write error on standard output, the exit status will be +non-zero even if 'm4exit' requested zero. + + If standard input is seekable, then the file will be positioned at +the next unread character. If it is a pipe or other non-seekable file, +then there are no guarantees how much data 'm4' might have read into +buffers, and thus discarded. + + +File: m4.info, Node: Frozen files, Next: Compatibility, Prev: Miscellaneous, Up: Top + +15 Fast loading of frozen state +******************************* + +Some bigger 'm4' applications may be built over a common base containing +hundreds of definitions and other costly initializations. Usually, the +common base is kept in one or more declarative files, which files are +listed on each 'm4' invocation prior to the user's input file, or else +each input file uses 'include'. + + Reading the common base of a big application, over and over again, +may be time consuming. GNU 'm4' offers some machinery to speed up the +start of an application using lengthy common bases. + +* Menu: + +* Using frozen files:: Using frozen files +* Frozen file format:: Frozen file format + + +File: m4.info, Node: Using frozen files, Next: Frozen file format, Up: Frozen files + +15.1 Using frozen files +======================= + +Suppose a user has a library of 'm4' initializations in 'base.m4', which +is then used with multiple input files: + + $ m4 base.m4 input1.m4 + $ m4 base.m4 input2.m4 + $ m4 base.m4 input3.m4 + + Rather than spending time parsing the fixed contents of 'base.m4' +every time, the user might rather execute: + + $ m4 -F base.m4f base.m4 + +once, and further execute, as often as needed: + + $ m4 -R base.m4f input1.m4 + $ m4 -R base.m4f input2.m4 + $ m4 -R base.m4f input3.m4 + +with the varying input. The first call, containing the '-F' option, +only reads and executes file 'base.m4', defining various application +macros and computing other initializations. Once the input file +'base.m4' has been completely processed, GNU 'm4' produces in 'base.m4f' +a "frozen" file, that is, a file which contains a kind of snapshot of +the 'm4' internal state. + + Later calls, containing the '-R' option, are able to reload the +internal state of 'm4', from 'base.m4f', _prior_ to reading any other +input files. This means instead of starting with a virgin copy of 'm4', +input will be read after having effectively recovered the effect of a +prior run. In our example, the effect is the same as if file 'base.m4' +has been read anew. However, this effect is achieved a lot faster. + + Only one frozen file may be created or read in any one 'm4' +invocation. It is not possible to recover two frozen files at once. +However, frozen files may be updated incrementally, through using '-R' +and '-F' options simultaneously. For example, if some care is taken, +the command: + + $ m4 file1.m4 file2.m4 file3.m4 file4.m4 + +could be broken down in the following sequence, accumulating the same +output: + + $ m4 -F file1.m4f file1.m4 + $ m4 -R file1.m4f -F file2.m4f file2.m4 + $ m4 -R file2.m4f -F file3.m4f file3.m4 + $ m4 -R file3.m4f file4.m4 + + Some care is necessary because not every effort has been made for +this to work in all cases. In particular, the trace attribute of macros +is not handled, nor the current setting of 'changeword'. Currently, +'m4wrap' and 'sysval' also have problems. Also, interactions for some +options of 'm4', being used in one call and not in the next, have not +been fully analyzed yet. On the other end, you may be confident that +stacks of 'pushdef' definitions are handled correctly, as well as +undefined or renamed builtins, and changed strings for quotes or +comments. And future releases of GNU M4 will improve on the utility of +frozen files. + + When an 'm4' run is to be frozen, the automatic undiversion which +takes place at end of execution is inhibited. Instead, all positively +numbered diversions are saved into the frozen file. The active +diversion number is also transmitted. + + A frozen file to be reloaded need not reside in the current +directory. It is looked up the same way as an 'include' file (*note +Search Path::). + + If the frozen file was generated with a newer version of 'm4', and +contains directives that an older 'm4' cannot parse, attempting to load +the frozen file with option '-R' will cause 'm4' to exit with status 63 +to indicate version mismatch. + + +File: m4.info, Node: Frozen file format, Prev: Using frozen files, Up: Frozen files + +15.2 Frozen file format +======================= + +Frozen files are sharable across architectures. It is safe to write a +frozen file on one machine and read it on another, given that the second +machine uses the same or newer version of GNU 'm4'. It is conventional, +but not required, to give a frozen file the suffix of '.m4f'. + + These are simple (editable) text files, made up of directives, each +starting with a capital letter and ending with a newline (<NL>). +Wherever a directive is expected, the character '#' introduces a comment +line; empty lines are also ignored if they are not part of an embedded +string. In the following descriptions, each LEN refers to the length of +the corresponding strings STR in the next line of input. Numbers are +always expressed in decimal. There are no escape characters. The +directives are: + +'C LEN1 , LEN2 <NL> STR1 STR2 <NL>' + Uses STR1 and STR2 as the begin-comment and end-comment strings. + If omitted, then '#' and <NL> are the comment delimiters. + +'D NUMBER, LEN <NL> STR <NL>' + Selects diversion NUMBER, making it current, then copy STR in the + current diversion. NUMBER may be a negative number for a + non-existing diversion. To merely specify an active selection, use + this command with an empty STR. With 0 as the diversion NUMBER, + STR will be issued on standard output at reload time. GNU 'm4' + will not produce the 'D' directive with non-zero length for + diversion 0, but this can be done with manual edits. This + directive may appear more than once for the same diversion, in + which case the diversion is the concatenation of the various uses. + If omitted, then diversion 0 is current. + +'F LEN1 , LEN2 <NL> STR1 STR2 <NL>' + Defines, through 'pushdef', a definition for STR1 expanding to the + function whose builtin name is STR2. If the builtin does not exist + (for example, if the frozen file was produced by a copy of 'm4' + compiled with changeword support, but the version of 'm4' reloading + was compiled without it), the reload is silent, but any subsequent + use of the definition of STR1 will result in a warning. This + directive may appear more than once for the same name, and its + order, along with 'T', is important. If omitted, you will have no + access to any builtins. + +'Q LEN1 , LEN2 <NL> STR1 STR2 <NL>' + Uses STR1 and STR2 as the begin-quote and end-quote strings. If + omitted, then '`' and ''' are the quote delimiters. + +'T LEN1 , LEN2 <NL> STR1 STR2 <NL>' + Defines, though 'pushdef', a definition for STR1 expanding to the + text given by STR2. This directive may appear more than once for + the same name, and its order, along with 'F', is important. + +'V NUMBER <NL>' + Confirms the format of the file. 'm4' 1.4.17 only creates and + understands frozen files where NUMBER is 1. This directive must be + the first non-comment in the file, and may not appear more than + once. + + +File: m4.info, Node: Compatibility, Next: Answers, Prev: Frozen files, Up: Top + +16 Compatibility with other versions of 'm4' +******************************************** + +This chapter describes the many of the differences between this +implementation of 'm4', and of other implementations found under UNIX, +such as System V Release 4, Solaris, and BSD flavors. In particular, it +lists the known differences and extensions to POSIX. However, the list +is not necessarily comprehensive. + + At the time of this writing, POSIX 2001 (also known as IEEE Std +1003.1-2001) is the latest standard, although a new version of POSIX is +under development and includes several proposals for modifying what 'm4' +is required to do. The requirements for 'm4' are shared between SUSv3 +and POSIX, and can be viewed at +<http://www.opengroup.org/onlinepubs/000095399/utilities/m4.html>. + +* Menu: + +* Extensions:: Extensions in GNU M4 +* Incompatibilities:: Facilities in System V m4 not in GNU M4 +* Other Incompatibilities:: Other incompatibilities + + +File: m4.info, Node: Extensions, Next: Incompatibilities, Up: Compatibility + +16.1 Extensions in GNU M4 +========================= + +This version of 'm4' contains a few facilities that do not exist in +System V 'm4'. These extra facilities are all suppressed by using the +'-G' command line option (*note Invoking m4: Limits control.), unless +overridden by other command line options. + + * In the '$N' notation for macro arguments, N can contain several + digits, while the System V 'm4' only accepts one digit. This + allows macros in GNU 'm4' to take any number of arguments, and not + only nine (*note Arguments::). + + This means that 'define(`foo', `$11')' is ambiguous between + implementations. To portably choose between grabbing the first + parameter and appending 1 to the expansion, or grabbing the + eleventh parameter, you can do the following: + + define(`a1', `A1') + => + dnl First argument, concatenated with 1 + define(`_1', `$1')define(`first1', `_1($@)1') + => + dnl Eleventh argument, portable + define(`_9', `$9')define(`eleventh', `_9(shift(shift($@)))') + => + dnl Eleventh argument, GNU style + define(`Eleventh', `$11') + => + first1(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') + =>A1 + eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') + =>k + Eleventh(`a', `b', `c', `d', `e', `f', `g', `h', `i', `j', `k') + =>k + + Also see the 'argn' macro (*note Shift::). + + * The 'divert' (*note Divert::) macro can manage more than 9 + diversions. GNU 'm4' treats all positive numbers as valid + diversions, rather than discarding diversions greater than 9. + + * Files included with 'include' and 'sinclude' are sought in a user + specified search path, if they are not found in the working + directory. The search path is specified by the '-I' option and the + 'M4PATH' environment variable (*note Search Path::). + + * Arguments to 'undivert' can be non-numeric, in which case the named + file will be included uninterpreted in the output (*note + Undivert::). + + * Formatted output is supported through the 'format' builtin, which + is modeled after the C library function 'printf' (*note Format::). + + * Searches and text substitution through basic regular expressions + are supported by the 'regexp' (*note Regexp::) and 'patsubst' + (*note Patsubst::) builtins. Some BSD implementations use extended + regular expressions instead. + + * The output of shell commands can be read into 'm4' with 'esyscmd' + (*note Esyscmd::). + + * There is indirect access to any builtin macro with 'builtin' (*note + Builtin::). + + * Macros can be called indirectly through 'indir' (*note Indir::). + + * The name of the program, the current input file, and the current + input line number are accessible through the builtins + '__program__', '__file__', and '__line__' (*note Location::). + + * The format of the output from 'dumpdef' and macro tracing can be + controlled with 'debugmode' (*note Debug Levels::). + + * The destination of trace and debug output can be controlled with + 'debugfile' (*note Debug Output::). + + * The 'maketemp' (*note Mkstemp::) macro behaves like 'mkstemp', + creating a new file with a unique name on every invocation, rather + than following the insecure behavior of replacing the trailing 'X' + characters with the 'm4' process id. + + * POSIX only requires support for the command line options '-s', + '-D', and '-U', so all other options accepted by GNU M4 are + extensions. *Note Invoking m4::, for a description of these + options. + + The debugging and tracing facilities in GNU 'm4' are much more + extensive than in most other versions of 'm4'. + + +File: m4.info, Node: Incompatibilities, Next: Other Incompatibilities, Prev: Extensions, Up: Compatibility + +16.2 Facilities in System V 'm4' not in GNU 'm4' +================================================ + +The version of 'm4' from System V contains a few facilities that have +not been implemented in GNU 'm4' yet. Additionally, POSIX requires some +behaviors that GNU 'm4' has not implemented yet. Relying on these +behaviors is non-portable, as a future release of GNU 'm4' may change. + + * POSIX requires support for multiple arguments to 'defn', without + any clarification on how 'defn' behaves when one of the multiple + arguments names a builtin. System V 'm4' and some other + implementations allow mixing builtins and text macros into a single + macro. GNU 'm4' only supports joining multiple text arguments, + although a future implementation may lift this restriction to + behave more like System V. The only portable way to join text + macros with builtins is via helper macros and implicit + concatenation of macro results. + + * POSIX requires an application to exit with non-zero status if it + wrote an error message to stderr. This has not yet been + consistently implemented for the various builtins that are required + to issue an error (such as 'eval' (*note Eval::) when an argument + cannot be parsed). + + * Some traditional implementations only allow reading standard input + once, but GNU 'm4' correctly handles multiple instances of '-' on + the command line. + + * POSIX requires 'm4wrap' (*note M4wrap::) to act in FIFO (first-in, + first-out) order, but GNU 'm4' currently uses LIFO order. + Furthermore, POSIX states that only the first argument to 'm4wrap' + is saved for later evaluation, but GNU 'm4' saves and processes all + arguments, with output separated by spaces. + + * POSIX states that builtins that require arguments, but are called + without arguments, have undefined behavior. Traditional + implementations simply behave as though empty strings had been + passed. For example, 'a`'define`'b' would expand to 'ab'. But GNU + 'm4' ignores certain builtins if they have missing arguments, + giving 'adefineb' for the above example. + + * Traditional implementations handle 'define(`f',`1')' (*note + Define::) by undefining the entire stack of previous definitions, + and if doing 'undefine(`f')' first. GNU 'm4' replaces just the top + definition on the stack, as if doing 'popdef(`f')' followed by + 'pushdef(`f',`1')'. POSIX allows either behavior. + + * POSIX 2001 requires 'syscmd' (*note Syscmd::) to evaluate command + output for macro expansion, but this was a mistake that is + anticipated to be corrected in the next version of POSIX. GNU 'm4' + follows traditional behavior in 'syscmd' where output is not + rescanned, and provides the extension 'esyscmd' that does scan the + output. + + * At one point, POSIX required 'changequote(ARG)' (*note + Changequote::) to use newline as the close quote, but this was a + bug, and the next version of POSIX is anticipated to state that + using empty strings or just one argument is unspecified. + Meanwhile, the GNU 'm4' behavior of treating an empty end-quote + delimiter as ''' is not portable, as Solaris treats it as repeating + the start-quote delimiter, and BSD treats it as leaving the + previous end-quote delimiter unchanged. For predictable results, + never call changequote with just one argument, or with empty + strings for arguments. + + * At one point, POSIX required 'changecom(ARG,)' (*note Changecom::) + to make it impossible to end a comment, but this is a bug, and the + next version of POSIX is anticipated to state that using empty + strings is unspecified. Meanwhile, the GNU 'm4' behavior of + treating an empty end-comment delimiter as newline is not portable, + as BSD treats it as leaving the previous end-comment delimiter + unchanged. It is also impossible in BSD implementations to disable + comments, even though that is required by POSIX. For predictable + results, never call changecom with empty strings for arguments. + + * Most implementations of 'm4' give macros a higher precedence than + comments when parsing, meaning that if the start delimiter given to + 'changecom' (*note Changecom::) starts with a macro name, comments + are effectively disabled. POSIX does not specify what the + precedence is, so this version of GNU 'm4' parser recognizes + comments, then macros, then quoted strings. + + * Traditional implementations allow argument collection, but not + string and comment processing, to span file boundaries. Thus, if + 'a.m4' contains 'len(', and 'b.m4' contains 'abc)', 'm4 a.m4 b.m4' + outputs '3' with traditional 'm4', but gives an error message that + the end of file was encountered inside a macro with GNU 'm4'. On + the other hand, traditional implementations do end of file + processing for files included with 'include' or 'sinclude' (*note + Include::), while GNU 'm4' seamlessly integrates the content of + those files. Thus 'include(`a.m4')include(`b.m4')' will output '3' + instead of giving an error. + + * Traditional 'm4' treats 'traceon' (*note Trace::) without arguments + as a global variable, independent of named macro tracing. Also, + once a macro is undefined, named tracing of that macro is lost. On + the other hand, when GNU 'm4' encounters 'traceon' without + arguments, it turns tracing on for all existing definitions at the + time, but does not trace future definitions; 'traceoff' without + arguments turns tracing off for all definitions regardless of + whether they were also traced by name; and tracing by name, such as + with '-tfoo' at the command line or 'traceon(`foo')' in the input, + is an attribute that is preserved even if the macro is currently + undefined. + + Additionally, while POSIX requires trace output, it makes no + demands on the formatting of that output. Parsing trace output is + not guaranteed to be reliable, even between different releases of + GNU M4; however, the intent is that any future changes in trace + output will only occur under the direction of additional + 'debugmode' flags (*note Debug Levels::). + + * POSIX requires 'eval' (*note Eval::) to treat all operators with + the same precedence as C. However, earlier versions of GNU 'm4' + followed the traditional behavior of other 'm4' implementations, + where bitwise and logical negation ('~' and '!') have lower + precedence than equality operators; and where equality operators + ('==' and '!=') had the same precedence as relational operators + (such as '<'). Use explicit parentheses to ensure proper + precedence. As extensions to POSIX, GNU 'm4' gives well-defined + semantics to operations that C leaves undefined, such as when + overflow occurs, when shifting negative numbers, or when performing + division by zero. POSIX also requires '=' to cause an error, but + many traditional implementations allowed it as an alias for '=='. + + * POSIX 2001 requires 'translit' (*note Translit::) to treat each + character of the second and third arguments literally. However, it + is anticipated that the next version of POSIX will allow the GNU + 'm4' behavior of treating '-' as a range operator. + + * POSIX requires 'm4' to honor the locale environment variables of + 'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', and 'NLSPATH', but + this has not yet been implemented in GNU 'm4'. + + * POSIX states that only unquoted leading newlines and blanks (that + is, space and tab) are ignored when collecting macro arguments. + However, this appears to be a bug in POSIX, since most traditional + implementations also ignore all whitespace (formfeed, carriage + return, and vertical tab). GNU 'm4' follows tradition and ignores + all leading unquoted whitespace. + + * A strictly-compliant POSIX client is not allowed to use + command-line arguments not specified by POSIX. However, since this + version of M4 ignores 'POSIXLY_CORRECT' and enables the option + '--gnu' by default (*note Invoking m4: Limits control.), a client + desiring to be strictly compliant has no way to disable GNU + extensions that conflict with POSIX when directly invoking the + compiled 'm4'. A future version of 'GNU' M4 will honor the + environment variable 'POSIXLY_CORRECT', implicitly enabling + '--traditional' if it is set, in order to allow a + strictly-compliant client. In the meantime, a client needing + strict POSIX compliance can use the workaround of invoking a shell + script wrapper, where the wrapper then adds '--traditional' to the + arguments passed to the compiled 'm4'. + + +File: m4.info, Node: Other Incompatibilities, Prev: Incompatibilities, Up: Compatibility + +16.3 Other incompatibilities +============================ + +There are a few other incompatibilities between this implementation of +'m4', and the System V version. + + * GNU 'm4' implements sync lines differently from System V 'm4', when + text is being diverted. GNU 'm4' outputs the sync lines when the + text is being diverted, and System V 'm4' when the diverted text is + being brought back. + + The problem is which lines and file names should be attached to + text that is being, or has been, diverted. System V 'm4' regards + all the diverted text as being generated by the source line + containing the 'undivert' call, whereas GNU 'm4' regards the + diverted text as being generated at the time it is diverted. + + The sync line option is used mostly when using 'm4' as a front end + to a compiler. If a diverted line causes a compiler error, the + error messages should most probably refer to the place where the + diversion was made, and not where it was inserted again. + + divert(2)2 + divert(1)1 + divert`'0 + =>#line 3 "stdin" + =>0 + ^D + =>#line 2 "stdin" + =>1 + =>#line 1 "stdin" + =>2 + + The current 'm4' implementation has a limitation that the syncline + output at the start of each diversion occurs no matter what, even + if the previous diversion did not end with a newline. This goes + contrary to the claim that synclines appear on a line by + themselves, so this limitation may be corrected in a future version + of 'm4'. In the meantime, when using '-s', it is wisest to make + sure all diversions end with newline. + + * GNU 'm4' makes no attempt at prohibiting self-referential + definitions like: + + define(`x', `x') + => + define(`x', `x ') + => + + There is nothing inherently wrong with defining 'x' to return 'x'. + The wrong thing is to expand 'x' unquoted, because that would cause + an infinite rescan loop. In 'm4', one might use macros to hold + strings, as we do for variables in other programming languages, + further checking them with: + + ifelse(defn(`HOLDER'), `VALUE', ...) + + In cases like this one, an interdiction for a macro to hold its own + name would be a useless limitation. Of course, this leaves more + rope for the GNU 'm4' user to hang himself! Rescanning hangs may + be avoided through careful programming, a little like for endless + loops in traditional programming languages. + + +File: m4.info, Node: Answers, Next: Copying This Package, Prev: Compatibility, Up: Top + +17 Correct version of some examples +*********************************** + +Some of the examples in this manuals are buggy or not very robust, for +demonstration purposes. Improved versions of these composite macros are +presented here. + +* Menu: + +* Improved exch:: Solution for 'exch' +* Improved forloop:: Solution for 'forloop' +* Improved foreach:: Solution for 'foreach' +* Improved copy:: Solution for 'copy' +* Improved m4wrap:: Solution for 'm4wrap' +* Improved cleardivert:: Solution for 'cleardivert' +* Improved capitalize:: Solution for 'capitalize' +* Improved fatal_error:: Solution for 'fatal_error' + + +File: m4.info, Node: Improved exch, Next: Improved forloop, Up: Answers + +17.1 Solution for 'exch' +======================== + +The 'exch' macro (*note Arguments::) as presented requires clients to +double quote their arguments. A nicer definition, which lets clients +follow the rule of thumb of one level of quoting per level of +parentheses, involves adding quotes in the definition of 'exch', as +follows: + + define(`exch', ``$2', `$1'') + => + define(exch(`expansion text', `macro')) + => + macro + =>expansion text + + +File: m4.info, Node: Improved forloop, Next: Improved foreach, Prev: Improved exch, Up: Answers + +17.2 Solution for 'forloop' +=========================== + +The 'forloop' macro (*note Forloop::) as presented earlier can go into +an infinite loop if given an iterator that is not parsed as a macro +name. It does not do any sanity checking on its numeric bounds, and +only permits decimal numbers for bounds. Here is an improved version, +shipped as 'm4-1.4.17/examples/forloop2.m4'; this version also optimizes +overhead by calling four macros instead of six per iteration (excluding +those in TEXT), by not dereferencing the ITERATOR in the helper +'_forloop'. + + $ m4 -d -I examples + undivert(`forloop2.m4')dnl + =>divert(`-1') + =># forloop(var, from, to, stmt) - improved version: + =># works even if VAR is not a strict macro name + =># performs sanity check that FROM is larger than TO + =># allows complex numerical expressions in TO and FROM + =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1', + => `pushdef(`$1')_$0(`$1', eval(`$2'), + => eval(`$3'), `$4')popdef(`$1')')') + =>define(`_forloop', + => `define(`$1', `$2')$4`'ifelse(`$2', `$3', `', + => `$0(`$1', incr(`$2'), `$3', `$4')')') + =>divert`'dnl + include(`forloop2.m4') + => + forloop(`i', `2', `1', `no iteration occurs') + => + forloop(`', `1', `2', ` odd iterator name') + => odd iterator name odd iterator name + forloop(`i', `5 + 5', `0xc', ` 0x`'eval(i, `16')') + => 0xa 0xb 0xc + forloop(`i', `a', `b', `non-numeric bounds') + error->m4:stdin:6: bad expression in eval (bad input): (a) <= (b) + => + + One other change to notice is that the improved version used '_$0' +rather than '_foreach' to invoke the helper routine. In general, this +is a good practice to follow, because then the set of macros can be +uniformly transformed. The following example shows a transformation +that doubles the current quoting and appends a suffix '2' to each +transformed macro. If 'foreach' refers to the literal '_foreach', then +'foreach2' invokes '_foreach' instead of the intended '_foreach2', and +the mixing of quoting paradigms leads to an infinite recursion loop in +this example. + + $ m4 -d -L 9 -I examples + define(`arg1', `$1')include(`forloop2.m4')include(`quote.m4') + => + define(`double', `define(`$1'`2', + arg1(patsubst(dquote(defn(`$1')), `[`']', `\&\&')))') + => + double(`forloop')double(`_forloop')defn(`forloop2') + =>ifelse(eval(``($2) <= ($3)''), ``1'', + => ``pushdef(``$1'')_$0(``$1'', eval(``$2''), + => eval(``$3''), ``$4'')popdef(``$1'')'') + forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)') + => + changequote(`[', `]')changequote([``], ['']) + => + forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'') + => + changequote`'include(`forloop.m4') + => + double(`forloop')double(`_forloop')defn(`forloop2') + =>pushdef(``$1'', ``$2'')_forloop($@)popdef(``$1'') + forloop(i, 1, 5, `ifelse(')forloop(i, 1, 5, `)') + => + changequote(`[', `]')changequote([``], ['']) + => + forloop2(i, 1, 5, ``ifelse('')forloop2(i, 1, 5, ``)'') + error->m4:stdin:12: recursion limit of 9 exceeded, use -L<N> to change it + + One more optimization is still possible. Instead of repeatedly +assigning a variable then invoking or dereferencing it, it is possible +to pass the current iterator value as a single argument. Coupled with +'curry' if other arguments are needed (*note Composition::), or with +helper macros if the argument is needed in more than one place in the +expansion, the output can be generated with three, rather than four, +macros of overhead per iteration. Notice how the file +'m4-1.4.17/examples/forloop3.m4' rearranges the arguments of the helper +'_forloop' to take two arguments that are placed around the current +value. By splitting a balanced set of parantheses across multiple +arguments, the helper macro can now be shared by 'forloop' and the new +'forloop_arg'. + + $ m4 -I examples + include(`forloop3.m4') + => + undivert(`forloop3.m4')dnl + =>divert(`-1') + =># forloop_arg(from, to, macro) - invoke MACRO(value) for + =># each value between FROM and TO, without define overhead + =>define(`forloop_arg', `ifelse(eval(`($1) <= ($2)'), `1', + => `_forloop(`$1', eval(`$2'), `$3(', `)')')') + =># forloop(var, from, to, stmt) - refactored to share code + =>define(`forloop', `ifelse(eval(`($2) <= ($3)'), `1', + => `pushdef(`$1')_forloop(eval(`$2'), eval(`$3'), + => `define(`$1',', `)$4')popdef(`$1')')') + =>define(`_forloop', + => `$3`$1'$4`'ifelse(`$1', `$2', `', + => `$0(incr(`$1'), `$2', `$3', `$4')')') + =>divert`'dnl + forloop(`i', `1', `3', ` i') + => 1 2 3 + define(`echo', `$@') + => + forloop_arg(`1', `3', ` echo') + => 1 2 3 + include(`curry.m4') + => + forloop_arg(`1', `3', `curry(`pushdef', `a')') + => + a + =>3 + popdef(`a')a + =>2 + popdef(`a')a + =>1 + popdef(`a')a + =>a + + Of course, it is possible to make even more improvements, such as +adding an optional step argument, or allowing iteration through +descending sequences. GNU Autoconf provides some of these additional +bells and whistles in its 'm4_for' macro. + + +File: m4.info, Node: Improved foreach, Next: Improved copy, Prev: Improved forloop, Up: Answers + +17.3 Solution for 'foreach' +=========================== + +The 'foreach' and 'foreachq' macros (*note Foreach::) as presented +earlier each have flaws. First, we will examine and fix the quadratic +behavior of 'foreachq': + + $ m4 -I examples + include(`foreachq.m4') + => + traceon(`shift')debugmode(`aq') + => + foreachq(`x', ``1', `2', `3', `4'', `x + ')dnl + =>1 + error->m4trace: -3- shift(`1', `2', `3', `4') + error->m4trace: -2- shift(`1', `2', `3', `4') + =>2 + error->m4trace: -4- shift(`1', `2', `3', `4') + error->m4trace: -3- shift(`2', `3', `4') + error->m4trace: -3- shift(`1', `2', `3', `4') + error->m4trace: -2- shift(`2', `3', `4') + =>3 + error->m4trace: -5- shift(`1', `2', `3', `4') + error->m4trace: -4- shift(`2', `3', `4') + error->m4trace: -3- shift(`3', `4') + error->m4trace: -4- shift(`1', `2', `3', `4') + error->m4trace: -3- shift(`2', `3', `4') + error->m4trace: -2- shift(`3', `4') + =>4 + error->m4trace: -6- shift(`1', `2', `3', `4') + error->m4trace: -5- shift(`2', `3', `4') + error->m4trace: -4- shift(`3', `4') + error->m4trace: -3- shift(`4') + + Each successive iteration was adding more quoted 'shift' invocations, +and the entire list contents were passing through every iteration. In +general, when recursing, it is a good idea to make the recursion use +fewer arguments, rather than adding additional quoted uses of 'shift'. +By doing so, 'm4' uses less memory, invokes fewer macros, is less likely +to run into machine limits, and most importantly, performs faster. The +fixed version of 'foreachq' can be found in +'m4-1.4.17/examples/foreachq2.m4': + + $ m4 -I examples + include(`foreachq2.m4') + => + undivert(`foreachq2.m4')dnl + =>include(`quote.m4')dnl + =>divert(`-1') + =># foreachq(x, `item_1, item_2, ..., item_n', stmt) + =># quoted list, improved version + =>define(`foreachq', `pushdef(`$1')_$0($@)popdef(`$1')') + =>define(`_arg1q', ``$1'') + =>define(`_rest', `ifelse(`$#', `1', `', `dquote(shift($@))')') + =>define(`_foreachq', `ifelse(`$2', `', `', + => `define(`$1', _arg1q($2))$3`'$0(`$1', _rest($2), `$3')')') + =>divert`'dnl + traceon(`shift')debugmode(`aq') + => + foreachq(`x', ``1', `2', `3', `4'', `x + ')dnl + =>1 + error->m4trace: -3- shift(`1', `2', `3', `4') + =>2 + error->m4trace: -3- shift(`2', `3', `4') + =>3 + error->m4trace: -3- shift(`3', `4') + =>4 + + Note that the fixed version calls unquoted helper macros in +'_foreachq' to trim elements immediately; those helper macros in turn +must re-supply the layer of quotes lost in the macro invocation. +Contrast the use of '_arg1q', which quotes the first list element, with +'_arg1' of the earlier implementation that returned the first list +element directly. Additionally, by calling the helper method +immediately, the 'defn(`ITERATOR')' no longer contains unexpanded +macros. + + The astute m4 programmer might notice that the solution above still +uses more memory and macro invocations, and thus more time, than +strictly necessary. Note that '$2', which contains an arbitrarily long +quoted list, is expanded and rescanned three times per iteration of +'_foreachq'. Furthermore, every iteration of the algorithm effectively +unboxes then reboxes the list, which costs a couple of macro +invocations. It is possible to rewrite the algorithm for a bit more +speed by swapping the order of the arguments to '_foreachq' in order to +operate on an unboxed list in the first place, and by using the +fixed-length '$#' instead of an arbitrary length list as the key to end +recursion. The result is an overhead of six macro invocations per loop +(excluding any macros in TEXT), instead of eight. This alternative +approach is available as 'm4-1.4.17/examples/foreach3.m4': + + $ m4 -I examples + include(`foreachq3.m4') + => + undivert(`foreachq3.m4')dnl + =>divert(`-1') + =># foreachq(x, `item_1, item_2, ..., item_n', stmt) + =># quoted list, alternate improved version + =>define(`foreachq', `ifelse(`$2', `', `', + => `pushdef(`$1')_$0(`$1', `$3', `', $2)popdef(`$1')')') + =>define(`_foreachq', `ifelse(`$#', `3', `', + => `define(`$1', `$4')$2`'$0(`$1', `$2', + => shift(shift(shift($@))))')') + =>divert`'dnl + traceon(`shift')debugmode(`aq') + => + foreachq(`x', ``1', `2', `3', `4'', `x + ')dnl + =>1 + error->m4trace: -4- shift(`x', `x + error->', `', `1', `2', `3', `4') + error->m4trace: -3- shift(`x + error->', `', `1', `2', `3', `4') + error->m4trace: -2- shift(`', `1', `2', `3', `4') + =>2 + error->m4trace: -4- shift(`x', `x + error->', `1', `2', `3', `4') + error->m4trace: -3- shift(`x + error->', `1', `2', `3', `4') + error->m4trace: -2- shift(`1', `2', `3', `4') + =>3 + error->m4trace: -4- shift(`x', `x + error->', `2', `3', `4') + error->m4trace: -3- shift(`x + error->', `2', `3', `4') + error->m4trace: -2- shift(`2', `3', `4') + =>4 + error->m4trace: -4- shift(`x', `x + error->', `3', `4') + error->m4trace: -3- shift(`x + error->', `3', `4') + error->m4trace: -2- shift(`3', `4') + + In the current version of M4, every instance of '$@' is rescanned as +it is encountered. Thus, the 'foreachq3.m4' alternative uses much less +memory than 'foreachq2.m4', and executes as much as 10% faster, since +each iteration encounters fewer '$@'. However, the implementation of +rescanning every byte in '$@' is quadratic in the number of bytes +scanned (for example, making the broken version in 'foreachq.m4' cubic, +rather than quadratic, in behavior). A future release of M4 will +improve the underlying implementation by reusing results of previous +scans, so that both styles of 'foreachq' can become linear in the number +of bytes scanned. Notice how the implementation injects an empty +argument prior to expanding '$2' within 'foreachq'; the helper macro +'_foreachq' then ignores the third argument altogether, and ends +recursion when there are three arguments left because there was nothing +left to pass through 'shift'. Thus, each iteration only needs one +'ifelse', rather than the two conditionals used in the version from +'foreachq2.m4'. + + So far, all of the implementations of 'foreachq' presented have been +quadratic with M4 1.4.x. But 'forloop' is linear, because each +iteration parses a constant amount of arguments. So, it is possible to +design a variant that uses 'forloop' to do the iteration, then uses '$@' +only once at the end, giving a linear result even with older M4 +implementations. This implementation relies on the GNU extension that +'$10' expands to the tenth argument rather than the first argument +concatenated with '0'. The trick is to define an intermediate macro +that repeats the text 'm4_define(`$1', `$N')$2`'', with 'n' set to +successive integers corresponding to each argument. The helper macro +'_foreachq_' is needed in order to generate the literal sequences such +as '$1' into the intermediate macro, rather than expanding them as the +arguments of '_foreachq'. With this approach, no 'shift' calls are even +needed! Even though there are seven macros of overhead per iteration +instead of six in 'foreachq3.m4', the linear scaling is apparent at +relatively small list sizes. However, this approach will need +adjustment when a future version of M4 follows POSIX by no longer +treating '$10' as the tenth argument; the anticipation is that '${10}' +can be used instead, although that alternative syntax is not yet +supported. + + $ m4 -I examples + include(`foreachq4.m4') + => + undivert(`foreachq4.m4')dnl + =>include(`forloop2.m4')dnl + =>divert(`-1') + =># foreachq(x, `item_1, item_2, ..., item_n', stmt) + =># quoted list, version based on forloop + =>define(`foreachq', + =>`ifelse(`$2', `', `', `_$0(`$1', `$3', $2)')') + =>define(`_foreachq', + =>`pushdef(`$1', forloop(`$1', `3', `$#', + => `$0_(`1', `2', indir(`$1'))')`popdef( + => `$1')')indir(`$1', $@)') + =>define(`_foreachq_', + =>``define(`$$1', `$$3')$$2`''') + =>divert`'dnl + traceon(`shift')debugmode(`aq') + => + foreachq(`x', ``1', `2', `3', `4'', `x + ')dnl + =>1 + =>2 + =>3 + =>4 + + For yet another approach, the improved version of 'foreach', +available in 'm4-1.4.17/examples/foreach2.m4', simply overquotes the +arguments to '_foreach' to begin with, using 'dquote_elt'. Then +'_foreach' can just use '_arg1' to remove the extra layer of quoting +that was added up front: + + $ m4 -I examples + include(`foreach2.m4') + => + undivert(`foreach2.m4')dnl + =>include(`quote.m4')dnl + =>divert(`-1') + =># foreach(x, (item_1, item_2, ..., item_n), stmt) + =># parenthesized list, improved version + =>define(`foreach', `pushdef(`$1')_$0(`$1', + => (dquote(dquote_elt$2)), `$3')popdef(`$1')') + =>define(`_arg1', `$1') + =>define(`_foreach', `ifelse(`$2', `(`')', `', + => `define(`$1', _arg1$2)$3`'$0(`$1', (dquote(shift$2)), `$3')')') + =>divert`'dnl + traceon(`shift')debugmode(`aq') + => + foreach(`x', `(`1', `2', `3', `4')', `x + ')dnl + error->m4trace: -4- shift(`1', `2', `3', `4') + error->m4trace: -4- shift(`2', `3', `4') + error->m4trace: -4- shift(`3', `4') + =>1 + error->m4trace: -3- shift(``1'', ``2'', ``3'', ``4'') + =>2 + error->m4trace: -3- shift(``2'', ``3'', ``4'') + =>3 + error->m4trace: -3- shift(``3'', ``4'') + =>4 + error->m4trace: -3- shift(``4'') + + It is likewise possible to write a variant of 'foreach' that performs +in linear time on M4 1.4.x; the easiest method is probably writing a +version of 'foreach' that unboxes its list, then invokes '_foreachq' as +previously defined in 'foreachq4.m4'. + + In summary, recursion over list elements is trickier than it appeared +at first glance, but provides a powerful idiom within 'm4' processing. +As a final demonstration, both list styles are now able to handle +several scenarios that would wreak havoc on one or both of the original +implementations. This points out one other difference between the list +styles. 'foreach' evaluates unquoted list elements only once, in +preparation for calling '_foreach', similary for 'foreachq' as provided +by 'foreachq3.m4' or 'foreachq4.m4'. But 'foreachq', as provided by +'foreachq2.m4', evaluates unquoted list elements twice while visiting +the first list element, once in '_arg1q' and once in '_rest'. When +deciding which list style to use, one must take into account whether +repeating the side effects of unquoted list elements will have any +detrimental effects. + + $ m4 -I examples + include(`foreach2.m4') + => + include(`foreachq2.m4') + => + dnl 0-element list: + foreach(`x', `', `<x>') / foreachq(`x', `', `<x>') + => / + dnl 1-element list of empty element + foreach(`x', `()', `<x>') / foreachq(`x', ``'', `<x>') + =><> / <> + dnl 2-element list of empty elements + foreach(`x', `(`',`')', `<x>') / foreachq(`x', ``',`'', `<x>') + =><><> / <><> + dnl 1-element list of a comma + foreach(`x', `(`,')', `<x>') / foreachq(`x', ``,'', `<x>') + =><,> / <,> + dnl 2-element list of unbalanced parentheses + foreach(`x', `(`(', `)')', `<x>') / foreachq(`x', ``(', `)'', `<x>') + =><(><)> / <(><)> + define(`ab', `oops')dnl using defn(`iterator') + foreach(`x', `(`a', `b')', `defn(`x')') /dnl + foreachq(`x', ``a', `b'', `defn(`x')') + =>ab / ab + define(`active', `ACT, IVE') + => + traceon(`active') + => + dnl list of unquoted macros; expansion occurs before recursion + foreach(`x', `(active, active)', `<x> + ')dnl + error->m4trace: -4- active -> `ACT, IVE' + error->m4trace: -4- active -> `ACT, IVE' + =><ACT> + =><IVE> + =><ACT> + =><IVE> + foreachq(`x', `active, active', `<x> + ')dnl + error->m4trace: -3- active -> `ACT, IVE' + error->m4trace: -3- active -> `ACT, IVE' + =><ACT> + error->m4trace: -3- active -> `ACT, IVE' + error->m4trace: -3- active -> `ACT, IVE' + =><IVE> + =><ACT> + =><IVE> + dnl list of quoted macros; expansion occurs during recursion + foreach(`x', `(`active', `active')', `<x> + ')dnl + error->m4trace: -1- active -> `ACT, IVE' + =><ACT, IVE> + error->m4trace: -1- active -> `ACT, IVE' + =><ACT, IVE> + foreachq(`x', ``active', `active'', `<x> + ')dnl + error->m4trace: -1- active -> `ACT, IVE' + =><ACT, IVE> + error->m4trace: -1- active -> `ACT, IVE' + =><ACT, IVE> + dnl list of double-quoted macro names; no expansion + foreach(`x', `(``active'', ``active'')', `<x> + ')dnl + =><active> + =><active> + foreachq(`x', ```active'', ``active''', `<x> + ')dnl + =><active> + =><active> + + +File: m4.info, Node: Improved copy, Next: Improved m4wrap, Prev: Improved foreach, Up: Answers + +17.4 Solution for 'copy' +======================== + +The macro 'copy' presented above is unable to handle builtin tokens with +M4 1.4.x, because it tries to pass the builtin token through the macro +'curry', where it is silently flattened to an empty string (*note +Composition::). Rather than using the problematic 'curry' to work +around the limitation that 'stack_foreach' expects to invoke a macro +that takes exactly one argument, we can write a new macro that lets us +form the exact two-argument 'pushdef' call sequence needed, so that we +are no longer passing a builtin token through a text macro. + + -- Composite: stack_foreach_sep (MACRO, PRE, POST, SEP) + -- Composite: stack_foreach_sep_lifo (MACRO, PRE, POST, SEP) + For each of the 'pushdef' definitions associated with MACRO, expand + the sequence 'PRE`'definition`'POST'. Additionally, expand SEP + between definitions. 'stack_foreach_sep' visits the oldest + definition first, while 'stack_foreach_sep_lifo' visits the current + definition first. The expansion may dereference MACRO, but should + not modify it. There are a few special macros, such as 'defn', + which cannot be used as the MACRO parameter. + + Note that 'stack_foreach(`MACRO', `ACTION')' is equivalent to +'stack_foreach_sep(`MACRO', `ACTION(', `)')'. By supplying explicit +parentheses, split among the PRE and POST arguments to +'stack_foreach_sep', it is now possible to construct macro calls with +more than one argument, without passing builtin tokens through a macro +call. It is likewise possible to directly reference the stack +definitions without a macro call, by leaving PRE and POST empty. Thus, +in addition to fixing 'copy' on builtin tokens, it also executes with +fewer macro invocations. + + The new macro also adds a separator that is only output after the +first iteration of the helper '_stack_reverse_sep', implemented by +prepending the original SEP to PRE and omitting a SEP argument in +subsequent iterations. Note that the empty string that separates SEP +from PRE is provided as part of the fourth argument when originally +calling '_stack_reverse_sep', and not by writing '$4`'$3' as the third +argument in the recursive call; while the other approach would give the +same output, it does so at the expense of increasing the argument size +on each iteration of '_stack_reverse_sep', which results in quadratic +instead of linear execution time. The improved stack walking macros are +available in 'm4-1.4.17/examples/stack_sep.m4': + + $ m4 -I examples + include(`stack_sep.m4') + => + define(`copy', `ifdef(`$2', `errprint(`$2 already defined + ')m4exit(`1')', + `stack_foreach_sep(`$1', `pushdef(`$2',', `)')')')dnl + pushdef(`a', `1')pushdef(`a', defn(`divnum')) + => + copy(`a', `b') + => + b + =>0 + popdef(`b') + => + b + =>1 + pushdef(`c', `1')pushdef(`c', `2') + => + stack_foreach_sep_lifo(`c', `', `', `, ') + =>2, 1 + undivert(`stack_sep.m4')dnl + =>divert(`-1') + =># stack_foreach_sep(macro, pre, post, sep) + =># Invoke PRE`'defn`'POST with a single argument of each definition + =># from the definition stack of MACRO, starting with the oldest, and + =># separated by SEP between definitions. + =>define(`stack_foreach_sep', + =>`_stack_reverse_sep(`$1', `tmp-$1')'dnl + =>`_stack_reverse_sep(`tmp-$1', `$1', `$2`'defn(`$1')$3', `$4`'')') + =># stack_foreach_sep_lifo(macro, pre, post, sep) + =># Like stack_foreach_sep, but starting with the newest definition. + =>define(`stack_foreach_sep_lifo', + =>`_stack_reverse_sep(`$1', `tmp-$1', `$2`'defn(`$1')$3', `$4`'')'dnl + =>`_stack_reverse_sep(`tmp-$1', `$1')') + =>define(`_stack_reverse_sep', + =>`ifdef(`$1', `pushdef(`$2', defn(`$1'))$3`'popdef(`$1')$0( + => `$1', `$2', `$4$3')')') + =>divert`'dnl + + +File: m4.info, Node: Improved m4wrap, Next: Improved cleardivert, Prev: Improved copy, Up: Answers + +17.5 Solution for 'm4wrap' +========================== + +The replacement 'm4wrap' versions presented above, designed to guarantee +FIFO or LIFO order regardless of the underlying M4 implementation, share +a bug when dealing with wrapped text that looks like parameter +expansion. Note how the invocation of 'm4wrapN' interprets these +parameters, while using the builtin preserves them for their intended +use. + + $ m4 -I examples + include(`wraplifo.m4') + => + m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b') + ') + => + builtin(`m4wrap', ``'define(`bar', ``$0:'-$1-$*-$#-')bar(`a', `b') + ') + => + ^D + =>bar:-a-a,b-2- + =>m4wrap0:---0- + + Additionally, the computation of '_m4wrap_level' and creation of +multiple 'm4wrapN' placeholders in the original examples is more +expensive in time and memory than strictly necessary. Notice how the +improved version grabs the wrapped text via 'defn' to avoid parameter +expansion, then undefines '_m4wrap_text', before stripping a level of +quotes with '_arg1' to expand the text. That way, each level of +wrapping reuses the single placeholder, which starts each nesting level +in an undefined state. + + Finally, it is worth emulating the GNU M4 extension of saving all +arguments to 'm4wrap', separated by a space, rather than saving just the +first argument. This is done with the 'join' macro documented +previously (*note Shift::). The improved LIFO example is shipped as +'m4-1.4.17/examples/wraplifo2.m4', and can easily be converted to a FIFO +solution by swapping the adjacent invocations of 'joinall' and 'defn'. + + $ m4 -I examples + include(`wraplifo2.m4') + => + undivert(`wraplifo2.m4')dnl + =>dnl Redefine m4wrap to have LIFO semantics, improved example. + =>include(`join.m4')dnl + =>define(`_m4wrap', defn(`m4wrap'))dnl + =>define(`_arg1', `$1')dnl + =>define(`m4wrap', + =>`ifdef(`_$0_text', + => `define(`_$0_text', joinall(` ', $@)defn(`_$0_text'))', + => `_$0(`_arg1(defn(`_$0_text')undefine(`_$0_text'))')dnl + =>define(`_$0_text', joinall(` ', $@))')')dnl + m4wrap(`define(`foo', ``$0:'-$1-$*-$#-')foo(`a', `b') + ') + => + m4wrap(`lifo text + m4wrap(`nested', `', `$@ + ')') + => + ^D + =>lifo text + =>foo:-a-a,b-2- + =>nested $@ + + +File: m4.info, Node: Improved cleardivert, Next: Improved capitalize, Prev: Improved m4wrap, Up: Answers + +17.6 Solution for 'cleardivert' +=============================== + +The 'cleardivert' macro (*note Cleardivert::) cannot, as it stands, be +called without arguments to clear all pending diversions. That is +because using undivert with an empty string for an argument is different +than using it with no arguments at all. Compare the earlier definition +with one that takes the number of arguments into account: + + define(`cleardivert', + `pushdef(`_n', divnum)divert(`-1')undivert($@)divert(_n)popdef(`_n')') + => + divert(`1')one + divert + => + cleardivert + => + undivert + =>one + => + define(`cleardivert', + `pushdef(`_num', divnum)divert(`-1')ifelse(`$#', `0', + `undivert`'', `undivert($@)')divert(_num)popdef(`_num')') + => + divert(`2')two + divert + => + cleardivert + => + undivert + => + + +File: m4.info, Node: Improved capitalize, Next: Improved fatal_error, Prev: Improved cleardivert, Up: Answers + +17.7 Solution for 'capitalize' +============================== + +The 'capitalize' macro (*note Patsubst::) as presented earlier does not +allow clients to follow the quoting rule of thumb. Consider the three +macros 'active', 'Active', and 'ACTIVE', and the difference between +calling 'capitalize' with the expansion of a macro, expanding the result +of a case change, and changing the case of a double-quoted string: + + $ m4 -I examples + include(`capitalize.m4')dnl + define(`active', `act1, ive')dnl + define(`Active', `Act2, Ive')dnl + define(`ACTIVE', `ACT3, IVE')dnl + upcase(active) + =>ACT1,IVE + upcase(`active') + =>ACT3, IVE + upcase(``active'') + =>ACTIVE + downcase(ACTIVE) + =>act3,ive + downcase(`ACTIVE') + =>act1, ive + downcase(``ACTIVE'') + =>active + capitalize(active) + =>Act1 + capitalize(`active') + =>Active + capitalize(``active'') + =>_capitalize(`active') + define(`A', `OOPS') + => + capitalize(active) + =>OOPSct1 + capitalize(`active') + =>OOPSctive + + First, when 'capitalize' is called with more than one argument, it +was throwing away later arguments, whereas 'upcase' and 'downcase' used +'$*' to collect them all. The fix is simple: use '$*' consistently. + + Next, with single-quoting, 'capitalize' outputs a single character, a +set of quotes, then the rest of the characters, making it impossible to +invoke 'Active' after the fact, and allowing the alternate macro 'A' to +interfere. Here, the solution is to use additional quoting in the +helper macros, then pass the final over-quoted output string through +'_arg1' to remove the extra quoting and finally invoke the concatenated +portions as a single string. + + Finally, when passed a double-quoted string, the nested macro +'_capitalize' is never invoked because it ended up nested inside quotes. +This one is the toughest to fix. In short, we have no idea how many +levels of quotes are in effect on the substring being altered by +'patsubst'. If the replacement string cannot be expressed entirely in +terms of literal text and backslash substitutions, then we need a +mechanism to guarantee that the helper macros are invoked outside of +quotes. In other words, this sounds like a job for 'changequote' (*note +Changequote::). By changing the active quoting characters, we can +guarantee that replacement text injected by 'patsubst' always occurs in +the middle of a string that has exactly one level of over-quoting using +alternate quotes; so the replacement text closes the quoted string, +invokes the helper macros, then reopens the quoted string. In turn, +that means the replacement text has unbalanced quotes, necessitating +another round of 'changequote'. + + In the fixed version below, (also shipped as +'m4-1.4.17/examples/capitalize2.m4'), 'capitalize' uses the alternate +quotes of '<<[' and ']>>' (the longer strings are chosen so as to be +less likely to appear in the text being converted). The helpers +'_to_alt' and '_from_alt' merely reduce the number of characters +required to perform a 'changequote', since the definition changes twice. +The outermost pair means that 'patsubst' and '_capitalize_alt' are +invoked with alternate quoting; the innermost pair is used so that the +third argument to 'patsubst' can contain an unbalanced ']>>'/'<<[' pair. +Note that 'upcase' and 'downcase' must be redefined as '_upcase_alt' and +'_downcase_alt', since they contain nested quotes but are invoked with +the alternate quoting scheme in effect. + + $ m4 -I examples + include(`capitalize2.m4')dnl + define(`active', `act1, ive')dnl + define(`Active', `Act2, Ive')dnl + define(`ACTIVE', `ACT3, IVE')dnl + define(`A', `OOPS')dnl + capitalize(active; `active'; ``active''; ```actIVE''') + =>Act1,Ive; Act2, Ive; Active; `Active' + undivert(`capitalize2.m4')dnl + =>divert(`-1') + =># upcase(text) + =># downcase(text) + =># capitalize(text) + =># change case of text, improved version + =>define(`upcase', `translit(`$*', `a-z', `A-Z')') + =>define(`downcase', `translit(`$*', `A-Z', `a-z')') + =>define(`_arg1', `$1') + =>define(`_to_alt', `changequote(`<<[', `]>>')') + =>define(`_from_alt', `changequote(<<[`]>>, <<[']>>)') + =>define(`_upcase_alt', `translit(<<[$*]>>, <<[a-z]>>, <<[A-Z]>>)') + =>define(`_downcase_alt', `translit(<<[$*]>>, <<[A-Z]>>, <<[a-z]>>)') + =>define(`_capitalize_alt', + => `regexp(<<[$1]>>, <<[^\(\w\)\(\w*\)]>>, + => <<[_upcase_alt(<<[<<[\1]>>]>>)_downcase_alt(<<[<<[\2]>>]>>)]>>)') + =>define(`capitalize', + => `_arg1(_to_alt()patsubst(<<[<<[$*]>>]>>, <<[\w+]>>, + => _from_alt()`]>>_$0_alt(<<[\&]>>)<<['_to_alt())_from_alt())') + =>divert`'dnl + + +File: m4.info, Node: Improved fatal_error, Prev: Improved capitalize, Up: Answers + +17.8 Solution for 'fatal_error' +=============================== + +The 'fatal_error' macro (*note M4exit::) is not robust to versions of +GNU M4 earlier than 1.4.8, where invoking '__file__' (*note Location::) +inside 'm4wrap' would result in an empty string, and '__line__' resulted +in '0' even though all files start at line 1. Furthermore, versions +earlier than 1.4.6 did not support the '__program__' macro. If you want +'fatal_error' to work across the entire 1.4.x release series, a better +implementation would be: + + define(`fatal_error', + `errprint(ifdef(`__program__', `__program__', ``m4'')'dnl + `:ifelse(__line__, `0', `', + `__file__:__line__:')` fatal error: $* + ')m4exit(`1')') + => + m4wrap(`divnum(`demo of internal message') + fatal_error(`inside wrapped text')') + => + ^D + error->m4:stdin:6: Warning: excess arguments to builtin `divnum' ignored + =>0 + error->m4:stdin:6: fatal error: inside wrapped text + + +File: m4.info, Node: Copying This Package, Next: Copying This Manual, Prev: Answers, Up: Top + +Appendix A How to make copies of the overall M4 package +******************************************************* + +This appendix covers the license for copying the source code of the +overall M4 package. This manual is under a different set of +restrictions, covered later (*note Copying This Manual::). + +* Menu: + +* GNU General Public License:: License for copying the M4 package + + +File: m4.info, Node: GNU General Public License, Up: Copying This Package + +A.1 License for copying the M4 package +====================================== + + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + +Preamble +======== + +The GNU General Public License is a free, copyleft license for software +and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + +TERMS AND CONDITIONS +==================== + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public + License. + + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this + License. Each licensee is addressed as "you". "Licensees" and + "recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the + work in a fashion requiring copyright permission, other than the + making of an exact copy. The resulting work is called a "modified + version" of the earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work + based on the Program. + + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it on + a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities as + well. + + To "convey" a work means any kind of propagation that enables other + parties to make or receive copies. Mere interaction with a user + through a computer network, with no transfer of a copy, is not + conveying. + + An interactive user interface displays "Appropriate Legal Notices" + to the extent that it includes a convenient and prominently visible + feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to + the extent that warranties are provided), that licensees may convey + the work under this License, and how to view a copy of this + License. If the interface presents a list of user commands or + options, such as a menu, a prominent item in the list meets this + criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work + for making modifications to it. "Object code" means any non-source + form of a work. + + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in that + language. + + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the normal + form of packaging a Major Component, but which is not part of that + Major Component, and (b) serves only to enable use of the work with + that Major Component, or to implement a Standard Interface for + which an implementation is available to the public in source code + form. A "Major Component", in this context, means a major + essential component (kernel, window system, and so on) of the + specific operating system (if any) on which the executable work + runs, or a compiler used to produce the work, or an object code + interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all + the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including scripts + to control those activities. However, it does not include the + work's System Libraries, or general-purpose tools or generally + available free programs which are used unmodified in performing + those activities but which are not part of the work. For example, + Corresponding Source includes interface definition files associated + with source files for the work, and the source code for shared + libraries and dynamically linked subprograms that the work is + specifically designed to require, such as by intimate data + communication or control flow between those subprograms and other + parts of the work. + + The Corresponding Source need not include anything that users can + regenerate automatically from other parts of the Corresponding + Source. + + The Corresponding Source for a work in source code form is that + same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of + copyright on the Program, and are irrevocable provided the stated + conditions are met. This License explicitly affirms your unlimited + permission to run the unmodified Program. The output from running + a covered work is covered by this License only if the output, given + its content, constitutes a covered work. This License acknowledges + your rights of fair use or other equivalent, as provided by + copyright law. + + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for the + sole purpose of having them make modifications exclusively for you, + or provide you with facilities for running those works, provided + that you comply with the terms of this License in conveying all + material for which you do not control copyright. Those thus making + or running the covered works for you must do so exclusively on your + behalf, under your direction and control, on terms that prohibit + them from making any copies of your copyrighted material outside + their relationship with you. + + Conveying under any other circumstances is permitted solely under + the conditions stated below. Sublicensing is not allowed; section + 10 makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological + measure under any applicable law fulfilling obligations under + article 11 of the WIPO copyright treaty adopted on 20 December + 1996, or similar laws prohibiting or restricting circumvention of + such measures. + + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such + circumvention is effected by exercising rights under this License + with respect to the covered work, and you disclaim any intention to + limit operation or modification of the work as a means of + enforcing, against the work's users, your or third parties' legal + rights to forbid circumvention of technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you + receive it, in any medium, provided that you conspicuously and + appropriately publish on each copy an appropriate copyright notice; + keep intact all notices stating that this License and any + non-permissive terms added in accord with section 7 apply to the + code; keep intact all notices of the absence of any warranty; and + give all recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, + and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to + produce it from the Program, in the form of source code under the + terms of section 4, provided that you also meet all of these + conditions: + + a. The work must carry prominent notices stating that you + modified it, and giving a relevant date. + + b. The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in + section 4 to "keep intact all notices". + + c. You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable + section 7 additional terms, to the whole of the work, and all + its parts, regardless of how they are packaged. This License + gives no permission to license the work in any other way, but + it does not invalidate such permission if you have separately + received it. + + d. If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + + A compilation of a covered work with other separate and independent + works, which are not by their nature extensions of the covered + work, and which are not combined with it such as to form a larger + program, in or on a volume of a storage or distribution medium, is + called an "aggregate" if the compilation and its resulting + copyright are not used to limit the access or legal rights of the + compilation's users beyond what the individual works permit. + Inclusion of a covered work in an aggregate does not cause this + License to apply to the other parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms + of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + + a. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access + to copy the Corresponding Source from a network server at no + charge. + + c. Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, + in accord with subsection 6b. + + d. Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to + the Corresponding Source in the same way through the same + place at no further charge. You need not require recipients + to copy the Corresponding Source along with the object code. + If the place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated by + you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to the + object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long as + needed to satisfy these requirements. + + e. Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for personal, + family, or household purposes, or (2) anything designed or sold for + incorporation into a dwelling. In determining whether a product is + a consumer product, doubtful cases shall be resolved in favor of + coverage. For a particular product received by a particular user, + "normally used" refers to a typical or common use of that class of + product, regardless of the status of the particular user or of the + way in which the particular user actually uses, or expects or is + expected to use, the product. A product is a consumer product + regardless of whether the product has substantial commercial, + industrial or non-consumer uses, unless such uses represent the + only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding Source. + The information must suffice to ensure that the continued + functioning of the modified object code is in no case prevented or + interfered with solely because modification has been made. + + If you convey an object code work under this section in, or with, + or specifically for use in, a User Product, and the conveying + occurs as part of a transaction in which the right of possession + and use of the User Product is transferred to the recipient in + perpetuity or for a fixed term (regardless of how the transaction + is characterized), the Corresponding Source conveyed under this + section must be accompanied by the Installation Information. But + this requirement does not apply if neither you nor any third party + retains the ability to install modified object code on the User + Product (for example, the work has been installed in ROM). + + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or installed + by the recipient, or for the User Product in which it has been + modified or installed. Access to a network may be denied when the + modification itself materially and adversely affects the operation + of the network or violates the rules and protocols for + communication across the network. + + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that is + publicly documented (and with an implementation available to the + public in source code form), and must require no special password + or key for unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the Program, + that part may be used separately under those permissions, but the + entire Program remains governed by this License without regard to + the additional permissions. + + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any part + of it. (Additional permissions may be written to require their own + removal in certain cases when you modify the work.) You may place + additional permissions on material, added by you to a covered work, + for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material + you add to a covered work, you may (if authorized by the copyright + holders of that material) supplement the terms of this License with + terms: + + a. Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + + b. Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + + c. Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be marked + in reasonable ways as different from the original version; or + + d. Limiting the use for publicity purposes of names of licensors + or authors of the material; or + + e. Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f. Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to + the recipient, for any liability that these contractual + assumptions directly impose on those licensors and authors. + + All other non-permissive additional terms are considered "further + restrictions" within the meaning of section 10. If the Program as + you received it, or any part of it, contains a notice stating that + it is governed by this License along with a term that is a further + restriction, you may remove that term. If a license document + contains a further restriction but permits relicensing or conveying + under this License, you may add to a covered work material governed + by the terms of that license document, provided that the further + restriction does not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you + must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice indicating + where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as exceptions; + the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly + provided under this License. Any attempt otherwise to propagate or + modify it is void, and will automatically terminate your rights + under this License (including any patent licenses granted under the + third paragraph of section 11). + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, you do not qualify to receive new licenses + for the same material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or + run a copy of the Program. Ancillary propagation of a covered work + occurring solely as a consequence of using peer-to-peer + transmission to receive a copy likewise does not require + acceptance. However, nothing other than this License grants you + permission to propagate or modify any covered work. These actions + infringe copyright if you do not accept this License. Therefore, + by modifying or propagating a covered work, you indicate your + acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify and + propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + + An "entity transaction" is a transaction transferring control of an + organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a + covered work results from an entity transaction, each party to that + transaction who receives a copy of the work also receives whatever + licenses to the work the party's predecessor in interest had or + could give under the previous paragraph, plus a right to possession + of the Corresponding Source of the work from the predecessor in + interest, if the predecessor has it or can get it with reasonable + efforts. + + You may not impose any further restrictions on the exercise of the + rights granted or affirmed under this License. For example, you + may not impose a license fee, royalty, or other charge for exercise + of rights granted under this License, and you may not initiate + litigation (including a cross-claim or counterclaim in a lawsuit) + alleging that any patent claim is infringed by making, using, + selling, offering for sale, or importing the Program or any portion + of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this + License of the Program or a work on which the Program is based. + The work thus licensed is called the contributor's "contributor + version". + + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its contributor + version. + + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To "grant" + such a patent license to a party means to make such an agreement or + commitment not to enforce a patent against the party. + + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not available + for anyone to copy, free of charge and under the terms of this + License, through a publicly available network server or other + readily accessible means, then you must either (1) cause the + Corresponding Source to be so available, or (2) arrange to deprive + yourself of the benefit of the patent license for this particular + work, or (3) arrange, in a manner consistent with the requirements + of this License, to extend the patent license to downstream + recipients. "Knowingly relying" means you have actual knowledge + that, but for the patent license, your conveying the covered work + in a country, or your recipient's use of the covered work in a + country, would infringe one or more identifiable patents in that + country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance of, a + covered work, and grant a patent license to some of the parties + receiving the covered work authorizing them to use, propagate, + modify or convey a specific copy of the covered work, then the + patent license you grant is automatically extended to all + recipients of the covered work and works based on it. + + A patent license is "discriminatory" if it does not include within + the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that + are specifically granted under this License. You may not convey a + covered work if you are a party to an arrangement with a third + party that is in the business of distributing software, under which + you make payment to the third party based on the extent of your + activity of conveying the work, and under which the third party + grants, to any of the parties who would receive the covered work + from you, a discriminatory patent license (a) in connection with + copies of the covered work conveyed by you (or copies made from + those copies), or (b) primarily for and in connection with specific + products or compilations that contain the covered work, unless you + entered into that arrangement, or that patent license was granted, + prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting + any implied license or other defenses to infringement that may + otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement + or otherwise) that contradict the conditions of this License, they + do not excuse you from the conditions of this License. If you + cannot convey a covered work so as to satisfy simultaneously your + obligations under this License and any other pertinent obligations, + then as a consequence you may not convey it at all. For example, + if you agree to terms that obligate you to collect a royalty for + further conveying from those to whom you convey the Program, the + only way you could satisfy both those terms and this License would + be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work licensed + under version 3 of the GNU Affero General Public License into a + single combined work, and to convey the resulting work. The terms + of this License will continue to apply to the part which is the + covered work, but the special requirements of the GNU Affero + General Public License, section 13, concerning interaction through + a network will apply to the combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new + versions of the GNU General Public License from time to time. Such + new versions will be similar in spirit to the present version, but + may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the Free + Software Foundation. If the Program does not specify a version + number of the GNU General Public License, you may choose any + version ever published by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on any + author or copyright holder as a result of your choosing to follow a + later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE + COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE + RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. + SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES + AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR + DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE + THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA + BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER + PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF + THE POSSIBILITY OF SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided + above cannot be given local legal effect according to their terms, + reviewing courts shall apply local law that most closely + approximates an absolute waiver of all civil liability in + connection with the Program, unless a warranty or assumption of + liability accompanies a copy of the Program in return for a fee. + +END OF TERMS AND CONDITIONS +=========================== + +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or (at + your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see <http://www.gnu.org/licenses/>. + + Also add information on how to contact you by electronic and paper +mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + PROGRAM Copyright (C) YEAR NAME OF AUTHOR + This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type 'show c' for details. + + The hypothetical commands 'show w' and 'show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + + You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see <http://www.gnu.org/licenses/>. + + The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read <http://www.gnu.org/philosophy/why-not-lgpl.html>. + |