[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Changes to m4/doc/m4.texinfo,v
From: |
Gary V. Vaughan |
Subject: |
Changes to m4/doc/m4.texinfo,v |
Date: |
Thu, 13 Jul 2006 23:35:17 +0000 |
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}.
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/07/05
- Changes to m4/doc/m4.texinfo,v,
Gary V. Vaughan <=
- Changes to m4/doc/m4.texinfo,v, Gary V. Vaughan, 2006/07/14
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/07/15
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/07/17
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2006/07/19