1Tcl_RegExpMatch(3) Tcl Library Procedures Tcl_RegExpMatch(3)
2______________________________________________________________________________
6
8 Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange,
9 Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_Reg‐
10 ExpGetInfo - Pattern matching with regular expressions
11
13 #include <tcl.h>
14 int
16 Tcl_RegExpMatchObj(interp, textObj, patObj)
17 int
19 Tcl_RegExpMatch(interp, text, pattern)
20 Tcl_RegExp
22 Tcl_RegExpCompile(interp, pattern)
23 int
25 Tcl_RegExpExec(interp, regexp, text, start)
26 void
28 Tcl_RegExpRange(regexp, index, startPtr, endPtr)
29 Tcl_RegExp
31 Tcl_GetRegExpFromObj(interp, patObj, cflags)
32 int
34 Tcl_RegExpExecObj(interp, regexp, textObj, offset, nmatches, eflags)
35 void
37 Tcl_RegExpGetInfo(regexp, infoPtr)
38
40 Tcl_Interp *interp (in) Tcl interpreter to use for error
41 reporting. The interpreter may be
42 NULL if no error reporting is
43 desired.
44 Tcl_Obj *textObj (in/out) Refers to the value from which to
46 get the text to search. The
47 internal representation of the
48 value may be converted to a form
49 that can be efficiently searched.
50 Tcl_Obj *patObj (in/out) Refers to the value from which to
52 get a regular expression. The com‐
53 piled regular expression is cached
54 in the value.
55 char *text (in) Text to search for a match with a
57 regular expression.
58 const char *pattern (in) String in the form of a regular
60 expression pattern.
61 Tcl_RegExp regexp (in) Compiled regular expression. Must
63 have been returned previously by
64 Tcl_GetRegExpFromObj or Tcl_RegEx‐
65 pCompile.
66 char *start (in) If text is just a portion of some
68 other string, this argument iden‐
69 tifies the beginning of the larger
70 string. If it is not the same as
71 text, then no “^” matches will be
72 allowed.
73 int index (in) Specifies which range is desired:
75 0 means the range of the entire
76 match, 1 or greater means the
77 range that matched a parenthesized
78 sub-expression.
79 const char **startPtr (out) The address of the first character
81 in the range is stored here, or
82 NULL if there is no such range.
83 const char **endPtr (out) The address of the character just
85 after the last one in the range is
86 stored here, or NULL if there is
87 no such range.
88 int cflags (in) OR-ed combination of the compila‐
90 tion flags TCL_REG_ADVANCED,
91 TCL_REG_EXTENDED, TCL_REG_BASIC,
92 TCL_REG_EXPANDED, TCL_REG_QUOTE,
93 TCL_REG_NOCASE, TCL_REG_NEWLINE,
94 TCL_REG_NLSTOP, TCL_REG_NLANCH,
95 TCL_REG_NOSUB, and TCL_REG_CAN‐
96 MATCH. See below for more informa‐
97 tion.
98 int offset (in) The character offset into the text
100 where matching should begin. The
101 value of the offset has no impact
102 on ^ matches. This behavior is
103 controlled by eflags.
104 int nmatches (in) The number of matching subexpres‐
106 sions that should be remembered
107 for later use. If this value is
108 0, then no subexpression match
109 information will be computed. If
110 the value is -1, then all of the
111 matching subexpressions will be
112 remembered. Any other value will
113 be taken as the maximum number of
114 subexpressions to remember.
115 int eflags (in) OR-ed combination of the execution
117 flags TCL_REG_NOTBOL and
118 TCL_REG_NOTEOL. See below for more
119 information.
120 Tcl_RegExpInfo *infoPtr (out) The address of the location where
122 information about a previous match
123 should be stored by Tcl_RegExpGet‐
124 Info.
125______________________________________________________________________________
126
128 Tcl_RegExpMatch determines whether its pattern argument matches regexp,
129 where regexp is interpreted as a regular expression using the rules in
130 the re_syntax reference page. If there is a match then Tcl_RegExpMatch
131 returns 1. If there is no match then Tcl_RegExpMatch returns 0. If an
132 error occurs in the matching process (e.g. pattern is not a valid regu‐
133 lar expression) then Tcl_RegExpMatch returns -1 and leaves an error
134 message in the interpreter result. Tcl_RegExpMatchObj is similar to
135 Tcl_RegExpMatch except it operates on the Tcl values textObj and patObj
136 instead of UTF strings. Tcl_RegExpMatchObj is generally more efficient
137 than Tcl_RegExpMatch, so it is the preferred interface.
138 Tcl_RegExpCompile, Tcl_RegExpExec, and Tcl_RegExpRange provide lower-
140 level access to the regular expression pattern matcher. Tcl_RegExpCom‐
141 pile compiles a regular expression string into the internal form used
142 for efficient pattern matching. The return value is a token for this
143 compiled form, which can be used in subsequent calls to Tcl_RegExpExec
144 or Tcl_RegExpRange. If an error occurs while compiling the regular
145 expression then Tcl_RegExpCompile returns NULL and leaves an error mes‐
146 sage in the interpreter result. Note: the return value from Tcl_Reg‐
147 ExpCompile is only valid up to the next call to Tcl_RegExpCompile; it
148 is not safe to retain these values for long periods of time.
149 Tcl_RegExpExec executes the regular expression pattern matcher. It
151 returns 1 if text contains a range of characters that match regexp, 0
152 if no match is found, and -1 if an error occurs. In the case of an
153 error, Tcl_RegExpExec leaves an error message in the interpreter
154 result. When searching a string for multiple matches of a pattern, it
155 is important to distinguish between the start of the original string
156 and the start of the current search. For example, when searching for
157 the second occurrence of a match, the text argument might point to the
158 character just after the first match; however, it is important for the
159 pattern matcher to know that this is not the start of the entire
160 string, so that it does not allow “^” atoms in the pattern to match.
161 The start argument provides this information by pointing to the start
162 of the overall string containing text. Start will be less than or
163 equal to text; if it is less than text then no ^ matches will be
164 allowed.
165 Tcl_RegExpRange may be invoked after Tcl_RegExpExec returns; it pro‐
167 vides detailed information about what ranges of the string matched what
168 parts of the pattern. Tcl_RegExpRange returns a pair of pointers in
169 *startPtr and *endPtr that identify a range of characters in the source
170 string for the most recent call to Tcl_RegExpExec. Index indicates
171 which of several ranges is desired: if index is 0, information is
172 returned about the overall range of characters that matched the entire
173 pattern; otherwise, information is returned about the range of charac‐
174 ters that matched the index'th parenthesized subexpression within the
175 pattern. If there is no range corresponding to index then NULL is
176 stored in *startPtr and *endPtr.
177 Tcl_GetRegExpFromObj, Tcl_RegExpExecObj, and Tcl_RegExpGetInfo are
179 value interfaces that provide the most direct control of Henry
180 Spencer's regular expression library. For users that need to modify
181 compilation and execution options directly, it is recommended that you
182 use these interfaces instead of calling the internal regexp functions.
183 These interfaces handle the details of UTF to Unicode translations as
184 well as providing improved performance through caching in the pattern
185 and string values.
186 Tcl_GetRegExpFromObj attempts to return a compiled regular expression
188 from the patObj. If the value does not already contain a compiled reg‐
189 ular expression it will attempt to create one from the string in the
190 value and assign it to the internal representation of the patObj. The
191 return value of this function is of type Tcl_RegExp. The return value
192 is a token for this compiled form, which can be used in subsequent
193 calls to Tcl_RegExpExecObj or Tcl_RegExpGetInfo. If an error occurs
194 while compiling the regular expression then Tcl_GetRegExpFromObj
195 returns NULL and leaves an error message in the interpreter result.
196 The regular expression token can be used as long as the internal repre‐
197 sentation of patObj refers to the compiled form. The cflags argument
198 is a bit-wise OR of zero or more of the following flags that control
199 the compilation of patObj:
200 TCL_REG_ADVANCED
202 Compile advanced regular expressions (“ARE”s). This mode cor‐
203 responds to the normal regular expression syntax accepted by
204 the Tcl regexp and regsub commands.
205 TCL_REG_EXTENDED
207 Compile extended regular expressions (“ERE”s). This mode cor‐
208 responds to the regular expression syntax recognized by Tcl
209 8.0 and earlier versions.
210 TCL_REG_BASIC
212 Compile basic regular expressions (“BRE”s). This mode corre‐
213 sponds to the regular expression syntax recognized by common
214 Unix utilities like sed and grep. This is the default if no
215 flags are specified.
216 TCL_REG_EXPANDED
218 Compile the regular expression (basic, extended, or advanced)
219 using an expanded syntax that allows comments and whitespace.
220 This mode causes non-backslashed non-bracket-expression white
221 space and #-to-end-of-line comments to be ignored.
222 TCL_REG_QUOTE
224 Compile a literal string, with all characters treated as ordi‐
225 nary characters.
226 TCL_REG_NOCASE
228 Compile for matching that ignores upper/lower case distinc‐
229 tions.
230 TCL_REG_NEWLINE
232 Compile for newline-sensitive matching. By default, newline
233 is a completely ordinary character with no special meaning in
234 either regular expressions or strings. With this flag, “[^”
235 bracket expressions and “.” never match newline, “^” matches
236 an empty string after any newline in addition to its normal
237 function, and “$” matches an empty string before any newline
238 in addition to its normal function. REG_NEWLINE is the bit-
239 wise OR of REG_NLSTOP and REG_NLANCH.
240 TCL_REG_NLSTOP
242 Compile for partial newline-sensitive matching, with the
243 behavior of “[^” bracket expressions and “.” affected, but
244 not the behavior of “^” and “$”. In this mode, “[^” bracket
245 expressions and “.” never match newline.
246 TCL_REG_NLANCH
248 Compile for inverse partial newline-sensitive matching, with
249 the behavior of “^” and “$” (the “anchors”) affected, but not
250 the behavior of “[^” bracket expressions and “.”. In this
251 mode “^” matches an empty string after any newline in addition
252 to its normal function, and “$” matches an empty string before
253 any newline in addition to its normal function.
254 TCL_REG_NOSUB
256 Compile for matching that reports only success or failure, not
257 what was matched. This reduces compile overhead and may
258 improve performance. Subsequent calls to Tcl_RegExpGetInfo or
259 Tcl_RegExpRange will not report any match information.
260 TCL_REG_CANMATCH
262 Compile for matching that reports the potential to complete a
263 partial match given more text (see below).
264 Only one of TCL_REG_EXTENDED, TCL_REG_ADVANCED, TCL_REG_BASIC, and
266 TCL_REG_QUOTE may be specified.
267 Tcl_RegExpExecObj executes the regular expression pattern matcher. It
269 returns 1 if objPtr contains a range of characters that match regexp, 0
270 if no match is found, and -1 if an error occurs. In the case of an
271 error, Tcl_RegExpExecObj leaves an error message in the interpreter
272 result. The nmatches value indicates to the matcher how many subex‐
273 pressions are of interest. If nmatches is 0, then no subexpression
274 match information is recorded, which may allow the matcher to make var‐
275 ious optimizations. If the value is -1, then all of the subexpressions
276 in the pattern are remembered. If the value is a positive integer,
277 then only that number of subexpressions will be remembered. Matching
278 begins at the specified Unicode character index given by offset.
279 Unlike Tcl_RegExpExec, the behavior of anchors is not affected by the
280 offset value. Instead the behavior of the anchors is explicitly con‐
281 trolled by the eflags argument, which is a bit-wise OR of zero or more
282 of the following flags:
283 TCL_REG_NOTBOL
285 The starting character will not be treated as the beginning of
286 a line or the beginning of the string, so “^” will not match
287 there. Note that this flag has no effect on how “\A” matches.
288 TCL_REG_NOTEOL
290 The last character in the string will not be treated as the
291 end of a line or the end of the string, so “$” will not match
292 there. Note that this flag has no effect on how “\Z” matches.
293 Tcl_RegExpGetInfo retrieves information about the last match performed
295 with a given regular expression regexp. The infoPtr argument contains
296 a pointer to a structure that is defined as follows:
297 typedef struct Tcl_RegExpInfo {
299 int nsubs;
300 Tcl_RegExpIndices *matches;
301 long extendStart;
302 } Tcl_RegExpInfo;
303 The nsubs field contains a count of the number of parenthesized subex‐
305 pressions within the regular expression. If the TCL_REG_NOSUB was
306 used, then this value will be zero. The matches field points to an
307 array of nsubs+1 values that indicate the bounds of each subexpression
308 matched. The first element in the array refers to the range matched by
309 the entire regular expression, and subsequent elements refer to the
310 parenthesized subexpressions in the order that they appear in the pat‐
311 tern. Each element is a structure that is defined as follows:
312 typedef struct Tcl_RegExpIndices {
314 long start;
315 long end;
316 } Tcl_RegExpIndices;
317 The start and end values are Unicode character indices relative to the
319 offset location within objPtr where matching began. The start index
320 identifies the first character of the matched subexpression. The end
321 index identifies the first character after the matched subexpression.
322 If the subexpression matched the empty string, then start and end will
323 be equal. If the subexpression did not participate in the match, then
324 start and end will be set to -1.
325 The extendStart field in Tcl_RegExpInfo is only set if the TCL_REG_CAN‐
327 MATCH flag was used. It indicates the first character in the string
328 where a match could occur. If a match was found, this will be the same
329 as the beginning of the current match. If no match was found, then it
330 indicates the earliest point at which a match might occur if additional
331 text is appended to the string. If it is no match is possible even
332 with further text, this field will be set to -1.
333
335 re_syntax(n)
336
338 match, pattern, regular expression, string, subexpression, Tcl_RegEx‐
339 pIndices, Tcl_RegExpInfo
340Tcl 8.1 Tcl_RegExpMatch(3)