[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Changes to m4/doc/m4.texinfo,v [branch-1_4]
From: |
Eric Blake |
Subject: |
Changes to m4/doc/m4.texinfo,v [branch-1_4] |
Date: |
Thu, 24 Aug 2006 14:27:35 +0000 |
CVSROOT: /sources/m4
Module name: m4
Branch: branch-1_4
Changes by: Eric Blake <ericb> 06/08/24 14:27:33
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.69
retrieving revision 1.1.1.1.2.70
diff -u -b -r1.1.1.1.2.69 -r1.1.1.1.2.70
--- doc/m4.texinfo 22 Aug 2006 19:56:09 -0000 1.1.1.1.2.69
+++ doc/m4.texinfo 24 Aug 2006 14:27:33 -0000 1.1.1.1.2.70
@@ -151,8 +151,8 @@
* Names:: Macro names
* Quoted strings:: Quoting input to m4
-* Other tokens:: Other kinds of input tokens
* Comments:: Comments in m4 input
+* Other tokens:: Other kinds of input tokens
* Input processing:: How m4 copies input to output
How to invoke macros
@@ -604,7 +604,7 @@
@node Bugs
@section Problems and bugs
-If you have problems with @acronym{GNU} @code{m4} or think you've found a bug,
+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
really says you can do what you're trying to do. If it's not clear
@@ -713,8 +713,8 @@
@menu
* Names:: Macro names
* Quoted strings:: Quoting input to m4
-* Other tokens:: Other kinds of input tokens
* Comments:: Comments in m4 input
+* Other tokens:: Other kinds of input tokens
* Input processing:: How m4 copies input to output
@end menu
@@ -734,7 +734,8 @@
@section Quoted strings
@cindex quoted string
-A quoted string is a sequence of characters surrounded by the quotes
+A quoted string is a sequence of characters surrounded by quote
+strings, defaulting to
@kbd{`} and @kbd{'}, 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
@@ -757,12 +758,6 @@
The quote characters can be changed at any time, using the builtin macro
@code{changequote}. @xref{Changequote}, for more information.
address@hidden Other tokens
address@hidden Other tokens
-
-Any character, that is neither a part of a name, nor of a quoted string,
-is a token by itself.
-
@node Comments
@section Comments
@@ -787,6 +782,17 @@
the builtin macro @code{changecom}. @xref{Changecom}, for more
information.
address@hidden Other tokens
address@hidden Other 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 (@samp{(} and
address@hidden)}), comma (@samp{,}), and dollar (@samp{$}) have additional
+roles, explained later.
+
@node Input processing
@section Input Processing
@@ -801,7 +807,8 @@
@code{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. If the input is
+call first. For a running example, examine how @code{m4} handles this
+input:
@comment ignore
@example
@@ -809,8 +816,16 @@
@end example
@noindent
address@hidden will first expand @samp{eval(2**15)} to @samp{32768}, and only
-then expand the resulting call
+First, @code{m4} sees that the token @samp{format} is a macro name, so
+it collects the tokens @samp{(}, @samp{`Result is %d'}, @samp{,},
+and @address@hidden }}, before encountering another potential macro. Sure
+enough, @samp{eval} is a macro name, so the nested argument collection
+picks up @samp{(}, @samp{`2**15'}, and @samp{)}, invoking the eval macro
+with the lone argument of @samp{2**15}. The expansion of
address@hidden(2**15)} is @samp{32768}, which is then rescanned as the five
+tokens @samp{3}, @samp{2}, @samp{7}, @samp{6}, and @samp{8}; and
+combined with the next @samp{)}, the format macro now has all its
+arguments, as if the user had typed:
@comment ignore
@example
@@ -818,11 +833,14 @@
@end example
@noindent
-which will give the output
+The format macro expands to @samp{Result is 32768}, and we have another
+round of scanning for the tokens @samp{Result}, @address@hidden }},
address@hidden, @address@hidden }}, @samp{3}, @samp{2}, @samp{7}, @samp{6}, and
address@hidden None of these are macros, so the final output is
@comment ignore
@example
-Result is 32768
address@hidden is 32768
@end example
The order in which @code{m4} expands the macros can be explored using
@@ -911,6 +929,9 @@
whatsoever on user defined macros. For example, with this option,
one has to write @code{m4_dnl} and even @code{m4_m4exit}.
+Another alternative is to redefine problematic macros to a name less
+likely to cause conflicts, @xref{Definitions}.
+
If your version of @acronym{GNU} @code{m4} has the @code{changeword} feature
compiled in, it offers far more flexibility in specifying the
syntax of macro names, both builtin or user-defined. @xref{Changeword},
@@ -1010,6 +1031,7 @@
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.
Normally @code{m4} will issue warnings if a builtin macro is called
with an inappropriate number of arguments, but it can be suppressed with
@@ -3313,6 +3335,14 @@
@result{}-1
@end example
+Omitting @var{substring} evokes a warning, but still produces output.
+
address@hidden
+index(`abc')
address@hidden:stdin:1: Warning: too few arguments to builtin `index'
address@hidden
address@hidden example
+
@node Regexp
@section Searching for regular expressions
@@ -3378,6 +3408,14 @@
@result{}c
@end example
+Omitting @var{regexp} evokes a warning, but still produces output.
+
address@hidden
+regexp(`abc')
address@hidden:stdin:1: Warning: too few arguments to builtin `regexp'
address@hidden
address@hidden example
+
@node Substr
@section Extracting substrings
@@ -3403,6 +3441,17 @@
@result{}gnats
@end example
+Omitting @var{from} evokes a warning, but still produces output.
+
address@hidden
+substr(`abc')
address@hidden:stdin:1: Warning: too few arguments to builtin `substr'
address@hidden
+substr(`abc',)
address@hidden:stdin:2: empty string treated as 0 in builtin `substr'
address@hidden
address@hidden example
+
@node Translit
@section Translating characters
@@ -3447,6 +3496,14 @@
while converting them to lowercase. The two first cases are by far the
most common.
+Omitting @var{chars} evokes a warning, but still produces output.
+
address@hidden
+translit(`abc')
address@hidden:stdin:1: Warning: too few arguments to builtin `translit'
address@hidden
address@hidden example
+
@node Patsubst
@section Substituting text by regular expression
@@ -3489,7 +3546,7 @@
patsubst(`GNUs not Unix', `\<', `OBS: ')
@result{}OBS: GNUs OBS: not OBS: Unix
patsubst(`GNUs not Unix', `\w*', `(\&)')
address@hidden(GNUs)() (not)() (Unix)
address@hidden(GNUs)() (not)() (Unix)()
patsubst(`GNUs not Unix', `\w+', `(\&)')
@result{}(GNUs) (not) (Unix)
patsubst(`GNUs not Unix', `[A-Z][a-z]+')
@@ -3540,6 +3597,14 @@
@result{}bab
@end example
+Omitting @var{regexp} evokes a warning, but still produces output.
+
address@hidden
+patsubst(`abc')
address@hidden:stdin:1: Warning: too few arguments to builtin `patsubst'
address@hidden
address@hidden example
+
@node Format
@section Formatted output
@@ -4020,7 +4085,8 @@
@example
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
+ifdef(`__unix__', ,
+ `errprint(` skipping: syscmd does not have unix semantics
')m4exit(`77')')dnl
syscmd(`kill -13 $$')
@result{}
- Changes to m4/doc/m4.texinfo,v [branch-1_4], (continued)
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/03
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/04
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/08
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/09
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/12
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/14
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/15
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/16
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/17
- Changes to m4/doc/m4.texinfo,v [branch-1_4], Eric Blake, 2006/08/22
- Changes to m4/doc/m4.texinfo,v [branch-1_4],
Eric Blake <=