| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1994 The Regents of the University of California.
|
| 3 |
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
| 4 |
|
|
'\"
|
| 5 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
| 6 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
| 7 |
|
|
'\"
|
| 8 |
|
|
'\" RCS: @(#) $Id: RegExp.3,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
| 9 |
|
|
'\"
|
| 10 |
|
|
.so man.macros
|
| 11 |
|
|
.TH Tcl_RegExpMatch 3 7.4 Tcl "Tcl Library Procedures"
|
| 12 |
|
|
.BS
|
| 13 |
|
|
.SH NAME
|
| 14 |
|
|
Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern matching with regular expressions
|
| 15 |
|
|
.SH SYNOPSIS
|
| 16 |
|
|
.nf
|
| 17 |
|
|
\fB#include \fR
|
| 18 |
|
|
.sp
|
| 19 |
|
|
int
|
| 20 |
|
|
\fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
|
| 21 |
|
|
.sp
|
| 22 |
|
|
Tcl_RegExp
|
| 23 |
|
|
\fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
|
| 24 |
|
|
.sp
|
| 25 |
|
|
int
|
| 26 |
|
|
\fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
|
| 27 |
|
|
.sp
|
| 28 |
|
|
\fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
|
| 29 |
|
|
.SH ARGUMENTS
|
| 30 |
|
|
.AS Tcl_Interp *interp
|
| 31 |
|
|
.AP Tcl_Interp *interp in
|
| 32 |
|
|
Tcl interpreter to use for error reporting.
|
| 33 |
|
|
.AP char *string in
|
| 34 |
|
|
String to check for a match with a regular expression.
|
| 35 |
|
|
.AP char *pattern in
|
| 36 |
|
|
String in the form of a regular expression pattern.
|
| 37 |
|
|
.AP Tcl_RegExp regexp in
|
| 38 |
|
|
Compiled regular expression. Must have been returned previously
|
| 39 |
|
|
by \fBTcl_RegExpCompile\fR.
|
| 40 |
|
|
.AP char *start in
|
| 41 |
|
|
If \fIstring\fR is just a portion of some other string, this argument
|
| 42 |
|
|
identifies the beginning of the larger string.
|
| 43 |
|
|
If it isn't the same as \fIstring\fR, then no \fB^\fR matches
|
| 44 |
|
|
will be allowed.
|
| 45 |
|
|
.AP int index in
|
| 46 |
|
|
Specifies which range is desired: 0 means the range of the entire
|
| 47 |
|
|
match, 1 or greater means the range that matched a parenthesized
|
| 48 |
|
|
sub-expression.
|
| 49 |
|
|
.AP char **startPtr out
|
| 50 |
|
|
The address of the first character in the range is stored here, or
|
| 51 |
|
|
NULL if there is no such range.
|
| 52 |
|
|
.AP char **endPtr out
|
| 53 |
|
|
The address of the character just after the last one in the range
|
| 54 |
|
|
is stored here, or NULL if there is no such range.
|
| 55 |
|
|
.BE
|
| 56 |
|
|
|
| 57 |
|
|
.SH DESCRIPTION
|
| 58 |
|
|
.PP
|
| 59 |
|
|
\fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
|
| 60 |
|
|
matches \fIregexp\fR, where \fIregexp\fR is interpreted
|
| 61 |
|
|
as a regular expression using the same rules as for the
|
| 62 |
|
|
\fBregexp\fR Tcl command.
|
| 63 |
|
|
If there is a match then \fBTcl_RegExpMatch\fR returns 1.
|
| 64 |
|
|
If there is no match then \fBTcl_RegExpMatch\fR returns 0.
|
| 65 |
|
|
If an error occurs in the matching process (e.g. \fIpattern\fR
|
| 66 |
|
|
is not a valid regular expression) then \fBTcl_RegExpMatch\fR
|
| 67 |
|
|
returns \-1 and leaves an error message in \fIinterp->result\fR.
|
| 68 |
|
|
.PP
|
| 69 |
|
|
\fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
|
| 70 |
|
|
provide lower-level access to the regular expression pattern matcher.
|
| 71 |
|
|
\fBTcl_RegExpCompile\fR compiles a regular expression string into
|
| 72 |
|
|
the internal form used for efficient pattern matching.
|
| 73 |
|
|
The return value is a token for this compiled form, which can be
|
| 74 |
|
|
used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
|
| 75 |
|
|
If an error occurs while compiling the regular expression then
|
| 76 |
|
|
\fBTcl_RegExpCompile\fR returns NULL and leaves an error message
|
| 77 |
|
|
in \fIinterp->result\fR.
|
| 78 |
|
|
Note: the return value from \fBTcl_RegExpCompile\fR is only valid
|
| 79 |
|
|
up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to
|
| 80 |
|
|
retain these values for long periods of time.
|
| 81 |
|
|
.PP
|
| 82 |
|
|
\fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
|
| 83 |
|
|
It returns 1 if \fIstring\fR contains a range of characters that
|
| 84 |
|
|
match \fIregexp\fR, 0 if no match is found, and
|
| 85 |
|
|
\-1 if an error occurs.
|
| 86 |
|
|
In the case of an error, \fBTcl_RegExpExec\fR leaves an error
|
| 87 |
|
|
message in \fIinterp->result\fR.
|
| 88 |
|
|
When searching a string for multiple matches of a pattern,
|
| 89 |
|
|
it is important to distinguish between the start of the original
|
| 90 |
|
|
string and the start of the current search.
|
| 91 |
|
|
For example, when searching for the second occurrence of a
|
| 92 |
|
|
match, the \fIstring\fR argument might point to the character
|
| 93 |
|
|
just after the first match; however, it is important for the
|
| 94 |
|
|
pattern matcher to know that this is not the start of the entire string,
|
| 95 |
|
|
so that it doesn't allow \fB^\fR atoms in the pattern to match.
|
| 96 |
|
|
The \fIstart\fR argument provides this information by pointing
|
| 97 |
|
|
to the start of the overall string containing \fIstring\fR.
|
| 98 |
|
|
\fIStart\fR will be less than or equal to \fIstring\fR; if it
|
| 99 |
|
|
is less than \fIstring\fR then no \fB^\fR matches will be allowed.
|
| 100 |
|
|
.PP
|
| 101 |
|
|
\fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR
|
| 102 |
|
|
returns; it provides detailed information about what ranges of
|
| 103 |
|
|
the string matched what parts of the pattern.
|
| 104 |
|
|
\fBTcl_RegExpRange\fR returns a pair of pointers in \fI*startPtr\fR
|
| 105 |
|
|
and \fI*endPtr\fR that identify a range of characters in
|
| 106 |
|
|
the source string for the most recent call to \fBTcl_RegExpExec\fR.
|
| 107 |
|
|
\fIIndex\fR indicates which of several ranges is desired:
|
| 108 |
|
|
if \fIindex\fR is 0, information is returned about the overall range
|
| 109 |
|
|
of characters that matched the entire pattern; otherwise,
|
| 110 |
|
|
information is returned about the range of characters that matched the
|
| 111 |
|
|
\fIindex\fR'th parenthesized subexpression within the pattern.
|
| 112 |
|
|
If there is no range corresponding to \fIindex\fR then NULL
|
| 113 |
|
|
is stored in \fI*firstPtr\fR and \fI*lastPtr\fR.
|
| 114 |
|
|
|
| 115 |
|
|
.SH KEYWORDS
|
| 116 |
|
|
match, pattern, regular expression, string, subexpression
|
