CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/08/31 03:21:36
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -b -r1.38 -r1.39
--- doc/m4.texinfo 30 Aug 2006 13:35:20 -0000 1.38
+++ doc/m4.texinfo 31 Aug 2006 03:21:35 -0000 1.39
@@ -1202,12 +1202,12 @@
@example
$ @kbd{m4}
index(`abc')
[EMAIL PROTECTED]:input.m4:1: Warning: index: too few arguments: 1 < 2
[EMAIL PROTECTED]:stdin:1: Warning: index: too few arguments: 1 < 2
@result{}0
index(`abc',)
@result{}0
index(`abc', `b', `ignored')
[EMAIL PROTECTED]:input.m4:3: Warning: index: extra arguments ignored: 3 > 2
[EMAIL PROTECTED]:stdin:3: Warning: index: extra arguments ignored: 3 > 2
@result{}1
@end example
@@ -1256,7 +1256,7 @@
@example
define(
^D
[EMAIL PROTECTED]:input.m4:1: ERROR: end of file in argument list
[EMAIL PROTECTED]:stdin:1: ERROR: end of file in argument list
@end example
@node Quoting Arguments
@@ -1784,7 +1784,7 @@
@example
define(defn(`divnum'), `cannot redefine a builtin token')
[EMAIL PROTECTED]:input.m4:1: Warning: define: invalid macro name ignored
[EMAIL PROTECTED]:stdin:1: Warning: define: invalid macro name ignored
@result{}
divnum
@result{}0
@@ -1797,14 +1797,14 @@
@example
defn(`foo')
[EMAIL PROTECTED]:input.m4:1: Warning: defn: undefined macro: foo
[EMAIL PROTECTED]:stdin:1: Warning: defn: undefined macro `foo'
@result{}
define(`foo', `a')
@result{}
define(`bar', defn(`foo', `divnum'))
[EMAIL PROTECTED]
[EMAIL PROTECTED]
define(`blah', defn(`divnum', `foo'))
[EMAIL PROTECTED]
[EMAIL PROTECTED]
bar
@result{}a0
blah
@@ -1856,7 +1856,6 @@
popdef(`foo')
@result{}
foo
[EMAIL PROTECTED] one.
@result{}Expansion three.
popdef(`foo', `foo')
@result{}
@@ -1977,16 +1976,19 @@
@cindex indirect call of macros
@cindex call of macros, indirect
@cindex macros, indirect call of
[EMAIL PROTECTED] GNU extensions
[EMAIL PROTECTED] @acronym{GNU} extensions
+Any macro can be called indirectly with @code{indir}:
+
@deffn {Builtin (gnu)} indir (@var{name}, @dots{})
-Any macro can be called indirectly with @code{indir}, which results in a
-call to the macro @var{name}, which is passed the rest of the arguments.
+Results in a call to the macro @var{name}, which is passed the
+rest of the arguments. If @var{name} is not defined, an error message
+is printed, and the expansion is void.
-The macro @code{defn} is recognized only with parameters.
+The macro @code{indir} is recognized only with parameters.
@end deffn
-This can be used to call macros with computed or with ``illegal'' names
-(@code{define} allows such names to be defined):
+This can be used to call macros with computed or ``invalid''
+names (@code{define} allows such names to be defined):
@example
define(`$$internal$macro', `Internal macro (name `$0')')
@@ -1997,7 +1999,7 @@
@result{}Internal macro (name $$internal$macro)
@end example
-The point here is that larger macro packages can have private macros
+The point is, here, that larger macro packages can have private macros
defined, that will not be called by accident. They can @emph{only} be
called through the builtin @code{indir}.
@@ -2007,45 +2009,115 @@
@cindex indirect call of builtins
@cindex call of builtins, indirect
@cindex builtins, indirect call of
[EMAIL PROTECTED] GNU extensions
[EMAIL PROTECTED] @acronym{GNU} extensions
+Builtin macros can be called indirectly with @code{builtin}:
+
@deffn {Builtin (gnu)} builtin (@var{name}, @dots{})
-Builtin macros can be called indirectly with @code{builtin}, which
-results in a call to the builtin @var{name}, which is passed the rest of
-the arguments. This can be used, if @var{name} has been given another
-definition that has covered the original.
+Results in a call to the builtin @var{name}, which is passed the
+rest of the arguments. If @var{name} does not name a builtin, a warning
+message is printed, and the expansion is void.
The macro @code{builtin} is recognized only with parameters.
@end deffn
+This can be used even if @var{name} has been given another definition
+that has covered the original, or been undefined so that no macro
+maps to the builtin.
+
[EMAIL PROTECTED]
+pushdef(`define', `hidden')
[EMAIL PROTECTED]
+undefine(`undefine')
[EMAIL PROTECTED]
+define(`foo', `bar')
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]
+builtin(`define', `foo', `BAR')
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]
+undefine(`foo')
[EMAIL PROTECTED](foo)
+foo
[EMAIL PROTECTED]
+builtin(`undefine', `foo')
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
+The @var{name} argument only matches the original name of the builtin,
+even when the @option{--prefix-builtins} option (or @option{-P},
[EMAIL PROTECTED] m4}) is in effect. This is different from @code{indir},
+which only tracks current macro names.
+
[EMAIL PROTECTED] options: -P
[EMAIL PROTECTED]
+$ @kbd{m4 -P}
+m4_builtin(`divnum')
[EMAIL PROTECTED]
+m4_builtin(`m4_divnum')
[EMAIL PROTECTED]:stdin:2: Warning: m4_builtin: undefined builtin `m4_divnum'
[EMAIL PROTECTED]
+m4_indir(`divnum')
[EMAIL PROTECTED]:stdin:3: Warning: m4_indir: undefined macro `divnum'
[EMAIL PROTECTED]
+m4_indir(`m4_divnum')
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
+Note that @code{indir} and @code{builtin} can be used to invoke builtins
+without arguments, even when they normally require parameters to be
+recognized; but it will provoke a warning, and the expansion will behave
+as though empty strings had been passed as the required arguments.
+
[EMAIL PROTECTED]
+builtin
[EMAIL PROTECTED]
+builtin()
[EMAIL PROTECTED]:stdin:2: Warning: builtin: undefined builtin `'
[EMAIL PROTECTED]
+builtin(`builtin')
[EMAIL PROTECTED]:stdin:3: Warning: builtin: too few arguments: 0 < 1
[EMAIL PROTECTED]
+builtin(`builtin',)
[EMAIL PROTECTED]:stdin:4: Warning: builtin: undefined builtin `'
[EMAIL PROTECTED]
+indir(`index')
[EMAIL PROTECTED]:stdin:5: Warning: index: too few arguments: 0 < 2
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
@node Symbols
@section Getting the defined macro names
@cindex macro names
[EMAIL PROTECTED] GNU extensions
-The name of the currently defined macro can be accessed by
[EMAIL PROTECTED] @acronym{GNU} extensions
+The name of the currently defined macros can be accessed by
@code{symbols}:
[EMAIL PROTECTED] {Builtin (gnu)} symbols
[EMAIL PROTECTED] {Builtin (gnu)} symbols (@dots{})
[EMAIL PROTECTED] {Builtin (gnu)} symbols (@dots{})
Without arguments, @samp{symbols} expands to a sorted list of quoted
-strings. This contrasts with @code{dumpdef} which output can not be
-accessed by @code{m4} programs.
+strings, separated by commas. This contrasts with @code{dumpdef}
+(@pxref{Dumpdef}), whose output cannot be accessed by @code{m4}
+programs.
When given arguments, @code{symbols} returns the sorted subset of the
-symbols currently defined:
+symbols currently defined.
[EMAIL PROTECTED] deffn
@example
symbols(`ifndef', `ifdef', `define', `undef')
@result{}define,ifdef
@end example
[EMAIL PROTECTED] deffn
@node Conditionals
@chapter Conditionals, loops, and recursion
Macros, expanding to plain text, perhaps with arguments, are not quite
enough. We would like to have macros expand to different things, based
-on decisions taken at run-time. E.g., we need some kind of conditionals.
+on decisions taken at run-time. For that, we need some kind of conditionals.
Also, we would like to have some kind of loop construct, so we could do
something a number of times, or while some condition is true.
@@ -2059,10 +2131,11 @@
@section Testing macro definitions
@cindex conditionals
[EMAIL PROTECTED] {Builtin (m4)} ifdef (@var{name}, @var{string-1}, @w{opt
@var{string-2})}
There are two different builtin conditionals in @code{m4}. The first is
[EMAIL PROTECTED], which test whether a macro is defined or not. If
[EMAIL PROTECTED] is defined as a macro, @code{ifdef} expands to
[EMAIL PROTECTED]:
+
[EMAIL PROTECTED] {Builtin (m4)} ifdef (@var{name}, @var{string-1},
@ovar{string-2})
+If @var{name} is defined as a macro, @code{ifdef} expands to
@var{string-1}, otherwise to @var{string-2}. If @var{string-2} is
omitted, it is taken to be the empty string (according to the normal
rules).
@@ -2077,6 +2150,9 @@
@result{}
ifdef(`foo', ``foo' is defined', ``foo' is not defined')
@result{}foo is defined
+ifdef(`no_such_macro', `yes', `no', `extra argument')
[EMAIL PROTECTED]:stdin:4: Warning: ifdef: extra arguments ignored: 4 > 3
[EMAIL PROTECTED]
@end example
@node Ifelse
@@ -2100,7 +2176,7 @@
ifelse(`some comments')
@result{}
ifelse(`foo', `bar')
[EMAIL PROTECTED]:input.m4:2: Warning: ifelse: too few arguments: 2 < 3
[EMAIL PROTECTED]:stdin:2: Warning: ifelse: too few arguments: 2 < 3
@result{}
@end example
@@ -2249,6 +2325,13 @@
like start value less than final value, and the first argument not being
a name. Correcting these errors are left as an exercise to the reader.
[EMAIL PROTECTED] FIXME - it would be nice to introduce foreach here, and even
[EMAIL PROTECTED] give an example like this for finding defined macros that meet
[EMAIL PROTECTED] a certain pattern (see examples/foreach.m4):
[EMAIL PROTECTED] define(`quote', ``$@'')
[EMAIL PROTECTED] foreach(`macro', (quote(symbols)),
[EMAIL PROTECTED] `regexp(macro, `.*_.*', ``\&',')')
+
@node Debugging
@chapter How to debug macros and input
@@ -2823,7 +2906,7 @@
define(`test.1', `TEST ONE')
@result{}
__file__
[EMAIL PROTECTED]
[EMAIL PROTECTED]
changesyntax(`O_', `W.')
@result{}
__file__
@@ -3092,7 +3175,7 @@
@example
include(`n')
@result{}
[EMAIL PROTECTED]:input.m4:1: include: cannot open `n': No such file or
directory
[EMAIL PROTECTED]:stdin:1: include: cannot open `n': No such file or directory
sinclude(`n')
@result{}
@end example
@@ -4076,7 +4159,7 @@
define(`foo', `666')
@result{}
eval(`foo / 6')
[EMAIL PROTECTED]:input.m4:7: eval: bad expression: foo / 6
[EMAIL PROTECTED]:stdin:7: eval: bad expression: foo / 6
@result{}
eval(foo/6)
@result{}111
@@ -4317,7 +4400,7 @@
@example
errprint(`m4:'__file__:__line__: `Input error
')
[EMAIL PROTECTED]:input.m4:1: Input error
[EMAIL PROTECTED]:stdin:1: Input error
@result{}
@end example
@end deffn
@@ -4341,7 +4424,7 @@
')m4exit(1)')
@result{}
fatal_error(`This is a BAD one, buster')
[EMAIL PROTECTED]:input.m4:4: fatal error: This is a BAD one, buster
[EMAIL PROTECTED]:stdin:4: fatal error: This is a BAD one, buster
@end example
After this macro call, @code{m4} will exit with exit code 1. This macro
