FreeBSD Manual Pages
Tcl_RegExpMatch(3) Tcl Library Procedures Tcl_RegExpMatch(3) ________________________________________________________________________________ NAME Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGet- Info - Pattern matching with regular expressions SYNOPSIS #include <tcl.h> int Tcl_RegExpMatchObj(interp, textObj, patObj) int Tcl_RegExpMatch(interp, text, pattern) Tcl_RegExp Tcl_RegExpCompile(interp, pattern) int Tcl_RegExpExec(interp, regexp, text, start) void Tcl_RegExpRange(regexp, index, startPtr, endPtr) Tcl_RegExp Tcl_GetRegExpFromObj(interp, patObj, cflags) int Tcl_RegExpExecObj(interp, regexp, textObj, offset, nmatches, eflags) void Tcl_RegExpGetInfo(regexp, infoPtr) ARGUMENTS Tcl_Interp *interp (in) Tcl interpreter to use for error re- porting. The interpreter may be NULL if no error reporting is desired. Tcl_Obj *textObj (in/out) Refers to the value from which to get the text to search. The internal rep- resentation of the value may be con- verted to a form that can be effi- ciently searched. Tcl_Obj *patObj (in/out) Refers to the value from which to get a regular expression. The compiled regular expression is cached in the value. const char *text (in) Text to search for a match with a reg- ular expression. const char *pattern (in) String in the form of a regular ex- pression pattern. Tcl_RegExp regexp (in) Compiled regular expression. Must have been returned previously by Tcl_GetRegExpFromObj or Tcl_RegExpCom- pile. const char *start (in) If text is just a portion of some other string, this argument identifies the beginning of the larger string. If it is not the same as text, then no "^" matches will be allowed. int index (in) Specifies which range is desired: 0 means the range of the entire match, 1 or greater means the range that matched a parenthesized sub-expres- sion. const char **startPtr (out) The address of the first character in the range is stored here, or NULL if there is no such range. const char **endPtr (out) The address of the character just af- ter the last one in the range is stored here, or NULL if there is no such range. int cflags (in) OR-ed combination of the compilation flags TCL_REG_ADVANCED, TCL_REG_EX- TENDED, TCL_REG_BASIC, TCL_REG_EX- PANDED, TCL_REG_QUOTE, TCL_REG_NOCASE, TCL_REG_NEWLINE, TCL_REG_NLSTOP, TCL_REG_NLANCH, TCL_REG_NOSUB, and TCL_REG_CANMATCH. See below for more information. int offset (in) The character offset into the text where matching should begin. The value of the offset has no impact on ^ matches. This behavior is controlled by eflags. int nmatches (in) The number of matching subexpressions that should be remembered for later use. If this value is 0, then no subexpression match information will be computed. If the value is -1, then all of the matching subexpressions will be remembered. Any other value will be taken as the maximum number of subexpressions to remember. int eflags (in) OR-ed combination of the execution flags TCL_REG_NOTBOL and TCL_REG_NO- TEOL. See below for more information. Tcl_RegExpInfo *infoPtr (out) The address of the location where in- formation about a previous match should be stored by Tcl_RegExpGetInfo. ________________________________________________________________________________ DESCRIPTION Tcl_RegExpMatch determines whether its pattern argument matches regexp, where regexp is interpreted as a regular expression using the rules in the re_syntax reference page. If there is a match then Tcl_RegExpMatch returns 1. If there is no match then Tcl_RegExpMatch returns 0. If an error oc- curs in the matching process (e.g. pattern is not a valid regular expres- sion) then Tcl_RegExpMatch returns -1 and leaves an error message in the interpreter result. Tcl_RegExpMatchObj is similar to Tcl_RegExpMatch ex- cept it operates on the Tcl values textObj and patObj instead of UTF strings. Tcl_RegExpMatchObj is generally more efficient than Tcl_RegExp- Match, so it is the preferred interface. Tcl_RegExpCompile, Tcl_RegExpExec, and Tcl_RegExpRange provide lower-level access to the regular expression pattern matcher. Tcl_RegExpCompile com- piles a regular expression string into the internal form used for efficient pattern matching. The return value is a token for this compiled form, which can be used in subsequent calls to Tcl_RegExpExec or Tcl_RegExpRange. If an error occurs while compiling the regular expression then Tcl_RegExp- Compile returns NULL and leaves an error message in the interpreter result. Note: the return value from Tcl_RegExpCompile is only valid up to the next call to Tcl_RegExpCompile; it is not safe to retain these values for long periods of time. Tcl_RegExpExec executes the regular expression pattern matcher. It returns 1 if text contains a range of characters that match regexp, 0 if no match is found, and -1 if an error occurs. In the case of an error, Tcl_RegEx- pExec leaves an error message in the interpreter result. When searching a string for multiple matches of a pattern, it is important to distinguish between the start of the original string and the start of the current search. For example, when searching for the second occurrence of a match, the text argument might point to the character just after the first match; however, it is important for the pattern matcher to know that this is not the start of the entire string, so that it does not allow "^" atoms in the pattern to match. The start argument provides this information by pointing to the start of the overall string containing text. Start will be less than or equal to text; if it is less than text then no ^ matches will be allowed. Tcl_RegExpRange may be invoked after Tcl_RegExpExec returns; it provides detailed information about what ranges of the string matched what parts of the pattern. Tcl_RegExpRange returns a pair of pointers in *startPtr and *endPtr that identify a range of characters in the source string for the most recent call to Tcl_RegExpExec. Index indicates which of several ranges is desired: if index is 0, information is returned about the overall range of characters that matched the entire pattern; otherwise, informa- tion is returned about the range of characters that matched the index'th parenthesized subexpression within the pattern. If there is no range cor- responding to index then NULL is stored in *startPtr and *endPtr. Tcl_GetRegExpFromObj, Tcl_RegExpExecObj, and Tcl_RegExpGetInfo are value interfaces that provide the most direct control of Henry Spencer's regular expression library. For users that need to modify compilation and execu- tion options directly, it is recommended that you use these interfaces in- stead of calling the internal regexp functions. These interfaces handle the details of UTF to Unicode translations as well as providing improved performance through caching in the pattern and string values. Tcl_GetRegExpFromObj attempts to return a compiled regular expression from the patObj. If the value does not already contain a compiled regular ex- pression it will attempt to create one from the string in the value and as- sign it to the internal representation of the patObj. The return value of this function is of type Tcl_RegExp. The return value is a token for this compiled form, which can be used in subsequent calls to Tcl_RegExpExecObj or Tcl_RegExpGetInfo. If an error occurs while compiling the regular ex- pression then Tcl_GetRegExpFromObj returns NULL and leaves an error message in the interpreter result. The regular expression token can be used as long as the internal representation of patObj refers to the compiled form. The cflags argument is a bit-wise OR of zero or more of the following flags that control the compilation of patObj: TCL_REG_ADVANCED Compile advanced regular expressions ("ARE"s). This mode corre- sponds to the normal regular expression syntax accepted by the Tcl regexp and regsub commands. TCL_REG_EXTENDED Compile extended regular expressions ("ERE"s). This mode corre- sponds to the regular expression syntax recognized by Tcl 8.0 and earlier versions. TCL_REG_BASIC Compile basic regular expressions ("BRE"s). This mode corresponds to the regular expression syntax recognized by common Unix utili- ties like sed and grep. This is the default if no flags are spec- ified. TCL_REG_EXPANDED Compile the regular expression (basic, extended, or advanced) us- ing an expanded syntax that allows comments and whitespace. This mode causes non-backslashed non-bracket-expression white space and #-to-end-of-line comments to be ignored. TCL_REG_QUOTE Compile a literal string, with all characters treated as ordinary characters. TCL_REG_NOCASE Compile for matching that ignores upper/lower case distinctions. TCL_REG_NEWLINE Compile for newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning in either regular expressions or strings. With this flag, "[^" bracket ex- pressions and "." never match newline, "^" matches an empty string after any newline in addition to its normal function, and "$" matches an empty string before any newline in addition to its normal function. REG_NEWLINE is the bit-wise OR of REG_NLSTOP and REG_NLANCH. TCL_REG_NLSTOP Compile for partial newline-sensitive matching, with the behavior of "[^" bracket expressions and "." affected, but not the behav- ior of "^" and "$". In this mode, "[^" bracket expressions and "." never match newline. TCL_REG_NLANCH Compile for inverse partial newline-sensitive matching, with the behavior of "^" and "$" (the "anchors") affected, but not the be- havior of "[^" bracket expressions and ".". In this mode "^" matches an empty string after any newline in addition to its nor- mal function, and "$" matches an empty string before any newline in addition to its normal function. TCL_REG_NOSUB Compile for matching that reports only success or failure, not what was matched. This reduces compile overhead and may improve performance. Subsequent calls to Tcl_RegExpGetInfo or Tcl_RegEx- pRange will not report any match information. TCL_REG_CANMATCH Compile for matching that reports the potential to complete a par- tial match given more text (see below). Only one of TCL_REG_EXTENDED, TCL_REG_ADVANCED, TCL_REG_BASIC, and TCL_REG_QUOTE may be specified. Tcl_RegExpExecObj executes the regular expression pattern matcher. It re- turns 1 if objPtr contains a range of characters that match regexp, 0 if no match is found, and -1 if an error occurs. In the case of an error, Tcl_RegExpExecObj leaves an error message in the interpreter result. The nmatches value indicates to the matcher how many subexpressions are of in- terest. If nmatches is 0, then no subexpression match information is recorded, which may allow the matcher to make various optimizations. If the value is -1, then all of the subexpressions in the pattern are remem- bered. If the value is a positive integer, then only that number of subex- pressions will be remembered. Matching begins at the specified Unicode character index given by offset. Unlike Tcl_RegExpExec, the behavior of anchors is not affected by the offset value. Instead the behavior of the anchors is explicitly controlled by the eflags argument, which is a bit- wise OR of zero or more of the following flags: TCL_REG_NOTBOL The starting character will not be treated as the beginning of a line or the beginning of the string, so "^" will not match there. Note that this flag has no effect on how "\A" matches. TCL_REG_NOTEOL The last character in the string will not be treated as the end of a line or the end of the string, so "$" will not match there. Note that this flag has no effect on how "\Z" matches. Tcl_RegExpGetInfo retrieves information about the last match performed with a given regular expression regexp. The infoPtr argument contains a pointer to a structure that is defined as follows: typedef struct Tcl_RegExpInfo { int nsubs; Tcl_RegExpIndices *matches; long extendStart; } Tcl_RegExpInfo; The nsubs field contains a count of the number of parenthesized subexpres- sions within the regular expression. If the TCL_REG_NOSUB was used, then this value will be zero. The matches field points to an array of nsubs+1 values that indicate the bounds of each subexpression matched. The first element in the array refers to the range matched by the entire regular ex- pression, and subsequent elements refer to the parenthesized subexpressions in the order that they appear in the pattern. Each element is a structure that is defined as follows: typedef struct Tcl_RegExpIndices { long start; long end; } Tcl_RegExpIndices; The start and end values are Unicode character indices relative to the off- set location within objPtr where matching began. The start index identi- fies the first character of the matched subexpression. The end index iden- tifies the first character after the matched subexpression. If the subex- pression matched the empty string, then start and end will be equal. If the subexpression did not participate in the match, then start and end will be set to -1. The extendStart field in Tcl_RegExpInfo is only set if the TCL_REG_CANMATCH flag was used. It indicates the first character in the string where a match could occur. If a match was found, this will be the same as the be- ginning of the current match. If no match was found, then it indicates the earliest point at which a match might occur if additional text is appended to the string. If it is no match is possible even with further text, this field will be set to -1. SEE ALSO re_syntax(n) KEYWORDS match, pattern, regular expression, string, subexpression, Tcl_RegEx- pIndices, Tcl_RegExpInfo Tcl 8.1 Tcl_RegExpMatch(3)
NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_RegExpMatch.tcl86&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>