* doc/RegExp.3: Documented the new regexp interfaces and

the compile/execute flags.

1 files changed, 238 insertions, 24 deletions

diff --git a/doc/RegExp.3 b/doc/RegExp.3
index 1f1064d..9fefdaf 100644
--- a/doc/RegExp.3
+++ b/doc/RegExp.3
@@ -6,19 +6,19 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: RegExp.3,v 1.3 1999/04/16 00:46:32 stanton Exp $
+'\" RCS: @(#) $Id: RegExp.3,v 1.4 1999/06/17 19:32:21 stanton Exp $
 '\" 
 .so man.macros
-.TH Tcl_RegExpMatch 3 7.4 Tcl "Tcl Library Procedures"
+.TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_GetRegExpFromObj, Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern matching with regular expressions
+Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_GetRegExpInfo \- Pattern matching with regular expressions
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
 .sp
-Tcl_RegExp
-\fBTcl_GetRegExpFromObj\fR(\fIinterp\fR, \fIpatObj\fR, \fIflags\fR)
+int
+\fBTcl_RegExpMatchObj\fR(\fIinterp\fR, \fIstrObj\fR, \fIpatObj\fR)
 .sp
 int
 \fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
@@ -30,21 +30,38 @@ int
 \fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
 .sp
 \fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
+.VS 8.1
+.sp
+Tcl_RegExp
+\fBTcl_GetRegExpFromObj\fR(\fIinterp\fR, \fIpatObj\fR, \fIcflags\fR)
+.sp
+int
+\fBTcl_RegExpExecObj\fR(\fIregexp\fR, \fIobjPtr\fR, \fIoffset\fR, \fInmatches\fR, \fIeflags\fR)
+.sp
+\fBTcl_GetRegExpInfo\fR(\fIregexp\fR, \fIinfoPtr\fR)
+.VE 8.1
+
 .SH ARGUMENTS
 .AS Tcl_Interp *interp
 .AP Tcl_Interp *interp in
-Tcl interpreter to use for error reporting.
+Tcl interpreter to use for error reporting.  The interpreter may be
+NULL if no error reporting is desired.
+.VS 8.1
+.AP Tcl_Obj *strObj in/out
+Refers to the object from which to get the string to search.  The
+internal representation of the object may be converted to a form that
+can be efficiently searched.
+.AP Tcl_Obj *patObj in/out
+Refers to the object from which to get a regular expression. The
+compiled regular expression is cached in the object.
+.VE 8.1
 .AP char *string in
 String to check for a match with a regular expression.
 .AP char *pattern in
 String in the form of a regular expression pattern.
-.AP Tcl_Obj *patObj in
-Refers to the object from which to get a compiled regular expression.
-.AP int flags in
-Various flags to control regular expression compile options.
 .AP Tcl_RegExp regexp in
 Compiled regular expression.  Must have been returned previously
-by \fBTcl_GetRegExpFromObj\fR.
+by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR.
 .AP char *start in
 If \fIstring\fR is just a portion of some other string, this argument
 identifies the beginning of the larger string.
@@ -60,26 +77,50 @@ NULL if there is no such range.
 .AP char **endPtr out
 The address of the character just after the last one in the range
 is stored here, or NULL if there is no such range.
+.VS 8.1
+.AP int cflags in
+OR-ed combination of compilation flags. See below for more information.
+.AP Tcl_Obj *objPtr in/out
+An object which contains the string to check for a match with a
+regular expression.
+.AP int offset in
+The character offset into the string where matching should begin.
+The value of the offset has no impact on \fB^\fR matches.  This
+behavior is controlled by \fIeflags\fR.
+.AP int nmatches in
+The number of matching subexpressions that should be remembered for
+later use.  If this value is 0, then no subexpression match
+information will be computed.  If the value is -1, then
+all of the matching subexpressions will be remembered.  Any other
+value will be taken as the maximum number of subexpressions to
+remember.
+.AP int eflags in
+OR-ed combination of the values TCL_REG_NOTBOL and TCL_REG_NOTEOL.
+See below for more information.
+.AP Tcl_RegExpInfo *infoPtr out
+The address of the location where information about a previous match
+should be stored by \fBTcl_GetRegExpInfo\fR.
+.VE 8.1
 .BE
 
 .SH DESCRIPTION
 .PP
-\fBTcl_GetRegExpFromObj\fR attepts to return a compiled regular 
-expression from the Tcl obj \fIpatObj\fR.  If the object does not
-already contain a compiled regular expression it will attempt to
-create one from the string in the Tcl obj and assign it to the
-internal representation of the \fIpatObj\fR.  The return value
-of this function is of type \fBTcl_RegExp\fR.
-.PP
 \fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
 matches \fIregexp\fR, where \fIregexp\fR is interpreted
-as a regular expression using the same rules as for the
-\fBregexp\fR Tcl command.
+as a regular expression using the rules in the \fBre_syntax\fR
+reference page. 
 If there is a match then \fBTcl_RegExpMatch\fR returns 1.
 If there is no match then \fBTcl_RegExpMatch\fR returns 0.
 If an error occurs in the matching process (e.g. \fIpattern\fR
 is not a valid regular expression) then \fBTcl_RegExpMatch\fR
-returns \-1 and leaves an error message in \fIinterp->result\fR.
+returns \-1 and leaves an error message in the interpreter result.
+.VS 8.1.2
+\fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it
+operates on the Tcl objects \fIstrObj\fR and \fIpatObj\fR instead of
+UTF strings. 
+\fBTcl_RegExpMatchObj\fR is generally more efficient than
+\fBTcl_RegExpMatch\fR, so it is the preferred interface.
+.VE 8.1.2
 .PP
 \fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
 provide lower-level access to the regular expression pattern matcher.
@@ -89,7 +130,7 @@ The return value is a token for this compiled form, which can be
 used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
 If an error occurs while compiling the regular expression then
 \fBTcl_RegExpCompile\fR returns NULL and leaves an error message
-in \fIinterp->result\fR.
+in the interpreter result.
 Note:  the return value from \fBTcl_RegExpCompile\fR is only valid
 up to the next call to \fBTcl_RegExpCompile\fR;  it is not safe to
 retain these values for long periods of time.
@@ -99,7 +140,7 @@ It returns 1 if \fIstring\fR contains a range of characters that
 match \fIregexp\fR, 0 if no match is found, and
 \-1 if an error occurs.
 In the case of an error, \fBTcl_RegExpExec\fR leaves an error
-message in \fIinterp->result\fR.
+message in the interpreter result.
 When searching a string for multiple matches of a pattern,
 it is important to distinguish between the start of the original
 string and the start of the current search.
@@ -126,6 +167,179 @@ information is returned about the range of characters that matched the
 \fIindex\fR'th parenthesized subexpression within the pattern.
 If there is no range corresponding to \fIindex\fR then NULL
 is stored in \fI*firstPtr\fR and \fI*lastPtr\fR.
+.PP
+.VS 8.1
+\fBTcl_GetRegExpFromObj\fR, \fBTcl_RegExpExecObj\fR, and
+\fBTcl_GetRegExpInfo\fR are object interfaces that provide the most
+direct control of Henry Spencer's regular expression library.  For
+users that need to modify compilation and execution options directly,
+it is recommended that you use these interfaces instead of calling the
+internal regexp functions.  These interfaces handle the details of UTF
+to Unicode translations as well as providing improved performance
+through caching in the pattern and string objects.
+.PP
+\fBTcl_GetRegExpFromObj\fR attepts to return a compiled regular
+expression from the \fIpatObj\fR.  If the object does not already
+contain a compiled regular expression it will attempt to create one
+from the string in the object and assign it to the internal
+representation of the \fIpatObj\fR.  The return value of this function
+is of type \fBTcl_RegExp\fR.  The return value is a token for this
+compiled form, which can be used in subsequent calls to
+\fBTcl_RegExpExecObj\fR or \fBTcl_GetRegExpInfo\fR.  If an error
+occurs while compiling the regular expression then
+\fBTcl_GetRegExpFromObj\fR returns NULL and leaves an error message in
+the interpreter result.  The regular expression token can be used as
+long as the internal representation of \fIpatObj\fR refers to the
+compiled form.  The \fIeflags\fR argument is a bitwise OR of
+zero or more of the following flags that control the compilation of
+\fIpatObj\fR:
+.RS 2
+.TP
+\fBTCL_REG_ADVANCED\fR
+Compile advanced regular expressions (`AREs').  This mode corresponds to
+the normal regular expression syntax accepted by the Tcl regexp and
+regsub commands.
+.TP
+\fBTCL_REG_EXTENDED\fR
+Compile extended regular expressions (`EREs').  This mode corresponds
+to the regular expression syntax recognized by Tcl 8.0 and earlier
+versions. 
+.TP
+\fBTCL_REG_BASIC\fR
+Compile basic regular expressions (`BREs').  This mode corresponds
+to the regular expression syntax recognized by common Unix utilities
+like \fBsed\fR and \fBgrep\fR.  This is the default if no flags are
+specified.
+.TP
+\fBTCL_REG_EXPANDED\fR
+Compile the regular expression (basic, extended, or advanced) using an
+expanded syntax that allows comments and whitespace.  This mode causes
+non-backslashed non-bracket-expression white
+space and #-to-end-of-line comments to be ignored.
+.TP
+\fBTCL_REG_QUOTE\fR
+Compile a literal string, with all characters treated as ordinary characters.
+.TP
+\fBTCL_REG_NOCASE\fR
+Compile for matching that ignores upper/lower case distinctions.
+.TP
+\fBTCL_REG_NEWLINE\fR
+Compile for newline-sensitive matching.  By default, newline is a
+completely ordinary character with no special meaning in either
+regular expressions or strings.  With this flag, `[^' bracket
+expressions and `.' never match newline, `^' matches an empty string
+after any newline in addition to its normal function, and `$' matches
+an empty string before any newline in addition to its normal function.
+\fBREG_NEWLINE\fR is the bitwise OR of \fBREG_NLSTOP\fR and
+\fBREG_NLANCH\fR.
+.TP
+\fBTCL_REG_NLSTOP\fR
+Compile for partial newline-sensitive matching,
+with the behavior of
+`[^' bracket expressions and `.' affected,
+but not the behavior of `^' and `$'.  In this mode, `[^' bracket
+expressions and `.' never match newline.
+.TP
+\fBTCL_REG_NLANCH\fR
+Compile for inverse partial newline-sensitive matching,
+with the behavior of
+of `^' and `$' (the ``anchors'') affected, but not the behavior of
+`[^' bracket expressions and `.'.  In this mode `^' matches an empty string
+after any newline in addition to its normal function, and `$' matches
+an empty string before any newline in addition to its normal function.
+.TP
+\fBTCL_REG_NOSUB\fR
+Compile for matching that reports only success or failure,
+not what was matched.  This reduces compile overhead and may improve
+performance.  Subsequent calls to \fBTcl_GetRegExpInfo\fR or
+\fBTcl_RegExpRange\fR will not report any match information.
+.TP
+\fBTCL_REG_CANMATCH\fR
+Compile for matching that reports the potential to complete a partial
+match given more text (see below).
+.RE
+.PP
+Only one of
+\fBTCL_REG_EXTENDED\fR,
+\fBTCL_REG_ADVANCED\fR,
+\fBTCL_REG_BASIC\fR, and
+\fBTCL_REG_QUOTE\fR may be specified.
+.PP
+\fBTcl_RegExpExecObj\fR executes the regular expression pattern
+matcher.  It returns 1 if \fIobjPtr\fR contains a range of characters
+that match \fIregexp\fR, 0 if no match is found, and \-1 if an error
+occurs.  In the case of an error, \fBTcl_RegExpExecObj\fR leaves an
+error message in the interpreter result.  The \fInmatches\fR value
+indicates to the matcher how many subexpressions are of interest.  If
+\fInmatches\fR is 0, then no subexpression match information is
+recorded, which may allow the matcher to make various optimizations.
+If the value is -1, then all of the subexpressions in the pattern are
+remembered.  If the value is a positive integer, then only that number
+of subexpressions will be remembered.  Matching begins at the
+specified Unicode character index given by \fIoffset\fR.  Unlike
+\fBTcl_RegExpExec\fR, the behavior of anchors is not affected by the
+offset value.  Instead the behavior of the anchors is explicitly
+controlled by the \fIeflags\fR argument, which is a bitwise OR of
+zero or more of the following flags:
+.RS 2
+.TP
+\fBTCL_REG_NOTBOL\fR
+The starting character will not be treated as the beginning of a
+line or the beginning of the string, so `^' will not match there.
+Note that this flag has no effect on how `\fB\eA\fR' matches.
+.TP
+\fBTCL_REG_NOTEOL\fR
+The last character in the string will not be treated as the end of a
+line or the end of the string, so '$' will not match there.
+Note that this flag has no effect on how `\fB\eZ\fR' matches.
+.RE
+.PP
+\fBTcl_GetRegExpInfo\fR retrieves information about the last match
+performed with a given regular expression \fIregexp\fR.  The
+\fIinfoPtr\fR argument contains a pointer to a structure that is
+defined as follows:
+.PP
+.CS
+typedef struct Tcl_RegExpInfo {
+	int \fInsubs\fR;
+	Tcl_RegExpIndices *\fImatches\fR;
+	long \fIextendStart\fR;
+} Tcl_RegExpInfo;
+.CE
+.PP
+The \fInsubs\fR field contains a count of the number of parenthesized
+subexpressions within the regular expression.  If the \fBTCL_REG_NOSUB\fR
+was used, then this value will be zero.  The \fImatches\fR field
+points to an array of \fInsubs\fR values that indicate the bounds of each
+subexpression matched.  The first element in the array refers to the
+range matched by the entire regular expression, and subsequent elements
+refer to the parenthesized subexpressions in the order that they
+appear in the pattern.  Each element is a structure that is defined as
+follows:
+.PP
+.CS
+typedef struct Tcl_RegExpIndices {
+	long \fIstart\fR;
+	long \fIend\fR;
+} Tcl_RegExpIndices;
+.CE
+.PP
+The \fIstart\fR and \fIend\fR values are Unicode character indices
+relative to the offset location within \fIobjPtr\fR where matching began.
+The \fIstart\fR index identifies the first character of the matched
+subexpression.  The \fIend\fR index identifies the first character
+after the matched subexpression.  If the subexpression matched the
+empty string, then \fIstart\fR and \fIend\fR will be equal.  If the
+subexpression did not participate in the match, then \fIstart\fR and
+\fIend\fR will be set to -1.
+.PP
+The \fIextendStart\fR field in \fBTcl_RegExpInfo\fR is only set if the
+\fBTCL_REG_CANMATCH\fR flag was used.  It indicates the first
+character in the string where a match could occur.  If a match was
+found, this will be the same as the beginning of the current match.
+If no match was found, then it indicates the earliest point at which a
+match might occur if additional text is appended to the string.
+.VE 8.1
 
 .SH KEYWORDS
-match, pattern, regular expression, string, subexpression
+match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegExpInfo