2 '\" Copyright (c) 1994 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
4 '\" Copyright (c) 1998-1999 Scriptics Corportation
6 '\" See the file "license.terms" for information on usage and redistribution
7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
12 .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
15 Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- Pattern matching with regular expressions
18 \fB#include <tcl.h>\fR
21 \fBTcl_RegExpMatchObj\fR(\fIinterp\fR, \fIstrObj\fR, \fIpatObj\fR)
24 \fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
27 \fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
30 \fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
32 \fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
36 \fBTcl_GetRegExpFromObj\fR(\fIinterp\fR, \fIpatObj\fR, \fIcflags\fR)
39 \fBTcl_RegExpExecObj\fR(\fIinterp\fR, \fIregexp\fR, \fIobjPtr\fR, \fIoffset\fR, \fInmatches\fR, \fIeflags\fR)
41 \fBTcl_RegExpGetInfo\fR(\fIregexp\fR, \fIinfoPtr\fR)
45 .AS Tcl_Interp *interp
46 .AP Tcl_Interp *interp in
47 Tcl interpreter to use for error reporting. The interpreter may be
48 NULL if no error reporting is desired.
50 .AP Tcl_Obj *strObj in/out
51 Refers to the object from which to get the string to search. The
52 internal representation of the object may be converted to a form that
53 can be efficiently searched.
54 .AP Tcl_Obj *patObj in/out
55 Refers to the object from which to get a regular expression. The
56 compiled regular expression is cached in the object.
59 String to check for a match with a regular expression.
61 String in the form of a regular expression pattern.
62 .AP Tcl_RegExp regexp in
63 Compiled regular expression. Must have been returned previously
64 by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR.
66 If \fIstring\fR is just a portion of some other string, this argument
67 identifies the beginning of the larger string.
68 If it isn't the same as \fIstring\fR, then no \fB^\fR matches
71 Specifies which range is desired: 0 means the range of the entire
72 match, 1 or greater means the range that matched a parenthesized
74 .AP char **startPtr out
75 The address of the first character in the range is stored here, or
76 NULL if there is no such range.
78 The address of the character just after the last one in the range
79 is stored here, or NULL if there is no such range.
82 OR-ed combination of compilation flags. See below for more information.
83 .AP Tcl_Obj *objPtr in/out
84 An object which contains the string to check for a match with a
87 The character offset into the string where matching should begin.
88 The value of the offset has no impact on \fB^\fR matches. This
89 behavior is controlled by \fIeflags\fR.
91 The number of matching subexpressions that should be remembered for
92 later use. If this value is 0, then no subexpression match
93 information will be computed. If the value is -1, then
94 all of the matching subexpressions will be remembered. Any other
95 value will be taken as the maximum number of subexpressions to
98 OR-ed combination of the values TCL_REG_NOTBOL and TCL_REG_NOTEOL.
99 See below for more information.
100 .AP Tcl_RegExpInfo *infoPtr out
101 The address of the location where information about a previous match
102 should be stored by \fBTcl_RegExpGetInfo\fR.
108 \fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
109 matches \fIregexp\fR, where \fIregexp\fR is interpreted
110 as a regular expression using the rules in the \fBre_syntax\fR
112 If there is a match then \fBTcl_RegExpMatch\fR returns 1.
113 If there is no match then \fBTcl_RegExpMatch\fR returns 0.
114 If an error occurs in the matching process (e.g. \fIpattern\fR
115 is not a valid regular expression) then \fBTcl_RegExpMatch\fR
116 returns \-1 and leaves an error message in the interpreter result.
118 \fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it
119 operates on the Tcl objects \fIstrObj\fR and \fIpatObj\fR instead of
121 \fBTcl_RegExpMatchObj\fR is generally more efficient than
122 \fBTcl_RegExpMatch\fR, so it is the preferred interface.
125 \fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
126 provide lower-level access to the regular expression pattern matcher.
127 \fBTcl_RegExpCompile\fR compiles a regular expression string into
128 the internal form used for efficient pattern matching.
129 The return value is a token for this compiled form, which can be
130 used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
131 If an error occurs while compiling the regular expression then
132 \fBTcl_RegExpCompile\fR returns NULL and leaves an error message
133 in the interpreter result.
134 Note: the return value from \fBTcl_RegExpCompile\fR is only valid
135 up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to
136 retain these values for long periods of time.
138 \fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
139 It returns 1 if \fIstring\fR contains a range of characters that
140 match \fIregexp\fR, 0 if no match is found, and
141 \-1 if an error occurs.
142 In the case of an error, \fBTcl_RegExpExec\fR leaves an error
143 message in the interpreter result.
144 When searching a string for multiple matches of a pattern,
145 it is important to distinguish between the start of the original
146 string and the start of the current search.
147 For example, when searching for the second occurrence of a
148 match, the \fIstring\fR argument might point to the character
149 just after the first match; however, it is important for the
150 pattern matcher to know that this is not the start of the entire string,
151 so that it doesn't allow \fB^\fR atoms in the pattern to match.
152 The \fIstart\fR argument provides this information by pointing
153 to the start of the overall string containing \fIstring\fR.
154 \fIStart\fR will be less than or equal to \fIstring\fR; if it
155 is less than \fIstring\fR then no \fB^\fR matches will be allowed.
157 \fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR
158 returns; it provides detailed information about what ranges of
159 the string matched what parts of the pattern.
160 \fBTcl_RegExpRange\fR returns a pair of pointers in \fI*startPtr\fR
161 and \fI*endPtr\fR that identify a range of characters in
162 the source string for the most recent call to \fBTcl_RegExpExec\fR.
163 \fIIndex\fR indicates which of several ranges is desired:
164 if \fIindex\fR is 0, information is returned about the overall range
165 of characters that matched the entire pattern; otherwise,
166 information is returned about the range of characters that matched the
167 \fIindex\fR'th parenthesized subexpression within the pattern.
168 If there is no range corresponding to \fIindex\fR then NULL
169 is stored in \fI*firstPtr\fR and \fI*lastPtr\fR.
172 \fBTcl_GetRegExpFromObj\fR, \fBTcl_RegExpExecObj\fR, and
173 \fBTcl_RegExpGetInfo\fR are object interfaces that provide the most
174 direct control of Henry Spencer's regular expression library. For
175 users that need to modify compilation and execution options directly,
176 it is recommended that you use these interfaces instead of calling the
177 internal regexp functions. These interfaces handle the details of UTF
178 to Unicode translations as well as providing improved performance
179 through caching in the pattern and string objects.
181 \fBTcl_GetRegExpFromObj\fR attepts to return a compiled regular
182 expression from the \fIpatObj\fR. If the object does not already
183 contain a compiled regular expression it will attempt to create one
184 from the string in the object and assign it to the internal
185 representation of the \fIpatObj\fR. The return value of this function
186 is of type \fBTcl_RegExp\fR. The return value is a token for this
187 compiled form, which can be used in subsequent calls to
188 \fBTcl_RegExpExecObj\fR or \fBTcl_RegExpGetInfo\fR. If an error
189 occurs while compiling the regular expression then
190 \fBTcl_GetRegExpFromObj\fR returns NULL and leaves an error message in
191 the interpreter result. The regular expression token can be used as
192 long as the internal representation of \fIpatObj\fR refers to the
193 compiled form. The \fIeflags\fR argument is a bitwise OR of
194 zero or more of the following flags that control the compilation of
198 \fBTCL_REG_ADVANCED\fR
199 Compile advanced regular expressions (`AREs'). This mode corresponds to
200 the normal regular expression syntax accepted by the Tcl regexp and
203 \fBTCL_REG_EXTENDED\fR
204 Compile extended regular expressions (`EREs'). This mode corresponds
205 to the regular expression syntax recognized by Tcl 8.0 and earlier
209 Compile basic regular expressions (`BREs'). This mode corresponds
210 to the regular expression syntax recognized by common Unix utilities
211 like \fBsed\fR and \fBgrep\fR. This is the default if no flags are
214 \fBTCL_REG_EXPANDED\fR
215 Compile the regular expression (basic, extended, or advanced) using an
216 expanded syntax that allows comments and whitespace. This mode causes
217 non-backslashed non-bracket-expression white
218 space and #-to-end-of-line comments to be ignored.
221 Compile a literal string, with all characters treated as ordinary characters.
224 Compile for matching that ignores upper/lower case distinctions.
226 \fBTCL_REG_NEWLINE\fR
227 Compile for newline-sensitive matching. By default, newline is a
228 completely ordinary character with no special meaning in either
229 regular expressions or strings. With this flag, `[^' bracket
230 expressions and `.' never match newline, `^' matches an empty string
231 after any newline in addition to its normal function, and `$' matches
232 an empty string before any newline in addition to its normal function.
233 \fBREG_NEWLINE\fR is the bitwise OR of \fBREG_NLSTOP\fR and
237 Compile for partial newline-sensitive matching,
239 `[^' bracket expressions and `.' affected,
240 but not the behavior of `^' and `$'. In this mode, `[^' bracket
241 expressions and `.' never match newline.
244 Compile for inverse partial newline-sensitive matching,
246 of `^' and `$' (the ``anchors'') affected, but not the behavior of
247 `[^' bracket expressions and `.'. In this mode `^' matches an empty string
248 after any newline in addition to its normal function, and `$' matches
249 an empty string before any newline in addition to its normal function.
252 Compile for matching that reports only success or failure,
253 not what was matched. This reduces compile overhead and may improve
254 performance. Subsequent calls to \fBTcl_RegExpGetInfo\fR or
255 \fBTcl_RegExpRange\fR will not report any match information.
257 \fBTCL_REG_CANMATCH\fR
258 Compile for matching that reports the potential to complete a partial
259 match given more text (see below).
263 \fBTCL_REG_EXTENDED\fR,
264 \fBTCL_REG_ADVANCED\fR,
265 \fBTCL_REG_BASIC\fR, and
266 \fBTCL_REG_QUOTE\fR may be specified.
268 \fBTcl_RegExpExecObj\fR executes the regular expression pattern
269 matcher. It returns 1 if \fIobjPtr\fR contains a range of characters
270 that match \fIregexp\fR, 0 if no match is found, and \-1 if an error
271 occurs. In the case of an error, \fBTcl_RegExpExecObj\fR leaves an
272 error message in the interpreter result. The \fInmatches\fR value
273 indicates to the matcher how many subexpressions are of interest. If
274 \fInmatches\fR is 0, then no subexpression match information is
275 recorded, which may allow the matcher to make various optimizations.
276 If the value is -1, then all of the subexpressions in the pattern are
277 remembered. If the value is a positive integer, then only that number
278 of subexpressions will be remembered. Matching begins at the
279 specified Unicode character index given by \fIoffset\fR. Unlike
280 \fBTcl_RegExpExec\fR, the behavior of anchors is not affected by the
281 offset value. Instead the behavior of the anchors is explicitly
282 controlled by the \fIeflags\fR argument, which is a bitwise OR of
283 zero or more of the following flags:
287 The starting character will not be treated as the beginning of a
288 line or the beginning of the string, so `^' will not match there.
289 Note that this flag has no effect on how `\fB\eA\fR' matches.
292 The last character in the string will not be treated as the end of a
293 line or the end of the string, so '$' will not match there.
294 Note that this flag has no effect on how `\fB\eZ\fR' matches.
297 \fBTcl_RegExpGetInfo\fR retrieves information about the last match
298 performed with a given regular expression \fIregexp\fR. The
299 \fIinfoPtr\fR argument contains a pointer to a structure that is
303 typedef struct Tcl_RegExpInfo {
305 Tcl_RegExpIndices *\fImatches\fR;
306 long \fIextendStart\fR;
310 The \fInsubs\fR field contains a count of the number of parenthesized
311 subexpressions within the regular expression. If the \fBTCL_REG_NOSUB\fR
312 was used, then this value will be zero. The \fImatches\fR field
313 points to an array of \fInsubs\fR values that indicate the bounds of each
314 subexpression matched. The first element in the array refers to the
315 range matched by the entire regular expression, and subsequent elements
316 refer to the parenthesized subexpressions in the order that they
317 appear in the pattern. Each element is a structure that is defined as
321 typedef struct Tcl_RegExpIndices {
327 The \fIstart\fR and \fIend\fR values are Unicode character indices
328 relative to the offset location within \fIobjPtr\fR where matching began.
329 The \fIstart\fR index identifies the first character of the matched
330 subexpression. The \fIend\fR index identifies the first character
331 after the matched subexpression. If the subexpression matched the
332 empty string, then \fIstart\fR and \fIend\fR will be equal. If the
333 subexpression did not participate in the match, then \fIstart\fR and
334 \fIend\fR will be set to -1.
336 The \fIextendStart\fR field in \fBTcl_RegExpInfo\fR is only set if the
337 \fBTCL_REG_CANMATCH\fR flag was used. It indicates the first
338 character in the string where a match could occur. If a match was
339 found, this will be the same as the beginning of the current match.
340 If no match was found, then it indicates the earliest point at which a
341 match might occur if additional text is appended to the string.
346 match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegExpInfo
OSDN Git Service
