m4-commit
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Changes to m4/doc/m4.texinfo,v


From: Eric Blake
Subject: Changes to m4/doc/m4.texinfo,v
Date: Thu, 31 Aug 2006 03:21:37 +0000

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')
address@hidden:input.m4:1: Warning: index: too few arguments: 1 < 2
address@hidden:stdin:1: Warning: index: too few arguments: 1 < 2
 @result{}0
 index(`abc',)
 @result{}0
 index(`abc', `b', `ignored')
address@hidden:input.m4:3: Warning: index: extra arguments ignored: 3 > 2
address@hidden:stdin:3: Warning: index: extra arguments ignored: 3 > 2
 @result{}1
 @end example
 
@@ -1256,7 +1256,7 @@
 @example
 define(
 ^D
address@hidden:input.m4:1: ERROR: end of file in argument list
address@hidden: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')
address@hidden:input.m4:1: Warning: define: invalid macro name ignored
address@hidden:stdin:1: Warning: define: invalid macro name ignored
 @result{}
 divnum
 @result{}0
@@ -1797,14 +1797,14 @@
 
 @example
 defn(`foo')
address@hidden:input.m4:1: Warning: defn: undefined macro: foo
address@hidden:stdin:1: Warning: defn: undefined macro `foo'
 @result{}
 define(`foo', `a')
 @result{}
 define(`bar', defn(`foo', `divnum'))
address@hidden
address@hidden
 define(`blah', defn(`divnum', `foo'))
address@hidden
address@hidden
 bar
 @result{}a0
 blah
@@ -1856,7 +1856,6 @@
 popdef(`foo')
 @result{}
 foo
address@hidden 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
address@hidden GNU extensions
address@hidden @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
address@hidden GNU extensions
address@hidden @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.
+
address@hidden
+pushdef(`define', `hidden')
address@hidden
+undefine(`undefine')
address@hidden
+define(`foo', `bar')
address@hidden
+foo
address@hidden
+builtin(`define', `foo', `BAR')
address@hidden
+foo
address@hidden
+undefine(`foo')
address@hidden(foo)
+foo
address@hidden
+builtin(`undefine', `foo')
address@hidden
+foo
address@hidden
address@hidden example
+
+The @var{name} argument only matches the original name of the builtin,
+even when the @option{--prefix-builtins} option (or @option{-P},
address@hidden m4}) is in effect.  This is different from @code{indir},
+which only tracks current macro names.
+
address@hidden options: -P
address@hidden
+$ @kbd{m4 -P}
+m4_builtin(`divnum')
address@hidden
+m4_builtin(`m4_divnum')
address@hidden:stdin:2: Warning: m4_builtin: undefined builtin `m4_divnum'
address@hidden
+m4_indir(`divnum')
address@hidden:stdin:3: Warning: m4_indir: undefined macro `divnum'
address@hidden
+m4_indir(`m4_divnum')
address@hidden
address@hidden 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.
+
address@hidden
+builtin
address@hidden
+builtin()
address@hidden:stdin:2: Warning: builtin: undefined builtin `'
address@hidden
+builtin(`builtin')
address@hidden:stdin:3: Warning: builtin: too few arguments: 0 < 1
address@hidden
+builtin(`builtin',)
address@hidden:stdin:4: Warning: builtin: undefined builtin `'
address@hidden
+indir(`index')
address@hidden:stdin:5: Warning: index: too few arguments: 0 < 2
address@hidden
address@hidden example
+
 @node Symbols
 @section Getting the defined macro names
 
 @cindex macro names
address@hidden GNU extensions
-The name of the currently defined macro can be accessed by
address@hidden @acronym{GNU} extensions
+The name of the currently defined macros can be accessed by
 @code{symbols}:
 
address@hidden {Builtin (gnu)} symbols
address@hidden {Builtin (gnu)} symbols (@dots{})
address@hidden {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.
address@hidden deffn
 
 @example
 symbols(`ifndef', `ifdef', `define', `undef')
 @result{}define,ifdef
 @end example
address@hidden 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
address@hidden {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
address@hidden, which test whether a macro is defined or not.  If
address@hidden is defined as a macro, @code{ifdef} expands to
address@hidden:
+
address@hidden {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')
address@hidden:stdin:4: Warning: ifdef: extra arguments ignored: 4 > 3
address@hidden
 @end example
 
 @node Ifelse
@@ -2100,7 +2176,7 @@
 ifelse(`some comments')
 @result{}
 ifelse(`foo', `bar')
address@hidden:input.m4:2: Warning: ifelse: too few arguments: 2 < 3
address@hidden: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.
 
address@hidden FIXME - it would be nice to introduce foreach here, and even
address@hidden give an example like this for finding defined macros that meet
address@hidden a certain pattern (see examples/foreach.m4):
address@hidden define(`quote', ``$@'')
address@hidden foreach(`macro', (quote(symbols)),
address@hidden         `regexp(macro, `.*_.*', ``\&',')')
+
 @node Debugging
 @chapter How to debug macros and input
 
@@ -2823,7 +2906,7 @@
 define(`test.1', `TEST ONE')
 @result{}
 __file__
address@hidden
address@hidden
 changesyntax(`O_', `W.')
 @result{}
 __file__
@@ -3092,7 +3175,7 @@
 @example
 include(`n')
 @result{}
address@hidden:input.m4:1: include: cannot open `n': No such file or directory
address@hidden: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')
address@hidden:input.m4:7: eval: bad expression: foo / 6
address@hidden:stdin:7: eval: bad expression: foo / 6
 @result{}
 eval(foo/6)
 @result{}111
@@ -4317,7 +4400,7 @@
 @example
 errprint(`m4:'__file__:__line__: `Input error
 ')
address@hidden:input.m4:1: Input error
address@hidden:stdin:1: Input error
 @result{}
 @end example
 @end deffn
@@ -4341,7 +4424,7 @@
 ')m4exit(1)')
 @result{}
 fatal_error(`This is a BAD one, buster')
address@hidden:input.m4:4: fatal error: This is a BAD one, buster
address@hidden: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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]