Changes to m4/doc/m4.texinfo,v

[Eric Blake]

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}, @address@hidden)
address@hidden {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
address@hidden 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
address@hidden 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.
+
address@hidden
+$ @kbd{m4 -d}
+undefine(`defn')
address@hidden
+define(`foo', `bar')
address@hidden
+define(`defn1', `builtin(`defn', $@@)')
address@hidden
+define(`defn2', builtin(builtin(`defn', `builtin'), `defn'))
address@hidden
+dumpdef(`defn1', `defn2')
address@hidden:@tabchar{}`builtin(`defn', $@@)'
address@hidden:@tabchar{}<defn>
address@hidden
+traceon
address@hidden
+defn1(`foo')
address@hidden: -1- defn1(`foo') -> `builtin(`defn', `foo')'
address@hidden: -1- builtin(`defn', `foo') -> ``bar''
address@hidden
+defn2(`foo')
address@hidden: -1- defn2(`foo') -> ``bar''
address@hidden
+traceoff
address@hidden: -1- traceoff -> `'
address@hidden
+changequote(`[', `]')
address@hidden
+defn1([foo])
address@hidden:stdin:11: Warning: builtin: undefined builtin ``defn''
address@hidden
+defn2([foo])
address@hidden
address@hidden example
+
 @node M4symbols
 @section Getting the defined macro names