CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/10/27 17:03:51
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.73
retrieving revision 1.74
diff -u -b -r1.73 -r1.74
--- doc/m4.texinfo 25 Oct 2006 23:19:19 -0000 1.73
+++ doc/m4.texinfo 27 Oct 2006 17:03:51 -0000 1.74
@@ -2231,10 +2231,17 @@
Builtin macros can be called indirectly with @code{builtin}:
@deffn {Builtin (gnu)} builtin (@var{name}, @[EMAIL PROTECTED])
[EMAIL PROTECTED] {Builtin (gnu)} builtin (@code{defn(`builtin')}, @var{name1})
Results in a call to the builtin @var{name}, which is passed the
rest of the arguments @var{args}. If @var{name} does not name a
builtin, a warning message is printed, and the expansion is void.
+As a special case, if @var{name} is exactly the special token
+representing the @code{builtin} macro, as obtained by @code{defn}
+(@pxref{Defn}), then @var{args} must consist of a single @var{name1},
+and the expansion is the special token representing the builtin macro
+named by @var{name1}.
+
The macro @code{builtin} is recognized only with parameters.
@end deffn
@@ -2311,6 +2318,65 @@
@result{}0
@end example
+Normally, once a builtin macro is undefined, the only way to retrieve
+its functionality is by defining a new macro that expands to
[EMAIL PROTECTED] under the hood. But this extra layer of expansion is
+slightly inefficient, not to mention the fact that it is not robust to
+changes in the current quoting scheme due to @code{changequote}
+(@pxref{Changequote}). On the other hand, defining a macro to the
+special token produced by @code{defn} (@pxref{Defn}) is very efficient,
+and avoids the need for quoting within the macro definition; but
[EMAIL PROTECTED] only works if the desired macro is already defined by some
+other name. So @code{builtin} provides a special case where it is
+possible to retrieve the same special token representing a builtin as
+what @code{defn} would provide, were the desired macro still defined.
+This feature is activated by passing @code{defn(`builtin')} as the first
+argument to builtin. Normally, passing a special token representing a
+macro as @var{name} results in a warning and an empty expansion, but in
+this case, if the second argument @var{name1} names a valid builtin,
+there is no warning and the expansion is the appropriate special
+token. In fact, with just the @code{builtin} macro accessible, it is
+possible to reconstitute the entire startup state of @code{m4}.
+
+In the example below, compare the number of macro invocations performed
+by @code{defn1} and @code{defn2}, and the differences once quoting is
+changed.
+
[EMAIL PROTECTED]
+$ @kbd{m4 -d}
+undefine(`defn')
[EMAIL PROTECTED]
+define(`foo', `bar')
[EMAIL PROTECTED]
+define(`defn1', `builtin(`defn', $@@)')
[EMAIL PROTECTED]
+define(`defn2', builtin(builtin(`defn', `builtin'), `defn'))
[EMAIL PROTECTED]
+dumpdef(`defn1', `defn2')
[EMAIL PROTECTED]:@tabchar{}`builtin(`defn', $@@)'
[EMAIL PROTECTED]:@tabchar{}<defn>
[EMAIL PROTECTED]
+traceon
[EMAIL PROTECTED]
+defn1(`foo')
[EMAIL PROTECTED]: -1- defn1(`foo') -> `builtin(`defn', `foo')'
[EMAIL PROTECTED]: -1- builtin(`defn', `foo') -> ``bar''
[EMAIL PROTECTED]
+defn2(`foo')
[EMAIL PROTECTED]: -1- defn2(`foo') -> ``bar''
[EMAIL PROTECTED]
+traceoff
[EMAIL PROTECTED]: -1- traceoff -> `'
[EMAIL PROTECTED]
+changequote(`[', `]')
[EMAIL PROTECTED]
+defn1([foo])
[EMAIL PROTECTED]:stdin:11: Warning: builtin: undefined builtin ``defn''
[EMAIL PROTECTED]
+defn2([foo])
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
@node M4symbols
@section Getting the defined macro names
