Manual Pages for UNIX Darwin command on man Tcl

Manual Pages for UNIX Darwin command on man Tcl_RegExpMatch

TclRegExpMatch(3) Tcl Library Procedures TclRegExpMatch(3)

NAME

TclRegExpMatch, TclRegExpCompile, TclRegExpExec, TclRegExpRange,

TclGetRegExpFromObj, TclRegExpMatchObj, TclRegExpExecObj, TclReg-

ExpGetInfo - Pattern matching with regular expressions

SYNOPSIS

##iinncclluuddee <>

int TTccllRReeggEExxppMMaattcchhOObbjj(interp, strObj, patObj) int TTccllRReeggEExxppMMaattcchh(interp, string, pattern) TclRegExp TTccllRReeggEExxppCCoommppiillee(interp, pattern) int TTccllRReeggEExxppEExxeecc(interp, regexp, string, start) TTccllRReeggEExxppRRaannggee(regexp, index, startPtr, endPtr) TclRegExp | TTccllGGeettRReeggEExxppFFrroommOObbjj(interp, patObj, cflags) | int | TTccllRReeggEExxppEExxeeccOObbjj(interp, regexp, objPtr, offset, nmatches, eflags) | TTccllRReeggEExxppGGeettIInnffoo(regexp, infoPtr) | AARRGGUUMMEENNTTSS TclInterp *interp (in) Tcl interpreter to use for error reporting. The interpreter may be NULL if no error reporting is desired. | TclObj *strObj (in/out) || Refers to the object from which to get | the string to search. The internal | representation of the object may be |

converted to a form that can be effi- |

ciently searched. | TclObj *patObj (in/out) || Refers to the object from which to get | a regular expression. The compiled | regular expression is cached in the | object. char *string (in) String to check for a match with a regular expression. CONST char *pattern (in) String in the form of a regular expression pattern. TclRegExp regexp (in) Compiled regular expression. Must have been returned previously by

TTccllGGeettRReeggEExxppFFrroommOObbjj or TTccllRReeggEExxppCCoomm-

ppiillee. char *start (in) If string is just a portion of some other string, this argument identifies the beginning of the larger string. If it isn't the same as string, 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 | after the last one in the range is | stored here, or NULL if there is no | such range. | int cflags (in) ||

OR-ed combination of compilation |

flags. See below for more information. | TclObj *objPtr (in/out) || An object which contains the string to | check for a match with a regular | expression. |

int off- |

set (in) | | The character offset into the string | 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 values |

TCLREGNOTBOL and TCLREGNOTEOL. |

See below for more information. |

TclRegEx- |

pInfo *infoPtr(out) | | The address of the location where | information about a previous match | should be stored by TTccllRReeggEExxppGGeettIInnffoo.

DESCRIPTION

TTccllRReeggEExxppMMaattcchh determines whether its pattern argument matches regexp, where regexp is interpreted as a regular expression using the rules in the rreessyynnttaaxx reference page. If there is a match then TTccllRReeggEExxppMMaattcchh returns 1. If there is no match then TTccllRReeggEExxppMMaattcchh returns 0. If an

error occurs in the matching process (e.g. pattern is not a valid regu-

lar expression) then TTccllRReeggEExxppMMaattcchh returns -1 and leaves an error

message in the interpreter result. TTccllRReeggEExxppMMaattcchhOObbjj is similar to | TTccllRReeggEExxppMMaattcchh except it operates on the Tcl objects strObj and patObj | instead of UTF strings. TTccllRReeggEExxppMMaattcchhOObbjj is generally more efficient | than TTccllRReeggEExxppMMaattcchh, so it is the preferred interface.

TTccllRReeggEExxppCCoommppiillee, TTccllRReeggEExxppEExxeecc, and TTccllRReeggEExxppRRaannggee provide lower-

level access to the regular expression pattern matcher. TTccllRReeggEExxppCCoomm-

ppiillee compiles 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 TTccllRReeggEExxppEExxeecc or TTccllRReeggEExxppRRaannggee. If an error occurs while compiling the regular

expression then TTccllRReeggEExxppCCoommppiillee returns NULL and leaves an error mes-

sage in the interpreter result. Note: the return value from TTccllRReegg-

EExxppCCoommppiillee is only valid up to the next call to TTccllRReeggEExxppCCoommppiillee; it is not safe to retain these values for long periods of time. TTccllRReeggEExxppEExxeecc executes the regular expression pattern matcher. It returns 1 if string 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, TTccllRReeggEExxppEExxeecc 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 string 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 doesn't allow ^^ atoms in the pattern to match. The start argument provides this information by pointing to the start of the overall string containing string. Start will be less than or equal to string; if it is less than string then no ^^ matches will be allowed.

TTccllRReeggEExxppRRaannggee may be invoked after TTccllRReeggEExxppEExxeecc returns; it pro-

vides detailed information about what ranges of the string matched what parts of the pattern. TTccllRReeggEExxppRRaannggee 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 TTccllRReeggEExxppEExxeecc. 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, information is returned about the range of charac-

ters that matched the index'th parenthesized subexpression within the pattern. If there is no range corresponding to index then NULL is stored in *startPtr and *endPtr. TTccllGGeettRReeggEExxppFFrroommOObbjj, TTccllRReeggEExxppEExxeeccOObbjj, and TTccllRReeggEExxppGGeettIInnffoo are | object interfaces that provide the most direct control of Henry | Spencer's regular expression library. For users that need to modify | compilation and execution options directly, it is recommended that you | use these interfaces instead 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 objects. | TTccllGGeettRReeggEExxppFFrroommOObbjj attempts to return a compiled regular expression | from the patObj. If the object does not already contain a compiled | regular expression it will attempt to create one from the string in the | object and assign it to the internal representation of the patObj. The | return value of this function is of type TTccllRReeggEExxpp. The return value | is a token for this compiled form, which can be used in subsequent | calls to TTccllRReeggEExxppEExxeeccOObbjj or TTccllRReeggEExxppGGeettIInnffoo. If an error occurs | while compiling the regular expression then TTccllGGeettRReeggEExxppFFrroommOObbjj | returns NULL and leaves an error message in the interpreter result. |

The regular expression token can be used as long as the internal repre- |

sentation of patObj refers to the compiled form. The eflags argument | is a bitwise OR of zero or more of the following flags that control the | compilation of patObj: | TTCCLLRREEGGAADDVVAANNCCEEDD ||

Compile advanced regular expressions (`AREs'). This mode cor- |

responds to the normal regular expression syntax accepted by | the Tcl regexp and regsub commands. | TTCCLLRREEGGEEXXTTEENNDDEEDD ||

Compile extended regular expressions (`EREs'). This mode cor- |

responds to the regular expression syntax recognized by Tcl | 8.0 and earlier versions. | TTCCLLRREEGGBBAASSIICC ||

Compile basic regular expressions (`BREs'). This mode corre- |

sponds to the regular expression syntax recognized by common | Unix utilities like sseedd and ggrreepp. This is the default if no | flags are specified. | TTCCLLRREEGGEEXXPPAANNDDEEDD || Compile the regular expression (basic, extended, or advanced) | using 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. |

TTCCLLRREEGGQQUUOOTTEE ||

Compile a literal string, with all characters treated as ordi- |

nary characters. | TTCCLLRREEGGNNOOCCAASSEE ||

Compile for matching that ignores upper/lower case distinc- |

tions. |

TTCCLLRREEGGNNEEWW- |

LLIINNEE | |

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 expressions 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. RREEGGNNEEWWLLIINNEE is the bit- |

wise OR of RREEGGNNLLSSTTOOPP and RREEGGNNLLAANNCCHH. | TTCCLLRREEGGNNLLSSTTOOPP ||

Compile for partial newline-sensitive matching, with the |

behavior of `[^' bracket expressions and `.' affected, but not |

the behavior of `^' and `$'. In this mode, `[^' bracket |

expressions and `.' never match newline. | TTCCLLRREEGGNNLLAANNCCHH ||

Compile for inverse partial newline-sensitive matching, with |

the behavior of of `^' and `$' (the ``anchors'') affected, but |

not the behavior of `[^' bracket expressions and `.'. In this | mode `^' 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. | TTCCLLRREEGGNNOOSSUUBB || Compile for matching that reports only success or failure, not | what was matched. This reduces compile overhead and may | improve performance. Subsequent calls to TTccllRReeggEExxppGGeettIInnffoo or | TTccllRReeggEExxppRRaannggee will not report any match information. |

TTCCLLRREEGGCCAANN- |

MMAATTCCHH | | Compile for matching that reports the potential to complete a | partial match given more text (see below). | Only one of TTCCLLRREEGGEEXXTTEENNDDEEDD, TTCCLLRREEGGAADDVVAANNCCEEDD, TTCCLLRREEGGBBAASSIICC, and | TTCCLLRREEGGQQUUOOTTEE may be specified. | TTccllRReeggEExxppEExxeeccOObbjj executes the regular expression pattern matcher. It | returns 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, TTccllRReeggEExxppEExxeeccOObbjj leaves an error message in the interpreter |

result. The nmatches value indicates to the matcher how many subex- |

pressions are of interest. If nmatches is 0, then no subexpression |

match information is recorded, which may allow the matcher to make var- |

ious optimizations. If the value is -1, then all of the subexpressions |

in the pattern are remembered. If the value is a positive integer, | then only that number of subexpressions will be remembered. Matching | begins at the specified Unicode character index given by offset. | Unlike TTccllRReeggEExxppEExxeecc, the behavior of anchors is not affected by the |

offset value. Instead the behavior of the anchors is explicitly con- |

trolled by the eflags argument, which is a bitwise OR of zero or more | of the following flags: |

TTCCLLRREEGGNNOOTT- |

BBOOLL | | 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 `\\AA' matches. | TTCCLLRREEGGNNOOTTEEOOLL || 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 `\\ZZ' matches. | TTccllRReeggEExxppGGeettIInnffoo 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 TclRegExpInfo { | int nsubs; | TclRegExpIndices *matches; | long extendStart; | } TclRegExpInfo; |

The nsubs field contains a count of the number of parenthesized subex- |

pressions within the regular expression. If the TTCCLLRREEGGNNOOSSUUBB was | used, then this value will be zero. The matches field points to an | array of nsubs values that indicate the bounds of each subexpression | matched. The first element in the array refers to the range matched by | the entire regular expression, and subsequent elements refer to the |

parenthesized subexpressions in the order that they appear in the pat- |

tern. Each element is a structure that is defined as follows: | typedef struct TclRegExpIndices { | long start; | long end; | } TclRegExpIndices; | The start and end values are Unicode character indices relative to the | offset location within objPtr where matching began. The start index | identifies the first character of the matched subexpression. The end | index identifies the first character after the matched subexpression. | If the subexpression 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 TTccllRReeggEExxppIInnffoo is only set if the TTCCLLRREEGGCCAANN- |

MMAATTCCHH 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 beginning 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.