CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 07/03/02 03:26:30
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.99
retrieving revision 1.100
diff -u -b -r1.99 -r1.100
--- doc/m4.texinfo 1 Mar 2007 14:30:25 -0000 1.99
+++ doc/m4.texinfo 2 Mar 2007 03:26:30 -0000 1.100
@@ -2,15 +2,14 @@
@comment ========================================================
@comment %**start of header
@setfilename m4.info
[EMAIL PROTECTED] GNU M4 macro processor
[EMAIL PROTECTED] version.texi
[EMAIL PROTECTED] GNU M4 @value{VERSION} macro processor
@setchapternewpage odd
@ifnothtml
@setcontentsaftertitlepage
@end ifnothtml
@finalout
[EMAIL PROTECTED] version.texi
-
@set beta
@c @tabchar{}
@@ -295,8 +294,8 @@
Indices of concepts and macros
-* Concept index:: Index for many concepts
* Macro index:: Index for all @code{m4} macros
+* Concept index:: Index for many concepts
@end detailmenu
@end menu
@@ -322,6 +321,7 @@
@node Intro
@section Introduction to @code{m4}
[EMAIL PROTECTED] overview of @code{m4}
@code{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.
@@ -353,6 +353,8 @@
@node History
@section Historical references
[EMAIL PROTECTED] history of @code{m4}
[EMAIL PROTECTED] @acronym{GNU} M4, history of
@code{GPM} was an important ancestor of @code{m4}. See
C. Stratchey: ``A General Purpose Macro generator'', Computer Journal
8,3 (1965), pp. 225 ff. @code{GPM} is also succinctly described into
@@ -413,6 +415,9 @@
@node Bugs
@section Problems and bugs
[EMAIL PROTECTED] reporting bugs
[EMAIL PROTECTED] bug reports
[EMAIL PROTECTED] suggestions, reporting
If you have problems with @acronym{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
@@ -439,6 +444,7 @@
@node Manual
@section Using this manual
[EMAIL PROTECTED] examples, understanding
This manual contains a number of examples of @code{m4} input and output,
and a simple notation is used to distinguish input, output and error
messages from @code{m4}. Examples are set out from the normal text, and
@@ -529,6 +535,8 @@
@node Invoking m4
@chapter Invoking @code{m4}
[EMAIL PROTECTED] command line
[EMAIL PROTECTED] invoking @code{m4}
The format of the @code{m4} command is:
@comment ignore
@@ -611,6 +619,8 @@
@item -E
@itemx --fatal-warnings
[EMAIL PROTECTED] errors, fatal
[EMAIL PROTECTED] fatal errors
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,
@@ -715,6 +725,7 @@
@cindex macro definitions, on the command line
@cindex command line, macro definitions on the
[EMAIL PROTECTED] preprocessor features
Several options allow @code{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
@@ -775,6 +786,9 @@
Short for @option{--syncoutput=1}, turning synchronization lines on.
@item [EMAIL PROTECTED]@r{]}
[EMAIL PROTECTED] synchronization lines
[EMAIL PROTECTED] location, input
[EMAIL PROTECTED] input location
Control the generation of synchronization lines from the command line.
Synchronization lines are for use by the C preprocessor or other
similar tools. Order is significant with respect to file names. This
@@ -830,6 +844,8 @@
@item -L @var{NUM}
@itemx [EMAIL PROTECTED]
[EMAIL PROTECTED] nesting limit
[EMAIL PROTECTED] limit, nesting
Artificially limit the nesting of macro calls to @var{NUM} levels,
stopping program execution if this limit is ever exceeded. When not
specified, nesting is limited to 1024 levels. A value of zero means
@@ -846,6 +862,7 @@
Most users would never need this option. If shown to be obtrusive,
this option (which is still experimental) might well disappear.
[EMAIL PROTECTED] rescanning
This option does @emph{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
@@ -1046,6 +1063,7 @@
@section Macro names
@cindex names
[EMAIL PROTECTED] words
A name is any sequence of letters, digits, and the character @samp{_}
(underscore), where the first character is not a digit. @code{m4} will
use the longest such sequence found in the input. If a name has a
@@ -1062,6 +1080,7 @@
@section Quoting input to @code{m4}
@cindex quoted string
[EMAIL PROTECTED] string, quoted
A quoted string is a sequence of characters surrounded by quote
strings, defaulting to
@samp{`} and @samp{'}, where the nested begin and end quotes within the
@@ -1126,6 +1145,7 @@
@node Other tokens
@section Other kinds of input tokens
[EMAIL PROTECTED] tokens, special
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,
@@ -1343,6 +1363,7 @@
@section Macro invocation
@cindex macro invocation
[EMAIL PROTECTED] invoking macros
Macro invocations has one of the forms
@comment ignore
@@ -1475,6 +1496,7 @@
the @code{divert} builtin macro will be called, which expands to the
empty string.
[EMAIL PROTECTED] rescanning
The output of macro evaluations is always rescanned. The following
example would yield the string @samp{de}, exactly as if @code{m4}
has been given @[EMAIL PROTECTED](`abcde', `3', `2')}} as input:
@@ -1556,6 +1578,8 @@
@result{}
@end example
[EMAIL PROTECTED] warnings, suppressing
[EMAIL PROTECTED] suppressing warnings
Normally @code{m4} will issue warnings if a builtin macro is called
with an inappropriate number of arguments, but it can be suppressed with
the @option{--quiet} command line option (or @option{--silent}, or
@@ -1655,6 +1679,8 @@
foo(`() (() (')
@end example
[EMAIL PROTECTED] quoting rule of thumb
[EMAIL PROTECTED] rule of thumb, quoting
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
@@ -1800,7 +1826,15 @@
(@pxref{Indir}) and @code{Defn} (@pxref{Defn}).
@cindex arrays
-Arrays and associative arrays can be simulated by using this trick.
+Arrays and associative arrays can be simulated by using non-standard
+macro names.
+
[EMAIL PROTECTED] Composite array (@var{index})
[EMAIL PROTECTED] Composite array_set (@var{index}, @ovar{value})
+Provide access to entries within an array. @code{array} reads the entry
+at location @var{index}, and @code{array_set} assigns @var{value} to
+location @var{index}.
[EMAIL PROTECTED] deffn
@example
define(`array', `defn(format(``array[%d]'', `$1'))')
@@ -1817,19 +1851,24 @@
@result{}array element no. 17
@end example
-Change the @code{%d} to @code{%s} and it is an associative array.
+Change the @samp{%d} to @samp{%s} and it is an associative array.
@node Arguments
@section Arguments to macros
@cindex macros, arguments to
[EMAIL PROTECTED] Arguments to macros
[EMAIL PROTECTED] arguments to macros
Macros can have arguments. The @var{n}th argument is denoted by
@code{$n} in the expansion text, and is replaced by the @var{n}th 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. It simply exchanges the order of the two arguments.
+two arguments.
+
[EMAIL PROTECTED] Composite exch (@var{arg1}, @var{arg2})
+Expands to @var{arg2} followed by @var{arg1}, effectively exchanging
+their order.
[EMAIL PROTECTED] deffn
@example
define(`exch', `$2, $1')
@@ -1902,8 +1941,11 @@
and for all the actual arguments.
The number of actual arguments in a macro call is denoted by @code{$#}
-in the expansion text. Thus, a macro to display the number of arguments
-given can be
+in the expansion text.
+
[EMAIL PROTECTED] Composite nargs (@dots{})
+Expands to a count of the number of arguments supplied.
[EMAIL PROTECTED] deffn
@example
define(`nargs', `$#')
@@ -2011,6 +2053,9 @@
@result{}$$$ hello $$$
@end example
[EMAIL PROTECTED] rescanning
[EMAIL PROTECTED] literal output
[EMAIL PROTECTED] output, literal
If you want a macro to expand to something like @samp{$12}, the
judicious use of nested quoting can put a safe character between the
@code{$} and the next character, relying on the rescanning to remove the
@@ -2093,6 +2138,8 @@
@cindex macros, how to rename
@cindex renaming macros
[EMAIL PROTECTED] macros, displaying definitions
[EMAIL PROTECTED] definitions, displaying macro
It is possible to rename an already defined macro. To do this, you need
the builtin @code{defn}:
@@ -2161,6 +2208,7 @@
@result{}
@end example
[EMAIL PROTECTED] rescanning
However, it is important to remember that @code{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
@@ -2183,6 +2231,8 @@
@result{}AA'
@end example
[EMAIL PROTECTED] builtins, special tokens
[EMAIL PROTECTED] tokens, builtin macro
Using @code{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.
@@ -2225,6 +2275,8 @@
@cindex macros, temporary redefinition of
@cindex temporary redefinition of macros
@cindex redefinition of macros, temporary
[EMAIL PROTECTED] definition stack
[EMAIL PROTECTED] stack, macro definition
It is possible to redefine a macro temporarily, reverting to the
previous definition at a later time. This is done with the builtins
@code{pushdef} and @code{popdef}:
@@ -2634,7 +2686,9 @@
@node M4symbols
@section Getting the defined macro names
[EMAIL PROTECTED] macro names
[EMAIL PROTECTED] macro names, listing
[EMAIL PROTECTED] listing macro names
[EMAIL PROTECTED] currently defined macros
@cindex @acronym{GNU} extensions
The name of the currently defined macros can be accessed by
@code{m4symbols}:
@@ -2704,6 +2758,8 @@
@section If-else construct, or multibranch
@cindex comparing strings
[EMAIL PROTECTED] discarding input
[EMAIL PROTECTED] input, discarding
The other conditional, @code{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:
@@ -2776,6 +2832,8 @@
@end example
@cindex multibranches
[EMAIL PROTECTED] switch statement
[EMAIL PROTECTED] case statement
However, @code{ifelse} can take more than four arguments. If given more
than four arguments, @code{ifelse} works like a @code{case} or @code{switch}
statement in traditional programming languages. If @var{string-1} and
@@ -3188,6 +3246,8 @@
@node Debugging
@chapter How to debug macros and input
[EMAIL PROTECTED] debugging macros
[EMAIL PROTECTED] macros, debugging
When writing macros for @code{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 @code{m4}.
@@ -3206,6 +3266,7 @@
@cindex displaying macro definitions
@cindex macros, displaying definitions
@cindex definitions, displaying macro
[EMAIL PROTECTED] standard error, output to
If you want to see what a name expands into, you can use the builtin
@code{dumpdef}:
@@ -3284,6 +3345,7 @@
@cindex tracing macro expansion
@cindex macro expansion, tracing
@cindex expansion, tracing macro
[EMAIL PROTECTED] standard error, output to
It is possible to trace macro calls and expansions through the builtins
@code{traceon} and @code{traceoff}:
@@ -3776,6 +3838,8 @@
@section Deleting whitespace in input
@cindex deleting whitespace in input
[EMAIL PROTECTED] discarding input
[EMAIL PROTECTED] input, discarding
The builtin @code{dnl} stands for ``Discard to Next Line'':
@deffn {Builtin (m4)} dnl
@@ -3834,8 +3898,9 @@
@node Changequote
@section Changing the quote characters
[EMAIL PROTECTED] changing the quote delimiters
[EMAIL PROTECTED] quote delimiters, changing the
[EMAIL PROTECTED] changing quote delimiters
[EMAIL PROTECTED] quote delimiters, changing
[EMAIL PROTECTED] delimiters, changing
The default quote delimiters can be changed with the builtin
@code{changequote}:
@@ -4021,6 +4086,7 @@
@cindex changing comment delimiters
@cindex comment delimiters, changing
[EMAIL PROTECTED] delimiters, changing
The default comment delimiters can be changed with the builtin
macro @code{changecom}:
@@ -4169,6 +4235,12 @@
@section Changing the regular expression syntax
@cindex regular expression syntax, changing
[EMAIL PROTECTED] basic regular expressions
[EMAIL PROTECTED] extended regular expressions
[EMAIL PROTECTED] regular expressions
[EMAIL PROTECTED] expressions, regular
[EMAIL PROTECTED] syntax, changing regular expression
[EMAIL PROTECTED] flavors of regular expressions
@cindex @acronym{GNU} extensions
The @acronym{GNU} extensions @code{patsubst}, @code{regexp}, and more
recently, @code{renamesyms} each deal with regular expressions. There
@@ -4278,6 +4350,7 @@
@cindex lexical structure of the input
@cindex input, lexical structure of the
@cindex syntax table
[EMAIL PROTECTED] changing syntax
@cindex @acronym{GNU} extensions
@quotation
The macro @code{changesyntax} and all associated functionality is
@@ -4680,6 +4753,8 @@
@cindex saving input
@cindex input, saving
[EMAIL PROTECTED] deferring expansion
[EMAIL PROTECTED] expansion, deferring
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 @code{m4} when the
normal input has been exhausted. This feature is normally used to
@@ -4760,7 +4835,6 @@
@cindex file inclusion
@cindex inclusion, of files
-
@code{m4} allows you to include named files at any point in the input.
@menu
@@ -4889,6 +4963,7 @@
@node Diversions
@chapter Diverting and undiverting output
[EMAIL PROTECTED] deferring output
Diversions are a way of temporarily saving output. The output of
@code{m4} can at any time be diverted to a temporary file, and be
reinserted into the output stream, @dfn{undiverted}, again at a later
@@ -4970,6 +5045,8 @@
@result{}Wrapped TEXT precedes diverted text.
@end example
[EMAIL PROTECTED] discarding input
[EMAIL PROTECTED] input, discarding
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
@@ -5028,6 +5105,8 @@
order given. If no arguments are supplied, all diversions are
undiverted, in numerical order.
[EMAIL PROTECTED] file inclusion
[EMAIL PROTECTED] inclusion, of files
@cindex @acronym{GNU} extensions
As a @acronym{GNU} extension, @var{diversions} may contain non-numeric
strings, which are treated as the names of files to copy into the output
@@ -5225,6 +5304,8 @@
@chapter Extending M4 with dynamic runtime modules
@cindex modules
[EMAIL PROTECTED] dynamic modules
[EMAIL PROTECTED] loadable modules
@acronym{GNU} M4 1.4.x had a monolithic architecture. All of its
functionality was contained in a single binary, and additional macros
could be added only by writing more code in the M4 language, or at the
@@ -5530,6 +5611,7 @@
@node Index macro
@section Searching for substrings
[EMAIL PROTECTED] substrings, locating
Searching for substrings is done with @code{index}:
@deffn {Builtin (m4)} index (@var{string}, @var{substring})
@@ -5560,6 +5642,7 @@
@section Searching for regular expressions
@cindex regular expressions
[EMAIL PROTECTED] expressions, regular
@cindex @acronym{GNU} extensions
Searching for regular expressions is done with the builtin
@code{regexp}:
@@ -5763,6 +5846,7 @@
@section Substituting text by regular expression
@cindex regular expressions
[EMAIL PROTECTED] expressions, regular
@cindex pattern substitution
@cindex substitution by regular expression
@cindex @acronym{GNU} extensions
@@ -6395,7 +6479,6 @@
string.
@end deffn
[EMAIL PROTECTED] platform macro
On UNIX systems, @acronym{GNU} @code{m4} will define @[EMAIL PROTECTED]
in the @samp{gnu} module, and @code{unix} in the @samp{traditional}
module.
@@ -6546,25 +6629,87 @@
@node Sysval
@section Exit status
[EMAIL PROTECTED] exit code from shell commands
[EMAIL PROTECTED] shell commands, exit code from
[EMAIL PROTECTED] UNIX commands, exit code from
[EMAIL PROTECTED] commands, exit code from shell
[EMAIL PROTECTED] UNIX commands, exit status from
[EMAIL PROTECTED] exit status from shell commands
[EMAIL PROTECTED] shell commands, exit status from
[EMAIL PROTECTED] commands, exit status from shell
[EMAIL PROTECTED] status of shell commands
+To see whether a shell command succeeded, use @code{sysval}:
+
@deffn {Builtin (m4)} sysval
-To see whether a shell command succeeded, use @code{sysval}, which
-expands to the exit status of the last shell command run with
[EMAIL PROTECTED] or @code{esyscmd}.
+Expands to the exit status of the last shell command run with
[EMAIL PROTECTED] or @code{esyscmd}. Expands to 0 if no command has been
+run yet.
@end deffn
@example
+sysval
[EMAIL PROTECTED]
syscmd(`false')
@result{}
-ifelse(sysval, 0, zero, nonzero)
[EMAIL PROTECTED]
+ifelse(sysval, `0', `zero', `non-zero')
[EMAIL PROTECTED]
+syscmd(`exit 2')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
syscmd(`true')
@result{}
sysval
@result{}0
+esyscmd(`false')
[EMAIL PROTECTED]
+ifelse(sysval, `0', `zero', `non-zero')
[EMAIL PROTECTED]
+esyscmd(`exit 2')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
+esyscmd(`true')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] 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.
+
+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.
+
[EMAIL PROTECTED] This test has difficulties being portable, even on platforms
[EMAIL PROTECTED] where syscmd invokes /bin/sh. Kill is not portable with
signal
[EMAIL PROTECTED] names. According to autoconf, the only portable signal
numbers
[EMAIL PROTECTED] are 1 (HUP), 2 (INT), 9 (KILL), 13 (PIPE) and 15 (TERM). But
[EMAIL PROTECTED] all shells handle SIGINT, and ksh handles HUP (as in, the
shell
[EMAIL PROTECTED] exits normally rather than letting the signal terminate it).
[EMAIL PROTECTED] Also, TERM is flaky, as it can also kill the running m4 on
[EMAIL PROTECTED] systems where /bin/sh does not create its own process group.
[EMAIL PROTECTED] And PIPE is unreliable, since people tend to run with it
[EMAIL PROTECTED] ignored, with m4 inheriting that choice. That leaves KILL as
[EMAIL PROTECTED] the only signal we can reliably test.
[EMAIL PROTECTED]
+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 $$')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
+syscmd()
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
+esyscmd(`kill -9 $$')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
@end example
When the @option{--safer} option (@pxref{Operation modes, , Invoking
@@ -6835,6 +6980,8 @@
@node Location
@section Printing current location
[EMAIL PROTECTED] location, input
[EMAIL PROTECTED] input location
To make it possible to specify the location of an error, three
utility builtins exist:
@@ -6930,6 +7077,10 @@
@section Exiting from @code{m4}
@cindex exiting from @code{m4}
[EMAIL PROTECTED] status, setting @code{m4} exit
+If you need to exit from @code{m4} before the entire input has been
+read, you can use @code{m4exit}:
+
@deffn {Builtin (m4)} m4exit (@ovar{code})
If you need to exit from @code{m4} before the entire input has been
read, you can use @code{m4exit}, which causes @code{m4} to exit, with
@@ -6955,7 +7106,10 @@
@node Syncoutput
@section Turning on and off sync lines
[EMAIL PROTECTED] Toggling sync lines within @code{m4}
[EMAIL PROTECTED] toggling synchronization lines
[EMAIL PROTECTED] synchronization lines
[EMAIL PROTECTED] location, input
[EMAIL PROTECTED] input location
@deffn {Builtin (gnu)} syncoutput (@var{truth})
If you need to toggle sync lines on and off while processing macros, or
to insure that they are off or on, you may do so using
@@ -7089,6 +7243,8 @@
@node Frozen file format 1
@section Frozen file format 1
[EMAIL PROTECTED] frozen file format 1
[EMAIL PROTECTED] file format, frozen file version 1
Wow - thanks for really reading the manual. Report this as a bug if
this text is not removed before a release.
FIXME - split out the two formats into separate nodes.
@@ -7103,6 +7259,8 @@
@node Frozen file format 2
@section Frozen file format 2
[EMAIL PROTECTED] frozen file format 2
[EMAIL PROTECTED] file format, frozen file version 2
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 a newer version of GNU @code{m4}.
@@ -7510,6 +7668,8 @@
@error{}m4trace: -3- shift(`4')
@end example
[EMAIL PROTECTED] quadratic behavior, avoiding
[EMAIL PROTECTED] avoiding quadratic behavior
Each successive iteration was adding more quoted @code{shift}
invocations, and the entire list contents were passing through every
iteration. In general, when recursing, it is a good idea to make the
@@ -7756,27 +7916,24 @@
@appendix Indices of concepts and macros
@menu
-* Concept index:: Index for many concepts
* Macro index:: Index for all @code{m4} macros
+* Concept index:: Index for many concepts
@end menu
[EMAIL PROTECTED] Concept index
[EMAIL PROTECTED] Index for many concepts
-
[EMAIL PROTECTED] cp
-
@node Macro index
@appendixsec Index for all @code{m4} macros
-References are exclusively to the places where a builtin is introduced
-the first time.
-
[EMAIL PROTECTED]
[EMAIL PROTECTED] 1
[EMAIL PROTECTED] iftex
+This index covers all @code{m4} builtins, as well as several useful
+composite macros. References are exclusively to the places where a
+macro is introduced the first time.
@printindex fn
[EMAIL PROTECTED] Concept index
[EMAIL PROTECTED] Index for many concepts
+
[EMAIL PROTECTED] cp
+
@bye
@c Local Variables:
