CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/08/30 04:25:42
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -b -r1.36 -r1.37
--- doc/m4.texinfo 25 Aug 2006 22:06:41 -0000 1.36
+++ doc/m4.texinfo 30 Aug 2006 04:25:42 -0000 1.37
@@ -133,7 +133,7 @@
* Frozen files:: Fast loading of frozen state
* Compatibility:: Compatibility with other versions of m4
-* Experiments:: Experimental features in GNU m4
+* Experiments:: Experimental features in GNU M4
* Answers:: Correct version of some examples
* Copying This Manual:: How to make copies of this manual
* Indices:: Indices of concepts and macros
@@ -1274,7 +1274,11 @@
foo(() (`(') `(')
@end example
-is a macro call, with one argument, whose value is @samp{()@w{ }(()@w{ }(}.
[EMAIL PROTECTED]
+is a macro call, with one argument, whose value is @samp{() (() (}.
+Commas separate arguments, except when they occur inside quotes,
+comments, or unquoted parentheses, @xref{Pseudo Arguments}, for
+examples.
It is common practice to quote all arguments to macros, unless you are
sure you want the arguments expanded. Thus, in the above
@@ -1285,9 +1289,14 @@
foo(`() (() (')
@end example
-It is, however, in certain cases necessary to leave out quotes for some
-arguments, and there is nothing wrong in doing it. It just makes life a
-bit harder, if you are not careful.
+It is, however, in certain cases necessary or convenient to leave out
+quotes for some arguments, and there is nothing wrong in doing it. It
+just makes life a bit harder, if you are not careful. For consistency,
+this manual follows the rule of thumb that each layer of parentheses
+introduces another layer of single quoting, except when showing the
+consequences of quoting rules. This is done even when the quoted string
+cannot be a macro, such as with integers when you have not changed the
+syntax via @code{changesyntax} (@pxref{Changesyntax}).
@node Macro expansion
@section Macro expansion
@@ -1303,9 +1312,11 @@
Taking a very simple example, if @var{foo} expands to @samp{bar}, and
@var{bar} expands to @samp{Hello world}, the input
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED] options: -Dbar='Hello world' -Dfoo=bar
@example
+$ @kbd{m4 -Dbar="Hello world" -Dfoo=bar}
foo
[EMAIL PROTECTED] world
@end example
@noindent
@@ -1318,8 +1329,8 @@
@cindex macros, how to define new
@cindex defining new macros
Macros can be defined, redefined and deleted in several different ways.
-Also, it is possible to redefine a macro, without losing a previous
-value, which can be brought back at a later time.
+Also, it is possible to redefine a macro without losing a previous
+value, and bring back the original value at a later time.
@menu
* Define:: Defining a new macro
@@ -1339,14 +1350,14 @@
@node Define
@section Defining a macro
[EMAIL PROTECTED] {Builtin (m4)} define (@var{name}, @w{opt @var{expansion})}
The normal way to define or redefine macros is to use the builtin
[EMAIL PROTECTED], which defines a new macro, @var{name}, to expand to
[EMAIL PROTECTED] If @var{expansion} is not given, it is taken to be
-empty.
[EMAIL PROTECTED]:
-The expansion of @code{define} is void.
[EMAIL PROTECTED] {Builtin (m4)} define (@var{name}, @ovar{expansion})
+Defines @var{name} to expand to @var{expansion}. If
[EMAIL PROTECTED] is not given, it is taken to be empty.
+The expansion of @code{define} is void.
The macro @code{define} is recognized only with parameters.
@end deffn
@@ -1365,18 +1376,40 @@
the output. This can be avoided by use of the macro @code{dnl}.
@xref{Dnl}, for details.
[EMAIL PROTECTED] GNU extensions
-GNU @code{m4} normally replaces only the @emph{topmost} definition of a
-macro if it has several definitions from @code{pushdef}.
[EMAIL PROTECTED], , Temporarily redefining macros}, for an explanation of
[EMAIL PROTECTED] Some other UNIX implementations replace all definitions
-of a macro with @code{define}.
[EMAIL PROTECTED], , Other incompatibilities}, for more details.
-
-The first argument to @code{define} does not have to be a simple word.
-It can be any text string. A macro with a non standard name cannot be
-invoked in the normal way, as the name is not recognised. It can only
-be referenced by the builtins @ref{Indir} and @ref{Defn}.
+The first argument to @code{define} should be quoted; otherwise, if the
+macro is already defined, you will be defining a different macro. This
+example shows the problems with underquoting, since we did not want to
+redefine @code{one}:
+
[EMAIL PROTECTED]
+define(foo, one)
[EMAIL PROTECTED]
+define(foo, two)
[EMAIL PROTECTED]
+one
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] @acronym{GNU} extensions
[EMAIL PROTECTED] @code{m4} normally replaces only the @emph{topmost}
+definition of a macro if it has several definitions from @code{pushdef}
+(@pxref{Pushdef}). Some other implementations of @code{m4} replace all
+definitions of a macro with @code{define}. @xref{Incompatibilities},
+for more details.
[EMAIL PROTECTED] FIXME - See Austin group XCU ERN 118; this is considered
[EMAIL PROTECTED] ambiguous in the current version of POSIX. The best thing to
[EMAIL PROTECTED] do here would probably be keep GNU semantics of popdef/pushdef
[EMAIL PROTECTED] in the m4 module unconditionally, then have a shadow builtin
in
[EMAIL PROTECTED] the traditional module that does the undefine/pushdef
[EMAIL PROTECTED] semantics, rather than our current keying off of
[EMAIL PROTECTED] POSIXLY_CORRECT within the m4 module.
+
+As a @acronym{GNU} extension, the first argument to @code{define} does
+not have to be a simple word.
+It can be any text string, even the empty string. A macro with a
+non-standard name cannot be invoked in the normal way, as the name is
+not recognized. It can only be referenced by the builtins @ref{Indir}
+and @ref{Defn}.
@cindex arrays
Arrays and associative arrays can be simulated by using this trick.
@@ -1386,11 +1419,11 @@
@result{}
define(`array_set', `define(format(``array[%d]'', `$1'), `$2')')
@result{}
-array_set(4, `array element no. 4')
+array_set(`4', `array element no. 4')
@result{}
-array_set(17, `array element no. 17')
+array_set(`17', `array element no. 17')
@result{}
-array(4)
+array(`4')
@result{}array element no. 4
array(eval(`10 + 7'))
@result{}array element no. 17
@@ -1405,7 +1438,9 @@
@cindex Arguments to macros
Macros can have arguments. The @var{n}th argument is denoted by
@code{$n} in the expansion text, and is replaced by the @var{n}th actual
-argument, when the macro is expanded. Here is a example of a macro with
+argument, when the macro is expanded. Replacement of arguments happens
+before rescanning, regardless of how many nesting levels of quoting
+appear in the expansion. Here is a example of a macro with
two arguments. It simply exchanges the order of the two arguments.
@example
@@ -1428,14 +1463,22 @@
@end example
@xref{Quoting Arguments}, for an explanation of the double quotes.
+(You should try and improve this example so that clients of @code{exch}
+do not have to double quote. @pxref{Answers})
[EMAIL PROTECTED] GNU extensions
-GNU @code{m4} allows the number following the @samp{$} to consist of one
[EMAIL PROTECTED] @acronym{GNU} extensions
[EMAIL PROTECTED] @code{m4} allows the number following the @samp{$} to
+consist of one
or more digits, allowing macros to have any number of arguments. This
is not so in UNIX implementations of @code{m4}, which only recognize
one digit.
[EMAIL PROTECTED] FIXME - See Austin group XCU ERN 111. This is controversial,
[EMAIL PROTECTED] and perhaps we should consider an alternate syntax ${10}
[EMAIL PROTECTED] and phase out $10, for better POSIX compliance. There are
[EMAIL PROTECTED] existing m4 scripts that depend on $10 being the first
[EMAIL PROTECTED] parameter concatenated with 0, not the tenth argument.
-As a special case, the zero'th argument, @code{$0}, is always the name
+As a special case, the zeroth argument, @code{$0}, is always the name
of the macro being expanded.
@example
@@ -1479,8 +1522,15 @@
@result{}0
nargs()
@result{}1
-nargs(arg1, arg2, arg3)
+nargs(`arg1', `arg2', `arg3')
@result{}3
+nargs(`commas can be quoted, like this')
[EMAIL PROTECTED]
+nargs(arg1#inside comments, commas do not separate arguments
+still arg1)
[EMAIL PROTECTED]
+nargs((unquoted parentheses, like this, group arguments))
[EMAIL PROTECTED]
@end example
The notation @code{$*} can be used in the expansion text to denote all
@@ -1516,12 +1566,35 @@
@result{}
echo1(foo)
@result{}This is macro This is macro foo..
+echo1(`foo')
[EMAIL PROTECTED] is macro foo.
echo2(foo)
@result{}This is macro foo.
+echo2(`foo')
[EMAIL PROTECTED]
@end example
@noindent
[EMAIL PROTECTED], if you do not understand this.
[EMAIL PROTECTED], if you do not understand this. As another example of the
+difference, remember that comments encountered in arguments are passed
+untouched to the macro, and that quoting disables comments.
+
[EMAIL PROTECTED]
+define(`echo1', `$*')
[EMAIL PROTECTED]
+define(`echo2', `$@')
[EMAIL PROTECTED]
+define(`foo', `bar')
[EMAIL PROTECTED]
+echo1(#foo'foo
+foo)
[EMAIL PROTECTED]'foo
[EMAIL PROTECTED]
+echo2(#foo'foo
+foo)
[EMAIL PROTECTED]
[EMAIL PROTECTED]'
[EMAIL PROTECTED] example
A @samp{$} sign in the expansion text, that is not followed by anything
@code{m4} understands, is simply copied to the macro expansion, as any
@@ -1534,9 +1607,34 @@
@result{}$$$ hello $$$
@end example
-If you want a macro to expand to something like @samp{$12}, put a pair
-of quotes after the @code{$}. This will prevent @code{m4} from
-interpreting the @code{$} sign as a reference to an argument.
+If you want a macro to expand to something like @samp{$12}, the
+judicious use of nested quoting can put a safe character between the
[EMAIL PROTECTED] and the next character, relying on the rescanning to remove
the
+nested quote. This will prevent @code{m4} from interpreting the
[EMAIL PROTECTED] sign as a reference to an argument.
+
[EMAIL PROTECTED]
+define(`foo', `no nested quote: $1')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] nested quote: arg
+define(`foo', `nested quote around $: `$'1')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] quote around $: $1
+define(`foo', `nested empty quote after $: $`'1')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] empty quote after $: $1
+define(`foo', `nested quote around next character: $`1'')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] quote around next character: $1
+define(`foo', `nested quote around both: `$1'')
[EMAIL PROTECTED]
+foo(`arg')
[EMAIL PROTECTED] quote around both: arg
[EMAIL PROTECTED] example
@node Undefine
@section Deleting a macro
@@ -4555,7 +4653,7 @@
@node Experiments
[EMAIL PROTECTED] Experimental features in GNU m4
[EMAIL PROTECTED] Experimental features in GNU M4
Certain features of GNU @code{m4} are experimental.
