tcl/doc/RegExp.3

   1 '\"
   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 Corporation
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 '\" RCS: @(#) $Id$
  10 '\"
  11 .so man.macros
  12 .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
  13 .BS
  14 .SH NAME
  15 Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- Pattern matching with regular expressions
  16 .SH SYNOPSIS
  17 .nf
  18 \fB#include <tcl.h>\fR
  19 .sp
  20 int
  21 \fBTcl_RegExpMatchObj\fR(\fIinterp\fR, \fIstrObj\fR, \fIpatObj\fR)
  22 .sp
  23 int
  24 \fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
  25 .sp
  26 Tcl_RegExp
  27 \fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
  28 .sp
  29 int
  30 \fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
  31 .sp
  32 \fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
  33 .VS 8.1
  34 .sp
  35 Tcl_RegExp
  36 \fBTcl_GetRegExpFromObj\fR(\fIinterp\fR, \fIpatObj\fR, \fIcflags\fR)
  37 .sp
  38 int
  39 \fBTcl_RegExpExecObj\fR(\fIinterp\fR, \fIregexp\fR, \fIobjPtr\fR, \fIoffset\fR, \fInmatches\fR, \fIeflags\fR)
  40 .sp
  41 \fBTcl_RegExpGetInfo\fR(\fIregexp\fR, \fIinfoPtr\fR)
  42 .VE 8.1
  43
  44 .SH ARGUMENTS
  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.
  49 .VS 8.1
  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.
  57 .VE 8.1
  58 .AP char *string in
  59 String to check for a match with a regular expression.
  60 .AP "CONST char" *pattern in
  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.
  65 .AP char *start in
  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
  69 will be allowed.
  70 .AP int index in
  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
  73 sub-expression.
  74 .VS 8.4
  75 .AP "CONST char" **startPtr out
  76 The address of the first character in the range is stored here, or
  77 NULL if there is no such range.
  78 .AP "CONST char" **endPtr out
  79 The address of the character just after the last one in the range
  80 is stored here, or NULL if there is no such range.
  81 .VE 8.4
  82 .VS 8.1
  83 .AP int cflags in
  84 OR-ed combination of compilation flags. See below for more information.
  85 .AP Tcl_Obj *objPtr in/out
  86 An object which contains the string to check for a match with a
  87 regular expression.
  88 .AP int offset in
  89 The character offset into the string where matching should begin.
  90 The value of the offset has no impact on \fB^\fR matches.  This
  91 behavior is controlled by \fIeflags\fR.
  92 .AP int nmatches in
  93 The number of matching subexpressions that should be remembered for
  94 later use.  If this value is 0, then no subexpression match
  95 information will be computed.  If the value is -1, then
  96 all of the matching subexpressions will be remembered.  Any other
  97 value will be taken as the maximum number of subexpressions to
  98 remember.
  99 .AP int eflags in
 100 OR-ed combination of the values TCL_REG_NOTBOL and TCL_REG_NOTEOL.
 101 See below for more information.
 102 .AP Tcl_RegExpInfo *infoPtr out
 103 The address of the location where information about a previous match
 104 should be stored by \fBTcl_RegExpGetInfo\fR.
 105 .VE 8.1
 106 .BE
 107
 108 .SH DESCRIPTION
 109 .PP
 110 \fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
 111 matches \fIregexp\fR, where \fIregexp\fR is interpreted
 112 as a regular expression using the rules in the \fBre_syntax\fR
 113 reference page.
 114 If there is a match then \fBTcl_RegExpMatch\fR returns 1.
 115 If there is no match then \fBTcl_RegExpMatch\fR returns 0.
 116 If an error occurs in the matching process (e.g. \fIpattern\fR
 117 is not a valid regular expression) then \fBTcl_RegExpMatch\fR
 118 returns \-1 and leaves an error message in the interpreter result.
 119 .VS 8.1.2
 120 \fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it
 121 operates on the Tcl objects \fIstrObj\fR and \fIpatObj\fR instead of
 122 UTF strings.
 123 \fBTcl_RegExpMatchObj\fR is generally more efficient than
 124 \fBTcl_RegExpMatch\fR, so it is the preferred interface.
 125 .VE 8.1.2
 126 .PP
 127 \fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
 128 provide lower-level access to the regular expression pattern matcher.
 129 \fBTcl_RegExpCompile\fR compiles a regular expression string into
 130 the internal form used for efficient pattern matching.
 131 The return value is a token for this compiled form, which can be
 132 used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
 133 If an error occurs while compiling the regular expression then
 134 \fBTcl_RegExpCompile\fR returns NULL and leaves an error message
 135 in the interpreter result.
 136 Note:  the return value from \fBTcl_RegExpCompile\fR is only valid
 137 up to the next call to \fBTcl_RegExpCompile\fR;  it is not safe to
 138 retain these values for long periods of time.
 139 .PP
 140 \fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
 141 It returns 1 if \fIstring\fR contains a range of characters that
 142 match \fIregexp\fR, 0 if no match is found, and
 143 \-1 if an error occurs.
 144 In the case of an error, \fBTcl_RegExpExec\fR leaves an error
 145 message in the interpreter result.
 146 When searching a string for multiple matches of a pattern,
 147 it is important to distinguish between the start of the original
 148 string and the start of the current search.
 149 For example, when searching for the second occurrence of a
 150 match, the \fIstring\fR argument might point to the character
 151 just after the first match;  however, it is important for the
 152 pattern matcher to know that this is not the start of the entire string,
 153 so that it doesn't allow \fB^\fR atoms in the pattern to match.
 154 The \fIstart\fR argument provides this information by pointing
 155 to the start of the overall string containing \fIstring\fR.
 156 \fIStart\fR will be less than or equal to \fIstring\fR;  if it
 157 is less than \fIstring\fR then no \fB^\fR matches will be allowed.
 158 .PP
 159 \fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR
 160 returns;  it provides detailed information about what ranges of
 161 the string matched what parts of the pattern.
 162 \fBTcl_RegExpRange\fR returns a pair of pointers in \fI*startPtr\fR
 163 and \fI*endPtr\fR that identify a range of characters in
 164 the source string for the most recent call to \fBTcl_RegExpExec\fR.
 165 \fIIndex\fR indicates which of several ranges is desired:
 166 if \fIindex\fR is 0, information is returned about the overall range
 167 of characters that matched the entire pattern;  otherwise,
 168 information is returned about the range of characters that matched the
 169 \fIindex\fR'th parenthesized subexpression within the pattern.
 170 If there is no range corresponding to \fIindex\fR then NULL
 171 is stored in \fI*startPtr\fR and \fI*endPtr\fR.
 172 .PP
 173 .VS 8.1
 174 \fBTcl_GetRegExpFromObj\fR, \fBTcl_RegExpExecObj\fR, and
 175 \fBTcl_RegExpGetInfo\fR are object interfaces that provide the most
 176 direct control of Henry Spencer's regular expression library.  For
 177 users that need to modify compilation and execution options directly,
 178 it is recommended that you use these interfaces instead of calling the
 179 internal regexp functions.  These interfaces handle the details of UTF
 180 to Unicode translations as well as providing improved performance
 181 through caching in the pattern and string objects.
 182 .PP
 183 \fBTcl_GetRegExpFromObj\fR attempts to return a compiled regular
 184 expression from the \fIpatObj\fR.  If the object does not already
 185 contain a compiled regular expression it will attempt to create one
 186 from the string in the object and assign it to the internal
 187 representation of the \fIpatObj\fR.  The return value of this function
 188 is of type \fBTcl_RegExp\fR.  The return value is a token for this
 189 compiled form, which can be used in subsequent calls to
 190 \fBTcl_RegExpExecObj\fR or \fBTcl_RegExpGetInfo\fR.  If an error
 191 occurs while compiling the regular expression then
 192 \fBTcl_GetRegExpFromObj\fR returns NULL and leaves an error message in
 193 the interpreter result.  The regular expression token can be used as
 194 long as the internal representation of \fIpatObj\fR refers to the
 195 compiled form.  The \fIeflags\fR argument is a bitwise OR of
 196 zero or more of the following flags that control the compilation of
 197 \fIpatObj\fR:
 198 .RS 2
 199 .TP
 200 \fBTCL_REG_ADVANCED\fR
 201 Compile advanced regular expressions (`AREs').  This mode corresponds to
 202 the normal regular expression syntax accepted by the Tcl regexp and
 203 regsub commands.
 204 .TP
 205 \fBTCL_REG_EXTENDED\fR
 206 Compile extended regular expressions (`EREs').  This mode corresponds
 207 to the regular expression syntax recognized by Tcl 8.0 and earlier
 208 versions.
 209 .TP
 210 \fBTCL_REG_BASIC\fR
 211 Compile basic regular expressions (`BREs').  This mode corresponds
 212 to the regular expression syntax recognized by common Unix utilities
 213 like \fBsed\fR and \fBgrep\fR.  This is the default if no flags are
 214 specified.
 215 .TP
 216 \fBTCL_REG_EXPANDED\fR
 217 Compile the regular expression (basic, extended, or advanced) using an
 218 expanded syntax that allows comments and whitespace.  This mode causes
 219 non-backslashed non-bracket-expression white
 220 space and #-to-end-of-line comments to be ignored.
 221 .TP
 222 \fBTCL_REG_QUOTE\fR
 223 Compile a literal string, with all characters treated as ordinary characters.
 224 .TP
 225 \fBTCL_REG_NOCASE\fR
 226 Compile for matching that ignores upper/lower case distinctions.
 227 .TP
 228 \fBTCL_REG_NEWLINE\fR
 229 Compile for newline-sensitive matching.  By default, newline is a
 230 completely ordinary character with no special meaning in either
 231 regular expressions or strings.  With this flag, `[^' bracket
 232 expressions and `.' never match newline, `^' matches an empty string
 233 after any newline in addition to its normal function, and `$' matches
 234 an empty string before any newline in addition to its normal function.
 235 \fBREG_NEWLINE\fR is the bitwise OR of \fBREG_NLSTOP\fR and
 236 \fBREG_NLANCH\fR.
 237 .TP
 238 \fBTCL_REG_NLSTOP\fR
 239 Compile for partial newline-sensitive matching,
 240 with the behavior of
 241 `[^' bracket expressions and `.' affected,
 242 but not the behavior of `^' and `$'.  In this mode, `[^' bracket
 243 expressions and `.' never match newline.
 244 .TP
 245 \fBTCL_REG_NLANCH\fR
 246 Compile for inverse partial newline-sensitive matching,
 247 with the behavior of
 248 of `^' and `$' (the ``anchors'') affected, but not the behavior of
 249 `[^' bracket expressions and `.'.  In this mode `^' matches an empty string
 250 after any newline in addition to its normal function, and `$' matches
 251 an empty string before any newline in addition to its normal function.
 252 .TP
 253 \fBTCL_REG_NOSUB\fR
 254 Compile for matching that reports only success or failure,
 255 not what was matched.  This reduces compile overhead and may improve
 256 performance.  Subsequent calls to \fBTcl_RegExpGetInfo\fR or
 257 \fBTcl_RegExpRange\fR will not report any match information.
 258 .TP
 259 \fBTCL_REG_CANMATCH\fR
 260 Compile for matching that reports the potential to complete a partial
 261 match given more text (see below).
 262 .RE
 263 .PP
 264 Only one of
 265 \fBTCL_REG_EXTENDED\fR,
 266 \fBTCL_REG_ADVANCED\fR,
 267 \fBTCL_REG_BASIC\fR, and
 268 \fBTCL_REG_QUOTE\fR may be specified.
 269 .PP
 270 \fBTcl_RegExpExecObj\fR executes the regular expression pattern
 271 matcher.  It returns 1 if \fIobjPtr\fR contains a range of characters
 272 that match \fIregexp\fR, 0 if no match is found, and \-1 if an error
 273 occurs.  In the case of an error, \fBTcl_RegExpExecObj\fR leaves an
 274 error message in the interpreter result.  The \fInmatches\fR value
 275 indicates to the matcher how many subexpressions are of interest.  If
 276 \fInmatches\fR is 0, then no subexpression match information is
 277 recorded, which may allow the matcher to make various optimizations.
 278 If the value is -1, then all of the subexpressions in the pattern are
 279 remembered.  If the value is a positive integer, then only that number
 280 of subexpressions will be remembered.  Matching begins at the
 281 specified Unicode character index given by \fIoffset\fR.  Unlike
 282 \fBTcl_RegExpExec\fR, the behavior of anchors is not affected by the
 283 offset value.  Instead the behavior of the anchors is explicitly
 284 controlled by the \fIeflags\fR argument, which is a bitwise OR of
 285 zero or more of the following flags:
 286 .RS 2
 287 .TP
 288 \fBTCL_REG_NOTBOL\fR
 289 The starting character will not be treated as the beginning of a
 290 line or the beginning of the string, so `^' will not match there.
 291 Note that this flag has no effect on how `\fB\eA\fR' matches.
 292 .TP
 293 \fBTCL_REG_NOTEOL\fR
 294 The last character in the string will not be treated as the end of a
 295 line or the end of the string, so '$' will not match there.
 296 Note that this flag has no effect on how `\fB\eZ\fR' matches.
 297 .RE
 298 .PP
 299 \fBTcl_RegExpGetInfo\fR retrieves information about the last match
 300 performed with a given regular expression \fIregexp\fR.  The
 301 \fIinfoPtr\fR argument contains a pointer to a structure that is
 302 defined as follows:
 303 .PP
 304 .CS
 305 typedef struct Tcl_RegExpInfo {
 306         int \fInsubs\fR;
 307         Tcl_RegExpIndices *\fImatches\fR;
 308         long \fIextendStart\fR;
 309 } Tcl_RegExpInfo;
 310 .CE
 311 .PP
 312 The \fInsubs\fR field contains a count of the number of parenthesized
 313 subexpressions within the regular expression.  If the \fBTCL_REG_NOSUB\fR
 314 was used, then this value will be zero.  The \fImatches\fR field
 315 points to an array of \fInsubs\fR values that indicate the bounds of each
 316 subexpression matched.  The first element in the array refers to the
 317 range matched by the entire regular expression, and subsequent elements
 318 refer to the parenthesized subexpressions in the order that they
 319 appear in the pattern.  Each element is a structure that is defined as
 320 follows:
 321 .PP
 322 .CS
 323 typedef struct Tcl_RegExpIndices {
 324         long \fIstart\fR;
 325         long \fIend\fR;
 326 } Tcl_RegExpIndices;
 327 .CE
 328 .PP
 329 The \fIstart\fR and \fIend\fR values are Unicode character indices
 330 relative to the offset location within \fIobjPtr\fR where matching began.
 331 The \fIstart\fR index identifies the first character of the matched
 332 subexpression.  The \fIend\fR index identifies the first character
 333 after the matched subexpression.  If the subexpression matched the
 334 empty string, then \fIstart\fR and \fIend\fR will be equal.  If the
 335 subexpression did not participate in the match, then \fIstart\fR and
 336 \fIend\fR will be set to -1.
 337 .PP
 338 The \fIextendStart\fR field in \fBTcl_RegExpInfo\fR is only set if the
 339 \fBTCL_REG_CANMATCH\fR flag was used.  It indicates the first
 340 character in the string where a match could occur.  If a match was
 341 found, this will be the same as the beginning of the current match.
 342 If no match was found, then it indicates the earliest point at which a
 343 match might occur if additional text is appended to the string.
 344 .VE 8.1
 345 .SH "SEE ALSO"
 346 re_syntax(n)
 347 .SH KEYWORDS
 348 match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegExpInfo