GNU M4, version 1.4.7 A powerful macro processor Edition 1.4.7, 23 September 2006 by Ren´eSeindal This manual is for GNU M4 (version 1.4.7, 23 September 2006), a package containing an implementation of the m4 macro language. Copyright c 1989, 1990, 1991, 1992, 1993, 1994, 2004, 2005, 2006 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.2 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.” i Table of Contents 1 Introduction and preliminaries ................ 3 1.1 Introduction to m4 ............................................. 3 1.2 Historical references ............................................ 3 1.3 Invoking m4 .................................................... 4 1.4 Problems and bugs ............................................. 8 1.5 Using this manual .............................................. 8 2 Lexical and syntactic conventions ............ 11 2.1 Macro names ................................................. 11 2.2 Quoting input to m4........................................... 11 2.3 Comments in m4 input ........................................ 11 2.4 Other kinds of input tokens ................................... 12 2.5 How m4 copies input to output ................................ 12 3 How to invoke macros......................... 13 3.1 Macro invocation ............................................. 13 3.2 Preventing macro invocation .................................. 13 3.3 Macro arguments ............................................. 15 3.4 On Quoting Arguments to macros ............................. 15 3.5 Macro expansion .............................................. 16 4 How to define new macros .................... 17 4.1 Defining a macro.............................................. 17 4.2 Arguments to macros ......................................... 18 4.3 Special arguments to macros .................................. 19 4.4 Deleting a macro.............................................. 21 4.5 Renaming macros ............................................. 21 4.6 Temporarily redefining macros ................................ 23 4.7 Indirect call of macros......................................... 24 4.8 Indirect call of builtins ........................................ 25 5 Conditionals, loops, and recursion ........... 27 5.1 Testing if a macro is defined................................... 27 5.2 If-else construct, or multibranch ............................... 27 5.3 Loops and recursion........................................... 29 6 How to debug macros and input ............. 31 6.1 Displaying macro definitions................................... 31 6.2 Tracing macro calls ........................................... 31 6.3 Controlling debugging output ................................. 33 6.4 Saving debugging output ...................................... 34 ii GNU M4 macro processor 7 Input control................................... 37 7.1 Deleting whitespace in input .................................. 37 7.2 Changing the quote characters ................................ 37 7.3 Changing the comment delimiters ............................. 40 7.4 Changing the lexical structure of words........................ 42 7.5 Saving text until end of input ................................. 44 8 File inclusion................................... 47 8.1 Including named files.......................................... 47 8.2 Searching for include files ..................................... 48 9 Diverting and undiverting output............ 49 9.1 Diverting output .............................................. 49 9.2 Undiverting output ........................................... 50 9.3 Diversion numbers ............................................ 52 9.4 Discarding diverted text....................................... 52 10 Macros for text handling .................... 55 10.1 Calculating length of strings ................................. 55 10.2 Searching for substrings ...................................... 55 10.3 Searching for regular expressions ............................. 55 10.4 Extracting substrings ........................................ 56 10.5 Translating characters ....................................... 57 10.6 Substituting text by regular expression ....................... 57 10.7 Formatted output ............................................ 59 11 Macros for doing arithmetic................. 61 11.1 Decrement and increment operators .......................... 61 11.2 Evaluating integer expressions................................ 61 12 Macros for running shell commands ........ 65 12.1 Determining the platform .................................... 65 12.2 Executing simple commands ................................. 66 12.3 Reading the output of commands ............................ 66 12.4 Exit status................................................... 67 12.5 Making temporary files....................................... 68 13 Miscellaneous builtin macros................ 69 13.1 Printing error messages ...................................... 69 13.2 Printing current location ..................................... 69 13.3 Exiting from m4 .............................................. 70 14 Fast loading of frozen state.................. 73 14.1 Using frozen files............................................. 73 14.2 Frozen file format ............................................ 74 iii 15 Compatibility with other versions of m4 .... 77 15.1 Extensions in GNU m4........................................ 77 15.2 Facilities in System V m4 not in GNU m4...................... 78 15.3 Other incompatibilities....................................... 80 16 Correct version of some examples .......... 83 Appendix A How to make copies of this manual ................................................ 85 A.1 GNU Free Documentation License ............................ 85 Appendix B Indices of concepts and macros .. 93 B.1 Index for many concepts ...................................... 93 B.2 Index for all m4 macros ....................................... 94 iv GNU M4 macro processor 1 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´eSeindal, with subsequent changes by Fran¸cois Pinard and other volunteers on the Internet. All names and email addresses can be found in the files ‘AUTHORS’ and ‘THANKS’ from the GNU M4 distribution. This is release 1.4.7. 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 consider- ably 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. 2 GNU M4 macro processor Chapter 1: Introduction and preliminaries 3 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. 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 3 version, except for some minor differences. See Chapter 15 [Compatibility], page 77, 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. 1.2 Historical references GPM was an important ancestor