ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

This manual page is associated with the Mac OS X developer tools. The software or headers described may not be present on your Mac OS X installation until you install the developer tools package. This package is available on your Mac OS X installation DVD, and the latest versions can be downloaded from developer.apple.com.

For more information about the manual page format, see the manual page for manpages(5).



Tcl_RegExpMatch(3)                         Tcl Library Procedures                         Tcl_RegExpMatch(3)



____________________________________________________________________________________________________________

NAME
       Tcl_RegExpMatch,  Tcl_RegExpCompile,  Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_Reg-ExpMatchObj, Tcl_RegExpMatchObj,
       ExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo - Pattern matching with regular expressions

SYNOPSIS
       #include <tcl.h>

       int
       Tcl_RegExpMatchObj(interp, strObj, patObj)

       int
       Tcl_RegExpMatch(interp, string, pattern)

       Tcl_RegExp
       Tcl_RegExpCompile(interp, pattern)

       int
       Tcl_RegExpExec(interp, regexp, string, start)

       Tcl_RegExpRange(regexp, index, startPtr, endPtr)

       Tcl_RegExp                                                                                            |
       Tcl_GetRegExpFromObj(interp, patObj, cflags)                                                          |

       int                                                                                                   |
       Tcl_RegExpExecObj(interp, regexp, objPtr, offset, nmatches, eflags)                                   |

       Tcl_RegExpGetInfo(regexp, infoPtr)                                                                    |


ARGUMENTS
       Tcl_Interp   *interp   (in)      Tcl interpreter to use for error reporting.  The interpreter may  be
                                        NULL if no error reporting is desired.                               |

       Tcl_Obj      *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 efficiently searched.                                    |

       Tcl_Obj      *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.

       Tcl_RegExp   regexp    (in)      Compiled regular expression.  Must have been returned previously  by
                                        Tcl_GetRegExpFromObj or Tcl_RegExpCompile.

       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-expression.                                                      |

       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  informa- |
                                        tion.                                                                |

       Tcl_Obj      *objPtr   (in/out)                                                                       ||
                                        An object which contains the string to check for a match with a reg- |
                                        ular 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 informa- |
                                        tion 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 TCL_REG_NOTBOL  and  TCL_REG_NOTEOL. |
                                        See below for more information.                                      |

       Tcl_RegEx-                                                                                            |
       pInfo         *infoPtr(out)                                                                  |        |
                                        The address of the location where information 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 occurs
       in the matching process (e.g. pattern is not a valid regular expression) then Tcl_RegExpMatch returns
       -1  and leaves an error message in the interpreter result.  Tcl_RegExpMatchObj is similar to Tcl_Reg- |
       ExpMatch except it operates on the Tcl objects strObj and patObj instead of UTF strings.  Tcl_RegExp- |
       MatchObj is generally more efficient than Tcl_RegExpMatch, 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 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 Tcl_RegExpExec or Tcl_RegExpRange.  If an error occurs while  com-piling compiling
       piling  the regular expression then Tcl_RegExpCompile 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 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, Tcl_RegExpExec 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.

       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,  information is returned about the range of characters that matched the index'th parenthe-sized parenthesized
       sized subexpression within the pattern.  If there is no range corresponding to  index  then  NULL  is
       stored in *startPtr and *endPtr.

       Tcl_GetRegExpFromObj, Tcl_RegExpExecObj, and Tcl_RegExpGetInfo 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.                                                                                              |

       Tcl_GetRegExpFromObj 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  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 compil- |
       ing  the regular expression 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 eflags argument is a bitwise OR of zero or more of the |
       following flags that control the compilation of patObj:                                               |

         TCL_REG_ADVANCED                                                                                    ||
                Compile  advanced regular expressions (`AREs').  This mode corresponds to the normal regular |
                expression syntax accepted by the Tcl regexp and regsub commands.                            |

         TCL_REG_EXTENDED                                                                                    ||
                Compile extended regular expressions (`EREs').  This mode corresponds to the regular expres- |
                sion syntax recognized by Tcl 8.0 and earlier versions.                                      |

         TCL_REG_BASIC                                                                                       ||
                Compile basic regular expressions (`BREs').  This mode corresponds to the regular expression |
                syntax recognized by common Unix utilities like sed and grep.  This is  the  default  if  no |
                flags are specified.                                                                         |

         TCL_REG_EXPANDED                                                                                    ||
                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.                                     |

         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_NEW-                                                                                        |
         LINE                                                                                     |          |
                Compile  for newline-sensitive matching.  By default, newline is a completely ordinary char- |
                acter 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  new- |
                line  in  addition  to its normal function.  REG_NEWLINE is the bitwise OR of REG_NLSTOP and |
                REG_NLANCH.                                                                                  |

         TCL_REG_NLSTOP                                                                                      ||
                Compile  for  partial  newline-sensitive matching, with the behavior of `[^' bracket expres- |
                sions and `.' affected, but not the behavior 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 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.       |

         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_RegExpRange will not report any match information.                                    |

         TCL_REG_CAN-                                                                                        |
         MATCH                                                                                    |          |
                Compile  for matching that reports the potential to complete a partial 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 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, Tcl_RegExpExecObj leaves an error message in the interpreter result.  The  nmatches |
       value  indicates  to  the matcher how many subexpressions are of interest.  If nmatches is 0, then no |
       subexpression match information is recorded, which may allow the matcher to  make  various  optimiza- |
       tions.   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 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 bitwise OR of zero or more of the following flags:      |

         TCL_REG_NOT-                                                                                        |
         BOL                                                                                      |          |
                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 expres- |
       sion 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  subexpressions  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 values that indicate the bounds of each subexpression matched.  The  first  ele- |
       ment  in  the array refers to the range matched by the entire regular expression, and subsequent ele- |
       ments 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 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 Tcl_RegExpInfo is only set if the TCL_REG_CANMATCH flag was used.  It indi- |
       cates 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 ear- |
       liest 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_RegExpIndices, Tcl_RegExpInfo



Tcl                                                  8.1                                  Tcl_RegExpMatch(3)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.