On Apache
Under GNU General Public License
2024-04-24 17:51 @18.191.171.235 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Tcl_RegExpMatch(3) Tcl Library Procedures Tcl_RegExpMatch(3)
_________________________________________________________________________________________________
NAME
Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj,
Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo - Pattern matching with regular
expressions
SYNOPSIS
#include <tcl.h>
int
Tcl_RegExpMatchObj(interp, textObj, patObj)
int
Tcl_RegExpMatch(interp, text, pattern)
Tcl_RegExp
Tcl_RegExpCompile(interp, pattern)
int
Tcl_RegExpExec(interp, regexp, text, start)
void
Tcl_RegExpRange(regexp, index, startPtr, endPtr)
Tcl_RegExp
Tcl_GetRegExpFromObj(interp, patObj, cflags)
int
Tcl_RegExpExecObj(interp, regexp, textObj, offset, nmatches, eflags)
void
Tcl_RegExpGetInfo(regexp, infoPtr)
ARGUMENTS
Tcl_Interp *interp (in) Tcl interpreter to use for error reporting. The
interpreter may be NULL if no error reporting is
desired.
Tcl_Obj *textObj (in/out) Refers to the object from which to get the text to
search. The internal representation of the object
may be converted to a form that can be efficiently
searched.
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.
char *text (in) Text to search for a match with a regular expression.
const char *pattern (in) String in the form of a regular expression pattern.
Tcl_RegExp regexp (in) Compiled regular expression. Must have been returned
previously by Tcl_GetRegExpFromObj or Tcl_RegExpCom-
pile.
char *start (in) If text is just a portion of some other string, this
argument identifies the beginning of the larger
string. If it is not the same as text, then no "^"
matches will be allowed.
int index (in) Specifies which range is desired: 0 means the range
of the entire match, 1 or greater means the range
that matched a parenthesized sub-expression.
const char **startPtr (out) The address of the first character in the range is
stored here, or NULL if there is no such range.
const 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.
int cflags (in) OR-ed combination of the compilation flags
TCL_REG_ADVANCED, TCL_REG_EXTENDED, TCL_REG_BASIC,
TCL_REG_EXPANDED, TCL_REG_QUOTE, TCL_REG_NOCASE,
TCL_REG_NEWLINE, TCL_REG_NLSTOP, TCL_REG_NLANCH,
TCL_REG_NOSUB, and TCL_REG_CANMATCH. See below for
more information.
int offset (in) The character offset into the text where matching
should begin. The value of the offset has no impact
on ^ matches. This behavior is controlled by eflags.
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 subex-
pressions will be remembered. Any other value will
be taken as the maximum number of subexpressions to
remember.
int eflags (in) OR-ed combination of the execution flags TCL_REG_NOT-
BOL and TCL_REG_NOTEOL. See below for more informa-
tion.
Tcl_RegExpInfo *infoPtr (out) The address of the location where information about a
previous match should be stored by Tcl_RegExpGetInfo.
_________________________________________________________________
DESCRIPTION
Tcl_RegExpMatch determines whether its pattern argument matches regexp, where regexp is
interpreted as a regular expression using the rules in the re_syntax reference page. If
there is a match then Tcl_RegExpMatch returns 1. If there is no match then Tcl_RegExp-
Match returns 0. If an error occurs in the matching process (e.g. pattern is not a valid
regular expression) then Tcl_RegExpMatch returns -1 and leaves an error message in the
interpreter result. Tcl_RegExpMatchObj is similar to Tcl_RegExpMatch except it operates
on the Tcl objects textObj and patObj instead of UTF strings. Tcl_RegExpMatchObj is gen-
erally more efficient than Tcl_RegExpMatch, so it is the preferred interface.
Tcl_RegExpCompile, Tcl_RegExpExec, and Tcl_RegExpRange provide lower-level access to the
regular expression pattern matcher. Tcl_RegExpCompile compiles a regular expression
string into the internal form used for efficient pattern matching. The return value is a
token for this compiled form, which can be used in subsequent calls to Tcl_RegExpExec or
Tcl_RegExpRange. If an error occurs while compiling the regular expression then Tcl_Reg-
ExpCompile returns NULL and leaves an error message in the interpreter result. Note: the
return value from Tcl_RegExpCompile is only valid up to the next call to Tcl_RegExpCom-
pile; it is not safe to retain these values for long periods of time.
Tcl_RegExpExec executes the regular expression pattern matcher. It returns 1 if text con-
tains a range of characters that match regexp, 0 if no match is found, and -1 if an error
occurs. In the case of an error, Tcl_RegExpExec leaves an error message in the inter-
preter 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. For example, when searching for the second occurrence of a match, the text argu-
ment might point to the character just after the first match; however, it is important
for the pattern matcher to know that this is not the start of the entire string, so that
it does not allow "^" atoms in the pattern to match. The start argument provides this
information by pointing to the start of the overall string containing text. Start will be
less than or equal to text; if it is less than text then no ^ matches will be allowed.
Tcl_RegExpRange may be invoked after Tcl_RegExpExec returns; it provides detailed infor-
mation about what ranges of the string matched what parts of the pattern. Tcl_RegExpRange
returns a pair of pointers in *startPtr and *endPtr that identify a range of characters in
the source string for the most recent call to Tcl_RegExpExec. Index indicates which of
several ranges is desired: if index is 0, information is returned about the overall range
of characters that matched the entire pattern; otherwise, information is returned about
the range of characters that matched the index'th parenthesized subexpression within the
pattern. If there is no range corresponding to index then NULL is stored in *startPtr and
*endPtr.
Tcl_GetRegExpFromObj, Tcl_RegExpExecObj, and Tcl_RegExpGetInfo 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 perfor-
mance through caching in the pattern and string objects.
Tcl_GetRegExpFromObj attempts to return a compiled regular expression from the patObj. If
the object does not already contain a compiled regular expression it will attempt to cre-
ate one from the string in the object and assign it to the internal representation of the
patObj. The return value of this function is of type Tcl_RegExp. The return value is a
token for this compiled form, which can be used in subsequent calls to Tcl_RegExpExecObj
or Tcl_RegExpGetInfo. If an error occurs while compiling the regular expression then
Tcl_GetRegExpFromObj 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 patObj
refers to the compiled form. The cflags argument is a bit-wise OR of zero or more of the
following flags that control the compilation of patObj:
TCL_REG_ADVANCED
Compile advanced regular expressions ("ARE"s). This mode corresponds to the nor-
mal regular expression syntax accepted by the Tcl regexp and regsub commands.
TCL_REG_EXTENDED
Compile extended regular expressions ("ERE"s). This mode corresponds to the reg-
ular expression syntax recognized by Tcl 8.0 and earlier versions.
TCL_REG_BASIC
Compile basic regular expressions ("BRE"s). This mode corresponds to the regular
expression syntax recognized by common Unix utilities like sed and grep. This is
the default if no flags are specified.
TCL_REG_EXPANDED
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.
TCL_REG_QUOTE
Compile a literal string, with all characters treated as ordinary characters.
TCL_REG_NOCASE
Compile for matching that ignores upper/lower case distinctions.
TCL_REG_NEWLINE
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. REG_NEWLINE is the bit-wise OR of REG_NLSTOP and REG_NLANCH.
TCL_REG_NLSTOP
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.
TCL_REG_NLANCH
Compile for inverse partial newline-sensitive matching, with the behavior of "^"
and "$" (the "anchors") affected, but not the behavior of "[^" bracket expres-
sions and ".". In this mode "^" matches an empty string after any newline in
addition to its normal function, and "$" matches an empty string before any new-
line in addition to its normal function.
TCL_REG_NOSUB
Compile for matching that reports only success or failure, not what was matched.
This reduces compile overhead and may improve performance. Subsequent calls to
Tcl_RegExpGetInfo or Tcl_RegExpRange will not report any match information.
TCL_REG_CANMATCH
Compile for matching that reports the potential to complete a partial match given
more text (see below).
Only one of TCL_REG_EXTENDED, TCL_REG_ADVANCED, TCL_REG_BASIC, and TCL_REG_QUOTE may be
specified.
Tcl_RegExpExecObj executes the regular expression pattern matcher. It returns 1 if objPtr
contains a range of characters that match regexp, 0 if no match is found, and -1 if an
error occurs. In the case of an error, Tcl_RegExpExecObj leaves an error message in the
interpreter result. The nmatches value indicates to the matcher how many subexpressions
are of interest. If nmatches 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 speci-
fied Unicode character index given by offset. Unlike Tcl_RegExpExec, the behavior of
anchors is not affected by the offset value. Instead the behavior of the anchors is
explicitly controlled by the eflags argument, which is a bit-wise OR of zero or more of
the following flags:
TCL_REG_NOTBOL
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 "\A" matches.
TCL_REG_NOTEOL
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 "\Z" matches.
Tcl_RegExpGetInfo retrieves information about the last match performed with a given regu-
lar expression regexp. The infoPtr argument contains a pointer to a structure that is
defined as follows:
typedef struct Tcl_RegExpInfo {
int nsubs;
Tcl_RegExpIndices *matches;
long extendStart;
} Tcl_RegExpInfo;
The nsubs field contains a count of the number of parenthesized subexpressions within the
regular expression. If the TCL_REG_NOSUB was used, then this value will be zero. The
matches field points to an array of nsubs+1 values that indicate the bounds of each subex-
pression matched. The first element in the array refers to the range matched by the
entire regular expression, and subsequent elements refer to the parenthesized subexpres-
sions in the order that they appear in the pattern. Each element is a structure that is
defined as follows:
typedef struct Tcl_RegExpIndices {
long start;
long end;
} Tcl_RegExpIndices;
The start and end values are Unicode character indices relative to the offset location
within objPtr where matching began. The start index identifies the first character of the
matched subexpression. The end index identifies the first character after the matched
subexpression. If the subexpression matched the empty string, then start and end will be
equal. If the subexpression did not participate in the match, then start and end will be
set to -1.
The extendStart field in Tcl_RegExpInfo is only set if the TCL_REG_CANMATCH 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. If it is no match is possible even with further text,
this field will be set to -1.
SEE ALSO
re_syntax(n)
KEYWORDS
match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegEx-
pInfo
Tcl 8.1 Tcl_RegExpMatch(3)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-04-24 17:51 @18.191.171.235 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)