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
6 '\" See the file "license.terms" for information on usage and redistribution
7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
9 .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
10 .\" The -*- nroff -*- definitions below are for supplemental macros used
11 .\" in Tcl/Tk manual entries.
13 .\" .AP type name in/out ?indent?
14 .\" Start paragraph describing an argument to a library procedure.
15 .\" type is type of argument (int, etc.), in/out is either "in", "out",
16 .\" or "in/out" to describe whether procedure reads or modifies arg,
17 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 .\" needed; use .AS below instead)
21 .\" Give maximum sizes of arguments for setting tab stops. Type and
22 .\" name are examples of largest possible arguments that will be passed
23 .\" to .AP later. If args are omitted, default tab stops are used.
26 .\" Start box enclosure. From here until next .BE, everything will be
27 .\" enclosed in one large box.
30 .\" End of box enclosure.
33 .\" Begin code excerpt.
38 .\" .VS ?version? ?br?
39 .\" Begin vertical sidebar, for use in marking newly-changed parts
40 .\" of man pages. The first argument is ignored and used for recording
41 .\" the version when the .VS was added, so that the sidebars can be
42 .\" found and removed when they reach a certain age. If another argument
43 .\" is present, then a line break is forced before starting the sidebar.
46 .\" End of vertical sidebar.
49 .\" Begin an indented unfilled display.
52 .\" End of indented unfilled display.
55 .\" Start of list of standard options for a Tk widget. The manpage
56 .\" argument defines where to look up the standard options; if
57 .\" omitted, defaults to "options". The options follow on successive
58 .\" lines, in three columns separated by tabs.
61 .\" End of list of standard options for a Tk widget.
63 .\" .OP cmdName dbName dbClass
64 .\" Start of description of a specific option. cmdName gives the
65 .\" option's name as specified in the class command, dbName gives
66 .\" the option's name in the option database, and dbClass gives
67 .\" the option's class in the option database.
70 .\" Print arg1 underlined, then print arg2 normally.
73 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
76 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
77 .\" (for trailing punctuation) and then a closing parenthesis.
79 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
83 .\" # Start an argument description
87 . ie !"\\$2"" .TP \\n()Cu
92 \&\\$1 \\fI\\$2\\fP (\\$3)
105 .\" # define tabbing values for .AP
108 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
111 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
112 .nr )C \\n()Bu+\\w'(in/out)'u+2n
114 .AS Tcl_Interp Tcl_CreateInterp in/out
115 .\" # BS - start boxed text
116 .\" # ^y = starting y location
124 .if n \l'\\n(.lu\(ul'
127 .\" # BE - end boxed text (draw box now)
132 .ie n \l'\\n(^lu\(ul'
134 .\" Draw four-sided box normally, but don't draw top of
135 .\" box if the box started on an earlier page.
137 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
147 .\" # VS - start vertical sidebar
148 .\" # ^Y = starting y location
149 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
153 .ie n 'mc \s12\(br\s0
156 .\" # VE - end of vertical sidebar
164 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
171 .\" # Special macro to handle page bottom: finish off current
172 .\" # box/sidebar if in box/sidebar mode, then invoked standard
173 .\" # page bottom macro.
180 .\" Draw three-sided box if this is the box's first page,
181 .\" draw two sides but no top otherwise.
182 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
183 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
186 .nr ^x \\n(^tu+1v-\\n(^Yu
187 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
200 .\" # DS - begin display
206 .\" # DE - end display
212 .\" # SO - start of list of standard options
214 'ie '\\$1'' .ds So \\fBoptions\\fR
215 'el .ds So \\fB\\$1\\fR
216 .SH "STANDARD OPTIONS"
222 .\" # SE - end of list of standard options
227 See the \\*(So manual entry for details on the standard options.
229 .\" # OP - start of full description for a single option
234 Command-Line Name: \\fB\\$1\\fR
235 Database Name: \\fB\\$2\\fR
236 Database Class: \\fB\\$3\\fR
240 .\" # CS - begin code excerpt
246 .\" # CE - end code excerpt
251 .\" # UL - underline word
255 .\" # QW - apply quotation marks to word
257 .ie '\\*(lq'"' ``\\$1''\\$2
258 .\"" fix emacs highlighting
259 .el \\*(lq\\$1\\*(rq\\$2
261 .\" # PQ - apply parens and quotation marks to word
263 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
264 .\"" fix emacs highlighting
265 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
267 .\" # QR - quoted range
269 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
270 .\"" fix emacs highlighting
271 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
273 .\" # MT - "empty" string
279 Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- Pattern matching with regular expressions
282 \fB#include <tcl.h>\fR
285 \fBTcl_RegExpMatchObj\fR(\fIinterp\fR, \fItextObj\fR, \fIpatObj\fR)
288 \fBTcl_RegExpMatch\fR(\fIinterp\fR, \fItext\fR, \fIpattern\fR)
291 \fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
294 \fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fItext\fR, \fIstart\fR)
297 \fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
300 \fBTcl_GetRegExpFromObj\fR(\fIinterp\fR, \fIpatObj\fR, \fIcflags\fR)
303 \fBTcl_RegExpExecObj\fR(\fIinterp\fR, \fIregexp\fR, \fItextObj\fR, \fIoffset\fR, \fInmatches\fR, \fIeflags\fR)
306 \fBTcl_RegExpGetInfo\fR(\fIregexp\fR, \fIinfoPtr\fR)
309 .AS Tcl_RegExpInfo *interp in/out
310 .AP Tcl_Interp *interp in
311 Tcl interpreter to use for error reporting. The interpreter may be
312 NULL if no error reporting is desired.
313 .AP Tcl_Obj *textObj in/out
314 Refers to the value from which to get the text to search. The
315 internal representation of the value may be converted to a form that
316 can be efficiently searched.
317 .AP Tcl_Obj *patObj in/out
318 Refers to the value from which to get a regular expression. The
319 compiled regular expression is cached in the value.
321 Text to search for a match with a regular expression.
322 .AP "const char" *pattern in
323 String in the form of a regular expression pattern.
324 .AP Tcl_RegExp regexp in
325 Compiled regular expression. Must have been returned previously
326 by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR.
328 If \fItext\fR is just a portion of some other string, this argument
329 identifies the beginning of the larger string.
330 If it is not the same as \fItext\fR, then no
332 matches will be allowed.
334 Specifies which range is desired: 0 means the range of the entire
335 match, 1 or greater means the range that matched a parenthesized
337 .AP "const char" **startPtr out
338 The address of the first character in the range is stored here, or
339 NULL if there is no such range.
340 .AP "const char" **endPtr out
341 The address of the character just after the last one in the range
342 is stored here, or NULL if there is no such range.
344 OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\fR,
345 \fBTCL_REG_EXTENDED\fR, \fBTCL_REG_BASIC\fR, \fBTCL_REG_EXPANDED\fR,
346 \fBTCL_REG_QUOTE\fR, \fBTCL_REG_NOCASE\fR, \fBTCL_REG_NEWLINE\fR,
347 \fBTCL_REG_NLSTOP\fR, \fBTCL_REG_NLANCH\fR, \fBTCL_REG_NOSUB\fR, and
348 \fBTCL_REG_CANMATCH\fR. See below for more information.
350 The character offset into the text where matching should begin.
351 The value of the offset has no impact on \fB^\fR matches. This
352 behavior is controlled by \fIeflags\fR.
354 The number of matching subexpressions that should be remembered for
355 later use. If this value is 0, then no subexpression match
356 information will be computed. If the value is \-1, then
357 all of the matching subexpressions will be remembered. Any other
358 value will be taken as the maximum number of subexpressions to
361 OR-ed combination of the execution flags \fBTCL_REG_NOTBOL\fR and
362 \fBTCL_REG_NOTEOL\fR. See below for more information.
363 .AP Tcl_RegExpInfo *infoPtr out
364 The address of the location where information about a previous match
365 should be stored by \fBTcl_RegExpGetInfo\fR.
369 \fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
370 matches \fIregexp\fR, where \fIregexp\fR is interpreted
371 as a regular expression using the rules in the \fBre_syntax\fR
373 If there is a match then \fBTcl_RegExpMatch\fR returns 1.
374 If there is no match then \fBTcl_RegExpMatch\fR returns 0.
375 If an error occurs in the matching process (e.g. \fIpattern\fR
376 is not a valid regular expression) then \fBTcl_RegExpMatch\fR
377 returns \-1 and leaves an error message in the interpreter result.
378 \fBTcl_RegExpMatchObj\fR is similar to \fBTcl_RegExpMatch\fR except it
379 operates on the Tcl values \fItextObj\fR and \fIpatObj\fR instead of
381 \fBTcl_RegExpMatchObj\fR is generally more efficient than
382 \fBTcl_RegExpMatch\fR, so it is the preferred interface.
384 \fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
385 provide lower-level access to the regular expression pattern matcher.
386 \fBTcl_RegExpCompile\fR compiles a regular expression string into
387 the internal form used for efficient pattern matching.
388 The return value is a token for this compiled form, which can be
389 used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
390 If an error occurs while compiling the regular expression then
391 \fBTcl_RegExpCompile\fR returns NULL and leaves an error message
392 in the interpreter result.
393 Note: the return value from \fBTcl_RegExpCompile\fR is only valid
394 up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to
395 retain these values for long periods of time.
397 \fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
398 It returns 1 if \fItext\fR contains a range of characters that
399 match \fIregexp\fR, 0 if no match is found, and
400 \-1 if an error occurs.
401 In the case of an error, \fBTcl_RegExpExec\fR leaves an error
402 message in the interpreter result.
403 When searching a string for multiple matches of a pattern,
404 it is important to distinguish between the start of the original
405 string and the start of the current search.
406 For example, when searching for the second occurrence of a
407 match, the \fItext\fR argument might point to the character
408 just after the first match; however, it is important for the
409 pattern matcher to know that this is not the start of the entire string,
410 so that it does not allow
412 atoms in the pattern to match.
413 The \fIstart\fR argument provides this information by pointing
414 to the start of the overall string containing \fItext\fR.
415 \fIStart\fR will be less than or equal to \fItext\fR; if it
416 is less than \fItext\fR then no \fB^\fR matches will be allowed.
418 \fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR
419 returns; it provides detailed information about what ranges of
420 the string matched what parts of the pattern.
421 \fBTcl_RegExpRange\fR returns a pair of pointers in \fI*startPtr\fR
422 and \fI*endPtr\fR that identify a range of characters in
423 the source string for the most recent call to \fBTcl_RegExpExec\fR.
424 \fIIndex\fR indicates which of several ranges is desired:
425 if \fIindex\fR is 0, information is returned about the overall range
426 of characters that matched the entire pattern; otherwise,
427 information is returned about the range of characters that matched the
428 \fIindex\fR'th parenthesized subexpression within the pattern.
429 If there is no range corresponding to \fIindex\fR then NULL
430 is stored in \fI*startPtr\fR and \fI*endPtr\fR.
432 \fBTcl_GetRegExpFromObj\fR, \fBTcl_RegExpExecObj\fR, and
433 \fBTcl_RegExpGetInfo\fR are value interfaces that provide the most
434 direct control of Henry Spencer's regular expression library. For
435 users that need to modify compilation and execution options directly,
436 it is recommended that you use these interfaces instead of calling the
437 internal regexp functions. These interfaces handle the details of UTF
438 to Unicode translations as well as providing improved performance
439 through caching in the pattern and string values.
441 \fBTcl_GetRegExpFromObj\fR attempts to return a compiled regular
442 expression from the \fIpatObj\fR. If the value does not already
443 contain a compiled regular expression it will attempt to create one
444 from the string in the value and assign it to the internal
445 representation of the \fIpatObj\fR. The return value of this function
446 is of type \fBTcl_RegExp\fR. The return value is a token for this
447 compiled form, which can be used in subsequent calls to
448 \fBTcl_RegExpExecObj\fR or \fBTcl_RegExpGetInfo\fR. If an error
449 occurs while compiling the regular expression then
450 \fBTcl_GetRegExpFromObj\fR returns NULL and leaves an error message in
451 the interpreter result. The regular expression token can be used as
452 long as the internal representation of \fIpatObj\fR refers to the
453 compiled form. The \fIcflags\fR argument is a bit-wise OR of
454 zero or more of the following flags that control the compilation of
458 \fBTCL_REG_ADVANCED\fR
459 Compile advanced regular expressions
461 This mode corresponds to
462 the normal regular expression syntax accepted by the Tcl \fBregexp\fR and
463 \fBregsub\fR commands.
465 \fBTCL_REG_EXTENDED\fR
466 Compile extended regular expressions
468 This mode corresponds
469 to the regular expression syntax recognized by Tcl 8.0 and earlier
473 Compile basic regular expressions
475 This mode corresponds
476 to the regular expression syntax recognized by common Unix utilities
477 like \fBsed\fR and \fBgrep\fR. This is the default if no flags are
480 \fBTCL_REG_EXPANDED\fR
481 Compile the regular expression (basic, extended, or advanced) using an
482 expanded syntax that allows comments and whitespace. This mode causes
483 non-backslashed non-bracket-expression white
484 space and #-to-end-of-line comments to be ignored.
487 Compile a literal string, with all characters treated as ordinary characters.
490 Compile for matching that ignores upper/lower case distinctions.
492 \fBTCL_REG_NEWLINE\fR
493 Compile for newline-sensitive matching. By default, newline is a
494 completely ordinary character with no special meaning in either
495 regular expressions or strings. With this flag,
497 bracket expressions and
501 matches an empty string
502 after any newline in addition to its normal function, and
505 an empty string before any newline in addition to its normal function.
506 \fBREG_NEWLINE\fR is the bit-wise OR of \fBREG_NLSTOP\fR and
510 Compile for partial newline-sensitive matching,
513 bracket expressions and
515 affected, but not the behavior of
521 bracket expressions and
526 Compile for inverse partial newline-sensitive matching,
533 affected, but not the behavior of
535 bracket expressions and
539 matches an empty string
540 after any newline in addition to its normal function, and
543 an empty string before any newline in addition to its normal function.
546 Compile for matching that reports only success or failure,
547 not what was matched. This reduces compile overhead and may improve
548 performance. Subsequent calls to \fBTcl_RegExpGetInfo\fR or
549 \fBTcl_RegExpRange\fR will not report any match information.
551 \fBTCL_REG_CANMATCH\fR
552 Compile for matching that reports the potential to complete a partial
553 match given more text (see below).
557 \fBTCL_REG_EXTENDED\fR,
558 \fBTCL_REG_ADVANCED\fR,
559 \fBTCL_REG_BASIC\fR, and
560 \fBTCL_REG_QUOTE\fR may be specified.
562 \fBTcl_RegExpExecObj\fR executes the regular expression pattern
563 matcher. It returns 1 if \fIobjPtr\fR contains a range of characters
564 that match \fIregexp\fR, 0 if no match is found, and \-1 if an error
565 occurs. In the case of an error, \fBTcl_RegExpExecObj\fR leaves an
566 error message in the interpreter result. The \fInmatches\fR value
567 indicates to the matcher how many subexpressions are of interest. If
568 \fInmatches\fR is 0, then no subexpression match information is
569 recorded, which may allow the matcher to make various optimizations.
570 If the value is \-1, then all of the subexpressions in the pattern are
571 remembered. If the value is a positive integer, then only that number
572 of subexpressions will be remembered. Matching begins at the
573 specified Unicode character index given by \fIoffset\fR. Unlike
574 \fBTcl_RegExpExec\fR, the behavior of anchors is not affected by the
575 offset value. Instead the behavior of the anchors is explicitly
576 controlled by the \fIeflags\fR argument, which is a bit-wise OR of
577 zero or more of the following flags:
581 The starting character will not be treated as the beginning of a
582 line or the beginning of the string, so
584 will not match there.
585 Note that this flag has no effect on how
590 The last character in the string will not be treated as the end of a
591 line or the end of the string, so
593 will not match there.
594 Note that this flag has no effect on how
599 \fBTcl_RegExpGetInfo\fR retrieves information about the last match
600 performed with a given regular expression \fIregexp\fR. The
601 \fIinfoPtr\fR argument contains a pointer to a structure that is
605 typedef struct Tcl_RegExpInfo {
607 Tcl_RegExpIndices *\fImatches\fR;
608 long \fIextendStart\fR;
609 } \fBTcl_RegExpInfo\fR;
612 The \fInsubs\fR field contains a count of the number of parenthesized
613 subexpressions within the regular expression. If the \fBTCL_REG_NOSUB\fR
614 was used, then this value will be zero. The \fImatches\fR field
615 points to an array of \fInsubs\fR+1 values that indicate the bounds of each
616 subexpression matched. The first element in the array refers to the
617 range matched by the entire regular expression, and subsequent elements
618 refer to the parenthesized subexpressions in the order that they
619 appear in the pattern. Each element is a structure that is defined as
623 typedef struct Tcl_RegExpIndices {
626 } \fBTcl_RegExpIndices\fR;
629 The \fIstart\fR and \fIend\fR values are Unicode character indices
630 relative to the offset location within \fIobjPtr\fR where matching began.
631 The \fIstart\fR index identifies the first character of the matched
632 subexpression. The \fIend\fR index identifies the first character
633 after the matched subexpression. If the subexpression matched the
634 empty string, then \fIstart\fR and \fIend\fR will be equal. If the
635 subexpression did not participate in the match, then \fIstart\fR and
636 \fIend\fR will be set to \-1.
638 The \fIextendStart\fR field in \fBTcl_RegExpInfo\fR is only set if the
639 \fBTCL_REG_CANMATCH\fR flag was used. It indicates the first
640 character in the string where a match could occur. If a match was
641 found, this will be the same as the beginning of the current match.
642 If no match was found, then it indicates the earliest point at which a
643 match might occur if additional text is appended to the string. If it
644 is no match is possible even with further text, this field will be set
649 match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegExpInfo
OSDN Git Service
