GNU M4, Version 1.4.19 a Powerful Macro Processor Edition 1.4.19, 28 May 2021
Total Page:16
File Type:pdf, Size:1020Kb
GNU M4, version 1.4.19 A powerful macro processor Edition 1.4.19, 28 May 2021 by Ren´eSeindal, Fran¸coisPinard, Gary V. Vaughan, and Eric Blake ([email protected]) This manual (28 May 2021) is for GNU M4 (version 1.4.19), a package containing an implementation of the m4 macro language. Copyright c 1989{1994, 2004{2014, 2016{2017, 2020{2021 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." i Table of Contents 1 Introduction and preliminaries ::::::::::::::::: 3 1.1 Introduction to m4 :::::::::::::::::::::::::::::::::::::::::::::: 3 1.2 Historical references :::::::::::::::::::::::::::::::::::::::::::: 3 1.3 Problems and bugs ::::::::::::::::::::::::::::::::::::::::::::: 4 1.4 Using this manual :::::::::::::::::::::::::::::::::::::::::::::: 5 2 Invoking m4::::::::::::::::::::::::::::::::::::::: 7 2.1 Command line options for operation modes ::::::::::::::::::::: 7 2.2 Command line options for preprocessor features ::::::::::::::::: 8 2.3 Command line options for limits control ::::::::::::::::::::::: 10 2.4 Command line options for frozen state ::::::::::::::::::::::::: 11 2.5 Command line options for debugging :::::::::::::::::::::::::: 11 2.6 Specifying input files on the command line ::::::::::::::::::::: 12 3 Lexical and syntactic conventions::::::::::::: 15 3.1 Macro names :::::::::::::::::::::::::::::::::::::::::::::::::: 15 3.2 Quoting input to m4 ::::::::::::::::::::::::::::::::::::::::::: 15 3.3 Comments in m4 input ::::::::::::::::::::::::::::::::::::::::: 15 3.4 Other kinds of input tokens:::::::::::::::::::::::::::::::::::: 16 3.5 How m4 copies input to output::::::::::::::::::::::::::::::::: 16 4 How to invoke macros ::::::::::::::::::::::::: 19 4.1 Macro invocation :::::::::::::::::::::::::::::::::::::::::::::: 19 4.2 Preventing macro invocation ::::::::::::::::::::::::::::::::::: 19 4.3 Macro arguments :::::::::::::::::::::::::::::::::::::::::::::: 21 4.4 On Quoting Arguments to macros ::::::::::::::::::::::::::::: 23 4.5 Macro expansion :::::::::::::::::::::::::::::::::::::::::::::: 23 5 How to define new macros :::::::::::::::::::: 25 5.1 Defining a macro :::::::::::::::::::::::::::::::::::::::::::::: 25 5.2 Arguments to macros :::::::::::::::::::::::::::::::::::::::::: 26 5.3 Special arguments to macros::::::::::::::::::::::::::::::::::: 27 5.4 Deleting a macro :::::::::::::::::::::::::::::::::::::::::::::: 30 5.5 Renaming macros ::::::::::::::::::::::::::::::::::::::::::::: 31 5.6 Temporarily redefining macros ::::::::::::::::::::::::::::::::: 33 5.7 Indirect call of macros ::::::::::::::::::::::::::::::::::::::::: 34 5.8 Indirect call of builtins :::::::::::::::::::::::::::::::::::::::: 35 6 Conditionals, loops, and recursion :::::::::::: 39 6.1 Testing if a macro is defined ::::::::::::::::::::::::::::::::::: 39 6.2 If-else construct, or multibranch ::::::::::::::::::::::::::::::: 39 ii GNU M4 1.4.19 macro processor 6.3 Recursion in m4:::::::::::::::::::::::::::::::::::::::::::::::: 41 6.4 Iteration by counting :::::::::::::::::::::::::::::::::::::::::: 46 6.5 Iteration by list contents::::::::::::::::::::::::::::::::::::::: 47 6.6 Working with definition stacks ::::::::::::::::::::::::::::::::: 49 6.7 Building macros with macros :::::::::::::::::::::::::::::::::: 51 7 How to debug macros and input :::::::::::::: 55 7.1 Displaying macro definitions ::::::::::::::::::::::::::::::::::: 55 7.2 Tracing macro calls :::::::::::::::::::::::::::::::::::::::::::: 55 7.3 Controlling debugging output :::::::::::::::::::::::::::::::::: 58 7.4 Saving debugging output :::::::::::::::::::::::::::::::::::::: 60 8 Input control ::::::::::::::::::::::::::::::::::: 61 8.1 Deleting whitespace in input ::::::::::::::::::::::::::::::::::: 61 8.2 Changing the quote characters ::::::::::::::::::::::::::::::::: 62 8.3 Changing the comment delimiters:::::::::::::::::::::::::::::: 65 8.4 Changing the lexical structure of words :::::::::::::::::::::::: 68 8.5 Saving text until end of input:::::::::::::::::::::::::::::::::: 70 9 File inclusion ::::::::::::::::::::::::::::::::::: 73 9.1 Including named files :::::::::::::::::::::::::::::::::::::::::: 73 9.2 Searching for include files :::::::::::::::::::::::::::::::::::::: 74 10 Diverting and undiverting output ::::::::::: 75 10.1 Diverting output ::::::::::::::::::::::::::::::::::::::::::::: 75 10.2 Undiverting output ::::::::::::::::::::::::::::::::::::::::::: 76 10.3 Diversion numbers:::::::::::::::::::::::::::::::::::::::::::: 78 10.4 Discarding diverted text :::::::::::::::::::::::::::::::::::::: 79 11 Macros for text handling ::::::::::::::::::::: 81 11.1 Calculating length of strings :::::::::::::::::::::::::::::::::: 81 11.2 Searching for substrings :::::::::::::::::::::::::::::::::::::: 81 11.3 Searching for regular expressions:::::::::::::::::::::::::::::: 81 11.4 Extracting substrings::::::::::::::::::::::::::::::::::::::::: 82 11.5 Translating characters :::::::::::::::::::::::::::::::::::::::: 83 11.6 Substituting text by regular expression ::::::::::::::::::::::: 84 11.7 Formatting strings (printf-like) ::::::::::::::::::::::::::::::: 86 12 Macros for doing arithmetic ::::::::::::::::: 89 12.1 Decrement and increment operators::::::::::::::::::::::::::: 89 12.2 Evaluating integer expressions :::::::::::::::::::::::::::::::: 89 iii 13 Macros for running shell commands::::::::: 95 13.1 Determining the platform::::::::::::::::::::::::::::::::::::: 95 13.2 Executing simple commands :::::::::::::::::::::::::::::::::: 96 13.3 Reading the output of commands ::::::::::::::::::::::::::::: 97 13.4 Exit status ::::::::::::::::::::::::::::::::::::::::::::::::::: 97 13.5 Making temporary files ::::::::::::::::::::::::::::::::::::::: 99 14 Miscellaneous builtin macros ::::::::::::::: 101 14.1 Printing error messages:::::::::::::::::::::::::::::::::::::: 101 14.2 Printing current location :::::::::::::::::::::::::::::::::::: 101 14.3 Exiting from m4 ::::::::::::::::::::::::::::::::::::::::::::: 103 15 Fast loading of frozen state ::::::::::::::::: 105 15.1 Using frozen files :::::::::::::::::::::::::::::::::::::::::::: 105 15.2 Frozen file format ::::::::::::::::::::::::::::::::::::::::::: 106 16 Compatibility with other versions of m4:::: 109 16.1 Extensions in GNU M4:::::::::::::::::::::::::::::::::::::: 109 16.2 Facilities in System V m4 not in GNU m4 :::::::::::::::::::: 110 16.3 Other incompatibilities :::::::::::::::::::::::::::::::::::::: 113 17 Correct version of some examples :::::::::: 115 17.1 Solution for exch:::::::::::::::::::::::::::::::::::::::::::: 115 17.2 Solution for forloop :::::::::::::::::::::::::::::::::::::::: 115 17.3 Solution for foreach :::::::::::::::::::::::::::::::::::::::: 117 17.4 Solution for copy:::::::::::::::::::::::::::::::::::::::::::: 124 17.5 Solution for m4wrap ::::::::::::::::::::::::::::::::::::::::: 125 17.6 Solution for cleardivert ::::::::::::::::::::::::::::::::::: 126 17.7 Solution for capitalize::::::::::::::::::::::::::::::::::::: 127 17.8 Solution for fatal_error ::::::::::::::::::::::::::::::::::: 129 Appendix A How to make copies of the overall M4 package::::::::::::::::::::::::::::: 131 A.1 License for copying the M4 package :::::::::::::::::::::::::: 131 Appendix B How to make copies of this manual :: 143 B.1 License for copying this manual :::::::::::::::::::::::::::::: 143 Appendix C Indices of concepts and macros :: 151 C.1 Index for all m4 macros::::::::::::::::::::::::::::::::::::::: 151 C.2 Index for many concepts ::::::::::::::::::::::::::::::::::::: 152 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 m4-1.4.19/AUTHORS and m4-1.4.19/THANKS from the GNU M4 distribution. This is release 1.4.19. 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. 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