[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: RFC: rename symbols to m4symbols
From: |
Eric Blake |
Subject: |
Re: RFC: rename symbols to m4symbols |
Date: |
Mon, 18 Sep 2006 22:00:35 -0600 |
User-agent: |
Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.0.7) Gecko/20060909 Thunderbird/1.5.0.7 Mnenhy/0.7.4.666 |
Hi Gary,
> Hi Eric!
>
> On 18 Sep 2006, at 14:09, Eric Blake wrote:
>>> "symbols" is an English word, but was added to m4-1.4o as a macro that
>>> takes 0 arguments (even worse, the 1.4o manual documented the new macro,
>>> but NEWS did not). This has the potential to break preprocessing of
>>> English text that used to work with m4 1.4.x, when someone upgrades and
>>> makes no changes to their command line. I propose renaming the macro to
>>> "m4symbols" (and we should probably document a policy that any future
>>> macro added in the gnu module that take 0 arguments either be in the "m4"
>>> or "__" namespace, such as the __program__ macro added in m4 1.4.6).
>>> m4sugar currently handles this case by mapping symbols to "m4_symbols",
>>> consistent with the other remappings it handles, so a rename visible
>>> in m4
>>> 2.0 would slightly impact autoconf; there are other macros that m4sugar
>>> still needs to pick up from CVS M4, such as changeresyntax.
>
> Agreed. "symbols" has only been present in alpha releases thus far, so
> I think changing it now rather than feeling the pain of having not done it
> later is the best course of action. Besides, one or two of the GNU M4
> maintainers also have a commit bit for Autoconf ;-)
OK, here's the M4 patch, and I'll follow up with an autoconf patch in the
near future.
>
> I suppose that it makes sense to do that with the "modules" builtin by
> virtue of your english words with 0 arguments rule above, but I see no
> compelling reason to change load or unload when they are perfectly in
> keeping with the style of many SUSv3 builtin names.
>
OK, since load/unload were already blind, they did not have the problem
(English text has the nice property, when properly puncutated :), that an
m4 macro is distinguishable from correct grammar). So after changing
symbols and modules, the only English word left is divert, which
POSIX/SUSv3 require to behave that way (and the manual documents accordingly).
2006-09-18 Eric Blake <address@hidden>
* modules/load.c (modules): Rename to...
(m4modules): ...this, since it is an English word with 0
arguments.
* modules/gnu.c (symbols, m4symbols): Likewise.
* doc/m4.texinfo (Listing Modules): Rename to...
(M4modules): ...this.
(Symbols): Rename to...
(M4symbols): ...this.
(Load, Foreach, Trace, Answers): Update to new spellings.
* NEWS: Document this.
--
Life is short - so eat dessert first!
Eric Blake address@hidden
Hi Gary,
> Hi Eric!
>
> On 18 Sep 2006, at 14:09, Eric Blake wrote:
>>> "symbols" is an English word, but was added to m4-1.4o as a macro that
>>> takes 0 arguments (even worse, the 1.4o manual documented the new macro,
>>> but NEWS did not). This has the potential to break preprocessing of
>>> English text that used to work with m4 1.4.x, when someone upgrades and
>>> makes no changes to their command line. I propose renaming the macro to
>>> "m4symbols" (and we should probably document a policy that any future
>>> macro added in the gnu module that take 0 arguments either be in the "m4"
>>> or "__" namespace, such as the __program__ macro added in m4 1.4.6).
>>> m4sugar currently handles this case by mapping symbols to "m4_symbols",
>>> consistent with the other remappings it handles, so a rename visible
>>> in m4
>>> 2.0 would slightly impact autoconf; there are other macros that m4sugar
>>> still needs to pick up from CVS M4, such as changeresyntax.
>
> Agreed. "symbols" has only been present in alpha releases thus far, so
> I think changing it now rather than feeling the pain of having not done it
> later is the best course of action. Besides, one or two of the GNU M4
> maintainers also have a commit bit for Autoconf ;-)
OK, here's the M4 patch, and I'll follow up with an autoconf patch in the
near future.
>
> I suppose that it makes sense to do that with the "modules" builtin by
> virtue of your english words with 0 arguments rule above, but I see no
> compelling reason to change load or unload when they are perfectly in
> keeping with the style of many SUSv3 builtin names.
>
OK, since load/unload were already blind, they did not have the problem
(English text has the nice property, when properly puncutated :), that an
m4 macro is distinguishable from correct grammar). So after changing
symbols and modules, the only English word left is divert, which
POSIX/SUSv3 require to behave that way (and the manual documents accordingly).
2006-09-18 Eric Blake <address@hidden>
* modules/load.c (modules): Rename to...
(m4modules): ...this, since it is an English word with 0
arguments.
* modules/gnu.c (symbols, m4symbols): Likewise.
* doc/m4.texinfo (Listing Modules): Rename to...
(M4modules): ...this.
(Symbols): Rename to...
(M4symbols): ...this.
(Load, Foreach, Trace, Answers): Update to new spellings.
* NEWS: Document this.
--
Life is short - so eat dessert first!
Eric Blake address@hidden
Index: HACKING
===================================================================
RCS file: /sources/m4/m4/HACKING,v
retrieving revision 1.3
diff -u -p -r1.3 HACKING
--- HACKING 22 Aug 2006 22:36:28 -0000 1.3
+++ HACKING 19 Sep 2006 03:45:48 -0000
@@ -26,6 +26,10 @@ and is not part of a release distributio
* Changes with user-visible effects must be mentioned in NEWS.
+* New macros must be blind, or else prefixed with `m4' or `__', in
+ order to minimize backward compatibility issues with previous
+ releases of M4 when processing English text.
+
* GNU Coding Standards should be followed:
http://www.gnu.org/prep/standards/
Additionally, while GNU M4 is not yet POSIX compliant, we are trying
Index: NEWS
===================================================================
RCS file: /sources/m4/m4/NEWS,v
retrieving revision 1.14
diff -u -p -r1.14 NEWS
--- NEWS 18 Sep 2006 13:16:43 -0000 1.14
+++ NEWS 19 Sep 2006 03:45:48 -0000
@@ -75,6 +75,13 @@ promoted to 2.0.
affects only debugmode and traceon output; we should probably deprecate
the --error-output, and rename it something like --trace-output.
+* The builtins `modules' and `symbols', introduced in previous betas,
+ have been renamed `m4modules' and `m4symbols', in order to minimize
+ problems when upgrading from 1.4.x and processing English text. To
+ prevent future problems, any future macro added as a GNU extension will
+ either be blind (ie. be unrecognized without arguments), or begin with
+ the prefix `m4' or `__'.
+
* FIXME: `m4wrap' semantics need an update to FIFO.
* FIXME: include the (long) list of changes in 1.4.x that were not already
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.45
diff -u -p -r1.45 m4.texinfo
--- doc/m4.texinfo 18 Sep 2006 13:16:43 -0000 1.45
+++ doc/m4.texinfo 19 Sep 2006 03:45:49 -0000
@@ -177,7 +177,7 @@ How to define new macros
* Indir:: Indirect call of macros
* Builtin:: Indirect call of builtins
-* Symbols:: Getting the defined macro names
+* M4symbols:: Getting the defined macro names
Conditionals, loops, and recursion
@@ -217,7 +217,7 @@ Diverting and undiverting output
Extending M4 with dynamic runtime modules
-* Listing Modules:: Listing loaded modules
+* M4modules:: Listing loaded modules
* Load:: Loading additional modules
* Unload:: Removing loaded modules
* Standard Modules:: Standard bundled modules
@@ -1360,7 +1360,7 @@ value, and bring back the original value
* Indir:: Indirect call of macros
* Builtin:: Indirect call of builtins
-* Symbols:: Getting the defined macro names
+* M4symbols:: Getting the defined macro names
@end menu
@node Define
@@ -2128,26 +2128,26 @@ indir(`index')
@result{}0
@end example
address@hidden Symbols
address@hidden M4symbols
@section Getting the defined macro names
@cindex macro names
@cindex @acronym{GNU} extensions
The name of the currently defined macros can be accessed by
address@hidden:
address@hidden:
address@hidden {Builtin (gnu)} symbols (@address@hidden)
-Without arguments, @samp{symbols} expands to a sorted list of quoted
address@hidden {Builtin (gnu)} m4symbols (@address@hidden)
+Without arguments, @code{m4symbols} expands to a sorted list of quoted
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
+When given arguments, @code{m4symbols} returns the sorted subset of the
@var{names} currently defined, and silently ignores the rest.
@end deffn
@example
-symbols(`ifndef', `ifdef', `define', `undef')
+m4symbols(`ifndef', `ifdef', `define', `undef')
@result{}define,ifdef
@end example
@@ -2514,12 +2514,13 @@ define(`_foreach',
`$3')')')dnl
define(`dquote', ``$@@'')
@result{}
-foreach(`macro', (dquote(symbols)), `regexp(macro, `.*if.*', ``\&',')')
+foreach(`macro', (dquote(m4symbols)),
+ `regexp(macro, `.*if.*', ``\&',')')
@result{}ifdef,ifelse,shift,
@end example
The example had to use a helper @code{quote} to ensure that the output
-from @code{symbols} was double quoted; without it, the macro would have
+from @code{m4symbols} was double quoted; without it, the macro would have
gone into an infinite loop thanks to macros being reinvoked during the
rescanning. Choosing @samp{()} as the list delimiters made this
example rather awkward in terms of proper quoting. (A different
@@ -2756,18 +2757,18 @@ However, @acronym{GNU} M4 1.4.7 and earl
semantics, where @code{traceon} without arguments only affected symbols
that were defined at that moment, and @code{traceoff} without arguments
stopped all tracing, even when tracing was requested by macro name. The
-addition of the macro @code{symbols} (@pxref{Symbols}) in 2.0 makes it
+addition of the macro @code{m4symbols} (@pxref{M4symbols}) in 2.0 makes it
possible to write a file that approximates the older semantics
regardless of which version of @acronym{GNU} M4 is in use.
@comment options: -d-V
@example
$ @kbd{m4}
-ifdef(`symbols',
- `define(`traceon', `ifelse(`$#', `0', `builtin(`traceon', symbols)',
+ifdef(`m4symbols',
+ `define(`traceon', `ifelse(`$#', `0', `builtin(`traceon', m4symbols)',
`builtin(`traceon', $@@)')')dnl
define(`traceoff', `ifelse(`$#', `0',
- `builtin(`traceoff')builtin(`traceoff', symbols)',
+ `builtin(`traceoff')builtin(`traceoff', m4symbols)',
`builtin(`traceoff', $@@)')')')dnl
define(`a', `1')
@result{}
@@ -2792,7 +2793,7 @@ traceoff # stops tracing b, even though
@error{}m4trace: -1- traceoff
@error{}m4trace: -1- ifelse
@error{}m4trace: -1- builtin
address@hidden: -2- symbols
address@hidden: -2- m4symbols
@error{}m4trace: -1- builtin
@result{} # stops tracing b, even though it was traced by name
a b
@@ -3133,7 +3134,7 @@ changecom
@cindex regular expression syntax, changing
@cindex GNU extensions
@deffn {Builtin (gnu)} changeresyntax (@var{resyntax})
-By default, the @sc{gnu} extensions @code{patsubst}, @code{regexp} and
+By default, the @acronym{GNU} extensions @code{patsubst}, @code{regexp} and
more recently @code{renamesyms} continue to use emacs style regular
expression syntax (@pxref{Regular expression syntax}).
@@ -3920,7 +3921,7 @@ should try to see if you can find it and
@chapter Extending M4 with dynamic runtime modules
@cindex modules
address@hidden m4-1.4.x had a monolithic architecture. All of its
address@hidden M4 1.4.x had a monolithic architecture. All of its
functionality was contained in a single binary, and additional macros
could be added only by writing more code in the M4 language, or at the
extreme by hacking the sources and recompiling the whole thing to make
@@ -3991,7 +3992,7 @@ setenv(`PATH', `/sbin:/bin:/usr/sbin:/us
Also, at build time, you can choose which modules to build into
the core (so that they will be available without dynamic loading).
-SUSv3 M4 functionality is contained in the module @samp{m4}, @sc{gnu}
+SUSv3 M4 functionality is contained in the module @samp{m4}, @acronym{GNU}
extensions in the module @samp{gnu}, the @code{load} builtin in the
module @samp{load} and so on.
@@ -4000,47 +4001,48 @@ preloaded into the installed M4 binary,
a @emph{thinner} binary minus GNU extensions, for example, by
configuring the distribution with @samp{./configure
--with-modules=m4}. For a binary built with that option to understand
-code that uses @sc{gnu} extensions, you must then run @samp{m4
+code that uses @acronym{GNU} extensions, you must then run @samp{m4
--load-module=gnu}. It is also possible to build a @emph{fatter}
binary with additional modules preloaded: adding, say, the @code{load}
builtin using @samp{./configure --with-modules="m4 gnu load"}.
-GNU M4 now has a facility for defining additional builtins without
address@hidden M4 now has a facility for defining additional builtins without
recompiling the sources. In actual fact, all of the builtins provided
-by GNU M4 are loaded from such modules. All of the builtin
+by @acronym{GNU} M4 are loaded from such modules. All of the builtin
descriptions in this manual are annotated with the module from which
they are loaded -- mostly from the module @samp{m4}.
-When you start GNU M4, the modules @samp{m4} and @samp{gnu} are
+When you start @acronym{GNU} M4, the modules @samp{m4} and @samp{gnu} are
loaded by default. If you supply the @option{-G} option at startup, the
module @samp{traditional} is loaded instead of @samp{gnu}.
@xref{Compatibility}, for more details on the differences between these
two modes of startup.
@menu
-* Listing Modules:: Listing loaded modules
+* M4modules:: Listing loaded modules
* Load:: Loading additional modules
* Unload:: Removing loaded modules
* Standard Modules:: Standard bundled modules
@end menu
address@hidden Listing Modules
address@hidden M4modules
@section Listing loaded modules
address@hidden {Builtin (load)} modules
address@hidden expands to an ordered list of currently loaded modules,
address@hidden {Builtin (load)} m4modules
+Expands to a quoted ordered list of currently loaded modules,
with the most recently loaded module at the front of the list. Loading
a module multiple times will not affect the order of this list, the
position depends on when the module was @emph{first} loaded.
@end deffn
-For example, if GNU @code{m4} is started with the @option{-mload}
-option to load the module @samp{load} and make this builtin available,
address@hidden will yield the following:
+For example, if @acronym{GNU} @code{m4} is started with the
address@hidden option to load the module @samp{load} and make this
+builtin available, @code{m4modules} will yield the following:
address@hidden ignore
address@hidden options: -m load
@example
-modules
+$ @kbd{m4 -m load}
+m4modules
@result{}load,gnu,m4
@end example
@@ -4062,11 +4064,11 @@ option.
@comment ignore
@example
-modules
+m4modules
@result{}load,gnu,m4
load(`mymodule')
@result{}
-modules
+m4modules
@result{}mymodule,load,gnu,m4
@end example
@@ -4205,7 +4207,7 @@ index(`gnus, gnats, and armadillos', `da
@ovar{replacement}, @ovar{resyntax})
Searching for regular expressions is done with the builtin
@code{regexp}, which searches for @var{regexp} in @var{string}. The
-syntax of regular expressions is similar to that of Perl, @sc{gnu} Awk
+syntax of regular expressions is similar to that of Perl, @acronym{GNU} Awk
and Egrep: so called ``Extended Regular Expression''.
If @var{replacement} is omitted, @code{regexp} expands to the index of
@@ -5098,7 +5100,7 @@ strings.
@item R @var{length} @key{NL} @var{string} @key{NL}
Sets the default regexp syntax, where @var{string} encodes one of the
-regular expression syntaxes supported by @sc{gnu} M4.
+regular expression syntaxes supported by @acronym{GNU} M4.
@xref{Changeresyntax}, for more details.
@item M @var{length} @key{NL} @var{string} @key{NL}
@@ -5207,9 +5209,9 @@ by the @code{regexp} (@pxref{Regexp}) an
@item
The syntax of regular expressions in M4 has never clearly formalized.
While Open BSD M4 uses extended regular expressions for @code{regexp}
-and @code{patsubst}, @sc{gnu} M4 uses basic regular expression. Use
+and @code{patsubst}, @acronym{GNU} M4 uses basic regular expression. Use
@code{changeresyntax} (@pxref{Changeresyntax}) to change the regular
-expression syntax used by @sc{gnu} M4.
+expression syntax used by @acronym{GNU} M4.
@item
The output of shell commands can be read into @code{m4} with
@@ -5387,7 +5389,7 @@ define(`_foreach',
`$3')')')dnl
define(`dquote', ``$@@'')
@result{}
-foreach(`macro', (dquote(symbols)), `regexp(macro, `shift', `\&')')
+foreach(`macro', (dquote(m4symbols)), `regexp(macro, `shift', `\&')')
@result{}shift
traceon(`shift')
@result{}
@@ -5414,7 +5416,7 @@ each iteration operates on a shorter lis
long lists. Another way of viewing these semantics is that the
outermost quotes delineates the list, then each element of the list must
be quoted as though the list delimiters were not present. Notice the
-difference when iterating over @code{symbols}; we must use
+difference when iterating over @code{m4symbols}; we must use
@code{dquote_elt} instead of @code{dquote} to get the necessary quoting.
@comment FIXME - include(foreach.m4),include(quote.m4)
@@ -5432,7 +5434,8 @@ define(`_foreach',
`define(`$1',
`_arg1($2)')$3`'_foreach(`$1', _rest($2),
`$3')')')dnl
-foreach(`macro', `dquote_elt(symbols)', `regexp(macro, `shift', `\&')')
+foreach(`macro', `dquote_elt(m4symbols)',
+ `regexp(macro, `shift', `\&')')
@result{}shift
traceon(`shift')
@result{}
Index: modules/gnu.c
===================================================================
RCS file: /sources/m4/m4/modules/gnu.c,v
retrieving revision 1.55
diff -u -p -r1.55 gnu.c
--- modules/gnu.c 15 Sep 2006 03:37:54 -0000 1.55
+++ modules/gnu.c 19 Sep 2006 03:45:49 -0000
@@ -59,7 +59,7 @@
BUILTIN (patsubst, false, true, true, 2, 4 ) \
BUILTIN (regexp, false, true, true, 2, 4 ) \
BUILTIN (renamesyms, false, true, false, 2, 3 ) \
- BUILTIN (symbols, false, false, false, 0, -1 ) \
+ BUILTIN (m4symbols, false, false, false, 0, -1 ) \
BUILTIN (syncoutput, false, true, false, 1, 1 ) \
@@ -691,13 +691,13 @@ M4BUILTIN_HANDLER (renamesyms)
}
-/* Implementation of "symbols". It builds up a table of pointers to
+/* Implementation of "m4symbols". It builds up a table of pointers to
symbols, sorts it and ships out the symbol names. */
/**
- * symbols([...])
+ * m4symbols([...])
**/
-M4BUILTIN_HANDLER (symbols)
+M4BUILTIN_HANDLER (m4symbols)
{
M4_MODULE_IMPORT (m4, m4_dump_symbols);
Index: modules/load.c
===================================================================
RCS file: /sources/m4/m4/modules/load.c,v
retrieving revision 1.18
diff -u -p -r1.18 load.c
--- modules/load.c 25 Aug 2006 22:06:42 -0000 1.18
+++ modules/load.c 19 Sep 2006 03:45:49 -0000
@@ -34,7 +34,7 @@
function macros blind side minargs maxargs */
#define builtin_functions \
- BUILTIN (modules, false, false, false, 0, 0 ) \
+ BUILTIN (m4modules, false, false, false, 0, 0 ) \
BUILTIN (load, false, true, false, 1, 1 ) \
BUILTIN (unload, false, true, false, 1, 1 ) \
@@ -87,9 +87,9 @@ M4INIT_HANDLER (load)
of the m4 builtins declared in `m4_builtin_table[]' above. */
/**
- * modules()
+ * m4modules()
**/
-M4BUILTIN_HANDLER (modules)
+M4BUILTIN_HANDLER (m4modules)
{
/* The expansion of this builtin is a comma separated list of
loaded modules. */