GNU M4, version 1.4.17

A powerful macro processor

Edition 1.4.17, 22 September 2013

by René Seindal, François Pinard,
Gary V. Vaughan, and Eric Blake
(bug-m4@gnu.org)

This manual (22 September 2013) is for GNU M4 (version 1.4.17), a package containing an implementation of the m4 macro language.

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

This manual (22 September 2013) is for GNU M4 (version 1.4.17), a package containing an implementation of the m4 macro language.

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 René Seindal, with subsequent changes by Franç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.

— The Detailed Node Listing — Introduction and preliminaries
1 Introduction and preliminaries
2 Invoking `m4`
3 Lexical and syntactic conventions
4 How to invoke macros
5 How to define new macros
6 Conditionals, loops, and recursion
7 How to debug macros and input
8 Input control
9 File inclusion
10 Diverting and undiverting output
11 Macros for text handling
12 Macros for doing arithmetic
13 Macros for running shell commands
14 Miscellaneous builtin macros
15 Fast loading of frozen state
16 Compatibility with other versions of `m4`
17 Correct version of some examples
Appendix A How to make copies of the overall M4 package
Appendix B How to make copies of this manual
Appendix C Indices of concepts and macros
1.1 Introduction to `m4`
1.2 Historical references
1.3 Problems and bugs
1.4 Using this manual
Invoking `m4`
2.1 Command line options for operation modes
2.2 Command line options for preprocessor features
2.3 Command line options for limits control
2.4 Command line options for frozen state
2.5 Command line options for debugging
2.6 Specifying input files on the command line
Lexical and syntactic conventions
3.1 Macro names
3.2 Quoting input to `m4`
3.3 Comments in `m4` input
3.4 Other kinds of input tokens
3.5 How `m4` copies input to output
How to invoke macros
4.1 Macro invocation
4.2 Preventing macro invocation
4.3 Macro arguments
4.4 On Quoting Arguments to macros
4.5 Macro expansion		Expanding macros
How to define new macros
5.1 Defining a macro		Defining a new macro
5.2 Arguments to macros
5.3 Special arguments to macros
5.4 Deleting a macro
5.5 Renaming macros
5.6 Temporarily redefining macros
5.7 Indirect call of macros
5.8 Indirect call of builtins
Conditionals, loops, and recursion
6.1 Testing if a macro is defined
6.2 If-else construct, or multibranch
6.3 Recursion in `m4`
6.4 Iteration by counting
6.5 Iteration by list contents
6.6 Working with definition stacks
6.7 Building macros with macros
How to debug macros and input
7.1 Displaying macro definitions
7.2 Tracing macro calls
7.3 Controlling debugging output
7.4 Saving debugging output
Input control
8.1 Deleting whitespace in input
8.2 Changing the quote characters
8.3 Changing the comment delimiters
8.4 Changing the lexical structure of words
8.5 Saving text until end of input
File inclusion
9.1 Including named files
9.2 Searching for include files
Diverting and undiverting output
10.1 Diverting output
10.2 Undiverting output
10.3 Diversion numbers
10.4 Discarding diverted text
Macros for text handling
11.1 Calculating length of strings
11.2 Searching for substrings
11.3 Searching for regular expressions
11.4 Extracting substrings
11.5 Translating characters
11.6 Substituting text by regular expression
11.7 Formatting strings (printf-like)
Macros for doing arithmetic
12.1 Decrement and increment operators
12.2 Evaluating integer expressions
Macros for running shell commands
13.1 Determining the platform
13.2 Executing simple commands
13.3 Reading the output of commands
13.4 Exit status
13.5 Making temporary files
Miscellaneous builtin macros
14.1 Printing error messages
14.2 Printing current location
14.3 Exiting from `m4`
Fast loading of frozen state
15.1 Using frozen files
15.2 Frozen file format
Compatibility with other versions of `m4`
16.1 Extensions in GNU M4
16.2 Facilities in System V `m4` not in GNU `m4`		Facilities in System V m4 not in GNU M4
16.3 Other incompatibilities
Correct version of some examples
17.1 Solution for `exch`
17.2 Solution for `forloop`
17.3 Solution for `foreach`
17.4 Solution for `copy`
17.5 Solution for `m4wrap`
17.6 Solution for `cleardivert`
17.7 Solution for `capitalize`
17.8 Solution for `fatal_error`
How to make copies of the overall M4 package
A.1 License for copying the M4 package
How to make copies of this manual
B.1 License for copying this manual
Indices of concepts and macros
C.1 Index for all `m4` macros
C.2 Index for many concepts

This document was generated on September 29, 2013 using texi2html 5.0.