Changes to m4/doc/m4.texinfo,v

[Gary V. Vaughan]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Gary V. Vaughan <gary>  06/07/13 23:35:16

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -b -r1.23 -r1.24
--- doc/m4.texinfo      5 Jul 2006 20:54:15 -0000       1.23
+++ doc/m4.texinfo      13 Jul 2006 23:35:15 -0000      1.24
@@ -140,6 +140,7 @@
 * Other tokens::                Other kinds of input tokens
 * Comments::                    Comments in m4 input
 * Input processing::            How m4 copies input to output
+* Regular expression syntax::  How m4 interprets regular expressions
 
 How to invoke macros
 
@@ -157,7 +158,7 @@
 * Undefine::                    Deleting a macro
 * Defn::                        Renaming macros
 * Pushdef::                     Temporarily redefining macros
-* Erenamesyms and Renamesyms::  Renaming macros with regular expressions
+* Renamesyms::                  Renaming macros with regular expressions
 
 * Indir::                       Indirect call of macros
 * Builtin::                     Indirect call of builtins
@@ -182,6 +183,7 @@
 * Dnl::                         Deleting whitespace in input
 * Changequote::                 Changing the quote characters
 * Changecom::                   Changing the comment delimiters
+* Changeresyntax::              Changing the regular expression syntax
 * Changesyntax::                Changing the lexical structure of the input
 * M4wrap::                      Saving input until end of input
 
@@ -208,10 +210,10 @@
 
 * Len::                         Calculating length of strings
 * Index::                       Searching for substrings
-* Eregexp and Regexp::          Searching for regular expressions
+* Regexp::                      Searching for regular expressions
 * Substr::                      Extracting substrings
 * Translit::                    Translating characters
-* Epatsubst and Patsubst::      Substituting text by regular expression
+* Patsubst::                    Substituting text by regular expression
 * Format::                      Formatting strings (printf-like)
 
 Macros for doing arithmetic
@@ -392,6 +394,13 @@
 @samp{m4_define} instead of @samp{define}, and @samp{m4___file__}
 instead of @samp{__file__}.
 
address@hidden -r @var{RESYNTAX-SPEC}
address@hidden address@hidden
+Set the regular expression syntax according to @var{RESYNTAX-SPEC}.
+When this option is not given, @sc{gnu} M4 uses emacs compatible
+regular expressions.  @xref{Changeresyntax}, for more details on the
+format and meaning of @var{RESYNTAX-SPEC}.
+
 @item -M @var{DIRECTORY}
 @itemx address@hidden
 Specify an alternate @var{DIRECTORY} to search for modules.  This option
@@ -603,7 +612,7 @@
 call of the macro will be shown, giving descriptive names to the
 arguments, e.g.,
 
address@hidden {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @w{opt 
@var{replacement})}
address@hidden {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @w{opt 
@var{replacement},} @w{opt @var{resyntax})}
 Description of @samp{regexp}.
 @end deffn
 
@@ -649,6 +658,7 @@
 * Other tokens::                Other kinds of input tokens
 * Comments::                    Comments in m4 input
 * Input processing::            How m4 copies input to output
+* Regular expression syntax::  How m4 interprets regular expressions
 @end menu
 
 @node Names
@@ -771,6 +781,11 @@
 This process continues until there are no more macro calls to expand and
 all the input has been consumed.
 
address@hidden Regular expression syntax
address@hidden Regular Expression Syntax
+
address@hidden regexprops-generic.texi
+
 @node Macros
 @chapter How to invoke macros
 
@@ -1024,7 +1039,7 @@
 * Undefine::                    Deleting a macro
 * Defn::                        Renaming macros
 * Pushdef::                     Temporarily redefining macros
-* Erenamesyms and Renamesyms::  Renaming macros with regular expressions
+* Renamesyms::                  Renaming macros with regular expressions
 
 * Indir::                       Indirect call of macros
 * Builtin::                     Indirect call of builtins
@@ -1408,18 +1423,23 @@
 It is possible to temporarily redefine a builtin with @code{pushdef}
 and @code{defn}.
 
address@hidden Erenamesyms and Renamesyms
address@hidden Renamesyms
 @section Renaming macros with regular expressions
 
 @cindex regular expressions
 @cindex macros, how to rename
 @cindex renaming macros
 @cindex GNU extensions
address@hidden {Builtin (gnu)} erenamesyms (@var{regexp}, @var{replacement})
-Global renaming of macros is done by @code{erenamesyms}, which selects
address@hidden {Builtin (gnu)} renamesyms (@var{regexp}, @var{replacement}, 
@w{opt @var{resyntax})}
+Global renaming of macros is done by @code{renamesyms}, which selects
 all macros with names that match @var{regexp}, and renames each match
 according to @var{replacement}.
 
+If @var{resyntax} is given, the particular flavor of regular
+expression understood with respect to @var{regexp} can be changed from
+the current default.  @xref{Changeresyntax}, for details of the values
+that can be given for this argument.
+
 A macro that does not have a name that matches @var{regexp} is left
 with its original name.  If only part of the name matches, any part of
 the name that is not covered by @var{regexp} is copied to the
@@ -1435,37 +1455,35 @@
 @var{regexp}, and @samp{\&} being the text matched by the entire
 regular expression.
 
-The builtin macro @code{erenamesyms} is recognized only when given
+The builtin macro @code{renamesyms} is recognized only when given
 arguments.
 @end deffn
 
 Here is an example that performs the same renaming as the
 @option{--prefix-builtins} option.  Where @option{--prefix-builtins}
-only renames M4 builtin macros, @code{erenamesyms} will rename any
+only renames M4 builtin macros, @code{renamesyms} will rename any
 macros that match when it runs, including text macros.
 
 @example
-erenamesyms(`^.*$', `m4_\&')
+renamesyms(`^.*$', `m4_\&')
 @result{}
 @end example
 
-Here is a more realistic example that performs a similar renaming on
-macros with lowercase names, except that it ignores macros with names
-that begin with @samp{_}, and avoids creating macros with names that
-begin with @samp{m4_m4}.
+If @var{resyntax} is given, @var{regexp} must be given according to
+the syntax chosen, though the default regular expression syntax
+remains unchanged for other invocations.  Here is a more realistic
+example that performs a similar renaming on macros with lowercase
+names, except that it ignores macros with names that begin with
address@hidden, and avoids creating macros with names that begin with
address@hidden
 
 @example
-erenamesyms(`^[^_]\w*$', `m4_\&')
+renamesyms(`^[^_]\w*$', `m4_\&')
 @result{}
-m4_erenamesyms(`^m4_m4(\w*)$', `m4_\1')
+m4_renamesyms(`^m4_m4(\w*)$', `m4_\1', `POSIX_EXTENDED')
 @result{}
 @end example
 
address@hidden {Builtin (gnu)} renamesyms (@var{regexp}, @var{replacement})
-Same as @code{erenamesyms}, but using Basic Regular Expression syntax,
-see @xref{Eregexp and Regexp}, for more details.
address@hidden deffn
-
 
 @node Indir
 @section Indirect call of macros
@@ -1945,6 +1963,7 @@
 * Dnl::                         Deleting whitespace in input
 * Changequote::                 Changing the quote characters
 * Changecom::                   Changing the comment delimiters
+* Changeresyntax::              Changing the regular expression syntax
 * Changesyntax::                Changing the lexical structure of the input
 * M4wrap::                      Saving input until end of input
 @end menu
@@ -2088,6 +2107,87 @@
 @end example
 
 
address@hidden Changeresyntax
address@hidden Changing the regular expression syntax
+
address@hidden regular expression syntax, changing
address@hidden GNU extensions
address@hidden {Builtin (gnu)} changeresyntax (@w{opt @var{resyntax}})
+By default, the @sc{gnu} extensions @code{patsubst}, @code{regexp} and
+more recently @code{renamesyms} continue to use emacs style regular
+expression syntax (@pxref{Regular expression syntax}).
+
+The @code{changeresyntax} macro expands to nothing, but changes the
+default regular expression syntax used by M4 according to the value of
address@hidden, equivalent to passing @var{resyntax} as the argument to
address@hidden when invoking @code{m4}.  @xref{Invoking m4},
+for more details.  If @var{resyntax} is empty or omitted the default
+settings are reverted to emacs style.
address@hidden deffn
+
+Any one of the values below, case is not important, and optionally
+with @kbd{-} or @kbd{ } substituted for @kbd{_} in the given names,
+will set the default regular expression syntax as described in the
+table below.  For example the following are all equivalent to
address@hidden:
+
address@hidden
+changeresyntax(`gnu m4')
address@hidden
+changeresyntax(`GNU-m4')
address@hidden
+changeresyntax(`Gnu_M4')
address@hidden
address@hidden example
+
address@hidden @dfn
address@hidden AWK
address@hidden regular expression syntax}, for details.
+
address@hidden BASIC
address@hidden ED
address@hidden POSIX_BASIC
address@hidden SED
address@hidden regular expression syntax}, for details.
+
address@hidden BSD_M4
address@hidden regular expression syntax}, for details.
+
address@hidden EMACS
address@hidden GNU_EMACS
address@hidden regular expression syntax}, for details.
+
address@hidden EXTENDED
address@hidden POSIX_EXTENDED
address@hidden regular expression syntax}, for details.
+
address@hidden GNU_AWK
address@hidden GAWK
address@hidden regular expression syntax}, for details.
+
address@hidden GNU_EGREP
address@hidden EGREP
address@hidden regular expression syntax}, for details.
+
address@hidden GNU_M4
address@hidden regular expression syntax}, for details.
+
address@hidden GREP
address@hidden regular expression syntax}, for details.
+
address@hidden MINIMAL
address@hidden POSIX_MINIMAL
address@hidden POSIX_MINIMAL_BASIC
address@hidden regular expression syntax}, for details.
+
address@hidden POSIX_AWK
address@hidden regular expression syntax}, for details.
+
address@hidden POSIX_EGREP
address@hidden regular expression syntax}, for details.
address@hidden table
+
+
 @node Changesyntax
 @section Changing the lexical structure of the input
 
@@ -2952,10 +3052,10 @@
 @menu
 * Len::                         Calculating length of strings
 * Index::                       Searching for substrings
-* Eregexp and Regexp::          Searching for regular expressions
+* Regexp::                      Searching for regular expressions
 * Substr::                      Extracting substrings
 * Translit::                    Translating characters
-* Epatsubst and Patsubst::      Substituting text by regular expression
+* Patsubst::                    Substituting text by regular expression
 * Format::                      Formatting strings (printf-like)
 @end menu
 
@@ -2998,12 +3098,13 @@
 @result{}-1
 @end example
 
address@hidden Eregexp and Regexp
address@hidden Regexp
 @section Searching for regular expressions
 
 @cindex regular expressions
 @cindex GNU extensions
address@hidden {Builtin (gnu)} eregexp (@var{string}, @var{regexp}, @w{opt 
@var{replacement})}
address@hidden {Builtin (gnu)} regexp (@var{string}, @var{regexp}, 
@var{resyntax})
address@hidden {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @w{opt 
@var{replacement},} @w{opt @var{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
@@ -3014,13 +3115,18 @@
 is specified and matches, then it expands into @var{replacement}. If
 @var{regexp} does not match anywhere in @var{string}, it expands to -1.
 
-The builtin macro @code{eregexp} is recognized only when given arguments.
+If @var{resyntax} is given, the particular flavor of regular
+expression understood with respect to @var{regexp} can be changed from
+the current default.  @xref{Changeresyntax}, for details of the values
+that can be given for this argument.
+
+The builtin macro @code{regexp} is recognized only when given arguments.
 @end deffn
 
 @example
-eregexp(`GNUs not Unix', `\<[a-z]\w+')
+regexp(`GNUs not Unix', `\<[a-z]\w+')
 @result{}5
-eregexp(`GNUs not Unix', `\<Q\w*')
+regexp(`GNUs not Unix', `\<Q\w*')
 @result{}-1
 @end example
 
@@ -3030,27 +3136,29 @@
 @samp{\&} being the text the entire regular expression matched.
 
 @example
-eregexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***')
+regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
 @result{}*** Unix *** nix ***
 @end example
 
-Originally, regular expressions were much less powerful (basically only
address@hidden was available), but to keep backward compatibility, new
-operators were implemented with previously invalid sequences, such as
address@hidden(}.  The following macro is exactly equivalent to @code{eregexp},
-but using the old, clumsy syntax.
-
address@hidden {Builtin (gnu)} regexp (@var{string}, @var{regexp}, @w{opt 
@var{replacement})}
-Same as @code{eregexp}, but using the old and clumsy ``Basic Regular
-Expression'' syntax, the same as in @sc{gnu} Emacs.  @xref{Regexps, ,
-Syntax of Regular Expressions, emacs, The @sc{gnu} Emacs Manual}.
address@hidden deffn
+If @var{resyntax} is given, @var{regexp} must be given according to
+the syntax chosen, though the default regular expression syntax
+remains unchanged for other invocations:
 
 @example
-regexp(`GNUs not Unix', `\w\(\w+\)$', `*** \& *** \1 ***')
+regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***', `POSIX_EXTENDED')
 @result{}*** Unix *** nix ***
 @end example
 
+Occasionally, you might want to pass an @var{resyntax} argument
+without wishing to give @var{replacement}.  If the @strong{last}
+argument is a valid @var{resyntax} it is used as such whether
+or not a @var{replacement} argument is also given:
+
address@hidden
+regexp(`GNUs not Unix', `\w(\w+)$', `POSIX_EXTENDED')
address@hidden
address@hidden example
+
 @node Substr
 @section Extracting substrings
 
@@ -3114,18 +3222,22 @@
 while converting them to lowercase.  The two first cases are by far the
 most common.
 
address@hidden Epatsubst and Patsubst
address@hidden Patsubst
 @section Substituting text by regular expression
 
 @cindex regular expressions
 @cindex pattern substitution
 @cindex substitution by regular expression
 @cindex GNU extensions
address@hidden {Builtin (gnu)} epatsubst (@var{string}, @var{regexp}, @w{opt 
@var{replacement})}
-Global substitution in a string is done by @code{epatsubst}, which
address@hidden {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @w{opt 
@var{replacement},} @w{opt @var{resyntax})}
+Global substitution in a string is done by @code{patsubst}, which
 searches @var{string} for matches of @var{regexp}, and substitutes
address@hidden for each match.  It uses Extended Regular Expressions
-syntax.
address@hidden for each match.
+
+If @var{resyntax} is given, the particular flavor of regular
+expression understood with respect to @var{regexp} can be changed from
+the current default.  @xref{Changeresyntax}, for details of the values
+that can be given for this parameter.
 
 The parts of @var{string} that are not covered by any match of
 @var{regexp} are copied to the expansion.  Whenever a match is found, the
@@ -3142,23 +3254,23 @@
 The @var{replacement} argument can be omitted, in which case the text
 matched by @var{regexp} is deleted.
 
-The builtin macro @code{epatsubst} is recognized only when given
+The builtin macro @code{patsubst} is recognized only when given
 arguments.
 @end deffn
 
-When used with two arguments, while @code{eregexp} returns the position
-of the match, @code{epatsusbt} deletes it:
+When used with two arguments, while @code{regexp} returns the position
+of the match, @code{patsubst} deletes it:
 
 @example
-epatsubst(`GNUs not Unix', `^', `OBS: ')
+patsubst(`GNUs not Unix', `^', `OBS: ')
 @result{}OBS: GNUs not Unix
-epatsubst(`GNUs not Unix', `\<', `OBS: ')
+patsubst(`GNUs not Unix', `\<', `OBS: ')
 @result{}OBS: GNUs OBS: not OBS: Unix
-epatsubst(`GNUs not Unix', `\w*', `(\&)')
+patsubst(`GNUs not Unix', `\w*', `(\&)')
 @result{}(GNUs)() (not)() (Unix)
-epatsubst(`GNUs not Unix', `\w+', `(\&)')
+patsubst(`GNUs not Unix', `\w+', `(\&)')
 @result{}(GNUs) (not) (Unix)
-epatsubst(`GNUs not Unix', `[A-Z][a-z]+')
+patsubst(`GNUs not Unix', `[A-Z][a-z]+')
 @result{}GN not @comment
 @end example
 
@@ -3170,63 +3282,43 @@
 define(`upcase',   `translit(`$*', `a-z', `A-Z')')dnl
 define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
 define(`capitalize1',
-       `eregexp(`$1', `^(\w)(\w*)', `upcase(`\1')`'downcase(`\2')')')dnl
+       `regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl
 define(`capitalize',
-       `epatsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
+       `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
 capitalize(`GNUs not Unix')
 @result{}Gnus Not Unix
 @end example
 
-While @code{eregexp} replaces the whole input with the replacement as
-soon as there is a match, @code{epatsubst} replaces each
+If @var{resyntax} is given, @var{regexp} must be given according to
+the syntax chosen, though the default regular expression syntax
+remains unchanged for other invocations:
+
address@hidden
+define(`epatsubst',
+       `builtin(`patsubst', `$1', `$2', `$3', `POSIX_EXTENDED')')dnl
+epatsubst(`bar foo baz Foo', `(\w*) (foo|Foo)', `_\1_')
address@hidden _baz_
+patsubst(`bar foo baz Foo', `\(\w*\) \(foo\|Foo\)', `_\1_')
address@hidden _baz_
address@hidden example
+
+While @code{regexp} replaces the whole input with the replacement as
+soon as there is a match, @code{patsubst} replaces each
 @emph{occurrence} of a match and preserves non matching pieces:
 
 @example
 define(`patreg',
-`epatsubst($@@)
-eregexp($@@)')dnl
-patreg(`bar foo baz Foo', `foo|Foo', `FOO')
+`patsubst($@@)
+regexp($@@)')dnl
+patreg(`bar foo baz Foo', `foo\|Foo', `FOO')
 @result{}bar FOO baz FOO
 @result{}FOO
-patreg(`aba abb 121', `(.)(.)\1', `\2\1\2')
+patreg(`aba abb 121', `\(.\)\(.\)\1', `\2\1\2')
 @result{}bab abb 212
 @result{}bab
 @end example
 
 
address@hidden {Builtin (gnu)} patsubst (@var{string}, @var{regexp}, @w{opt 
@var{replacement})}
-Same as @code{epatsubst}, but using Basic Regular Expression syntax, see
address@hidden and Regexp}, for more details.
address@hidden deffn
-
address@hidden No longer interesting for the documentation per se, but good
address@hidden for testing.
address@hidden
address@hidden
-patsubst(`GNUs not Unix', `^', `OBS: ')
address@hidden: GNUs not Unix
-patsubst(`GNUs not Unix', `\<', `OBS: ')
address@hidden: GNUs OBS: not OBS: Unix
-patsubst(`GNUs not Unix', `\w*', `(\&)')
address@hidden(GNUs)() (not)() (Unix)
-patsubst(`GNUs not Unix', `\w+', `(\&)')
address@hidden(GNUs) (not) (Unix)
-patsubst(`GNUs not Unix', `[A-Z][a-z]+')
address@hidden not @comment
address@hidden example
-
address@hidden
-define(`upcase',   `translit(`$*', `a-z', `A-Z')')dnl
-define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
-define(`capitalize1',
-       `regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl
-define(`capitalize',
-       `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
-capitalize(`GNUs not Unix')
address@hidden Not Unix
address@hidden example
address@hidden ignore
-
 @node Format
 @section Formatted output
 
@@ -3814,6 +3906,11 @@
 Uses @var{string1} and @var{string2} as the beginning quote and end quote
 strings.
 
address@hidden 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.
address@hidden, for more details.
+
 @item M @var{length} @key{NL} @var{string} @key{NL}
 Names a module which will be searched for according to the module search path
 and loaded.  Modules loaded from a frozen file don't add their builtin entries
@@ -3913,16 +4010,15 @@
 
 @item
 Searches and text substitution through regular expressions are supported
-by the @code{eregexp}, @code{regexp} (@pxref{Eregexp and Regexp}) and
address@hidden, @code{patsubst} (@pxref{Epatsubst and Patsubst})
-builtins.
+by the @code{regexp} (@pxref{Regexp}) and @code{patsubst}
+(@pxref{Patsubst}) builtins.
 
 @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
address@hidden (@pxref{Eregexp and Regexp}) and @code{epatsubst}
-(@pxref{Epatsubst and Patsubst}) for extended regular expressions.
address@hidden (@pxref{Changeresyntax}) to change the regular
+expression syntax used by @sc{gnu} M4.
 
 @item
 The output of shell commands can be read into @code{m4} with
@@ -3956,8 +4052,8 @@
 In addition to the above extensions, GNU @code{m4} implements the
 following command line options: @samp{-F}, @samp{-G}, @samp{-I},
 @samp{-L}, @samp{-R}, @samp{-V}, @samp{-W}, @samp{-d},
address@hidden, @samp{-o} and @samp{-t}.  @xref{Invoking m4}, for a
-description of these options.
address@hidden, @samp{-o}, @samp{-r} and @samp{-t}.  @xref{Invoking m4},
+for a description of these options.
 
 Also, the debugging and tracing facilities in GNU @code{m4} are much
 more extensive than in most other versions of @code{m4}.