1Tcl_RegExpMatch(3)          Tcl Library Procedures          Tcl_RegExpMatch(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

13       #include <tcl.h>
14
15       int
16       Tcl_RegExpMatchObj(interp, textObj, patObj)
17
18       int
19       Tcl_RegExpMatch(interp, text, pattern)
20
21       Tcl_RegExp
22       Tcl_RegExpCompile(interp, pattern)
23
24       int
25       Tcl_RegExpExec(interp, regexp, text, start)
26
27       void
28       Tcl_RegExpRange(regexp, index, startPtr, endPtr)
29
30       Tcl_RegExp
31       Tcl_GetRegExpFromObj(interp, patObj, cflags)
32
33       int
34       Tcl_RegExpExecObj(interp, regexp, textObj, offset, nmatches, eflags)
35
36       void
37       Tcl_RegExpGetInfo(regexp, infoPtr)
38

ARGUMENTS

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
45       Tcl_Obj *textObj (in/out)            Refers to the object from which to
46                                            get   the  text  to  search.   The
47                                            internal  representation  of   the
48                                            object  may be converted to a form
49                                            that can be efficiently searched.
50
51       Tcl_Obj *patObj (in/out)             Refers to the object from which to
52                                            get a regular expression. The com‐
53                                            piled regular expression is cached
54                                            in the object.
55
56       char *text (in)                      Text  to search for a match with a
57                                            regular expression.
58
59       const char *pattern (in)             String in the form  of  a  regular
60                                            expression pattern.
61
62       Tcl_RegExp regexp (in)               Compiled regular expression.  Must
63                                            have been returned  previously  by
64                                            Tcl_GetRegExpFromObj or Tcl_RegEx‐
65                                            pCompile.
66
67       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
74       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
80       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
84       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
89       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
99       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
105       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
116       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
121       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

DESCRIPTION

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  objects  textObj  and
136       patObj  instead  of  UTF strings.  Tcl_RegExpMatchObj is generally more
137       efficient than Tcl_RegExpMatch, so it is the preferred interface.
138
139       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
150       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
166       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
178       Tcl_GetRegExpFromObj,   Tcl_RegExpExecObj,  and  Tcl_RegExpGetInfo  are
179       object 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 objects.
186
187       Tcl_GetRegExpFromObj attempts to return a compiled  regular  expression
188       from  the  patObj.   If  the object does not already contain a compiled
189       regular expression it will attempt to create one from the string in the
190       object 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
201         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
206         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
211         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
217         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
223         TCL_REG_QUOTE
224                Compile a literal string, with all characters treated as ordi‐
225                nary characters.
226
227         TCL_REG_NOCASE
228                Compile  for  matching  that ignores upper/lower case distinc‐
229                tions.
230
231         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
241         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
247         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
255         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
261         TCL_REG_CANMATCH
262                Compile for matching that reports the potential to complete  a
263                partial match given more text (see below).
264
265       Only  one  of  TCL_REG_EXTENDED,  TCL_REG_ADVANCED,  TCL_REG_BASIC, and
266       TCL_REG_QUOTE may be specified.
267
268       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
284         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
289         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
294       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
298              typedef struct Tcl_RegExpInfo {
299                      int nsubs;
300                      Tcl_RegExpIndices *matches;
301                      long extendStart;
302              } Tcl_RegExpInfo;
303
304       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
313              typedef struct Tcl_RegExpIndices {
314                      long start;
315                      long end;
316              } Tcl_RegExpIndices;
317
318       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
326       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

SEE ALSO

335       re_syntax(n)
336

KEYWORDS

338       match,  pattern,  regular expression, string, subexpression, Tcl_RegEx‐
339       pIndices, Tcl_RegExpInfo
340
341
342
343Tcl                                   8.1                   Tcl_RegExpMatch(3)
Impressum