Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for tcl_regexpexec (opendarwin section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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_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 inter-
					preter 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  expres- |
					sion.  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 information.					  |

       Tcl_Obj	    *objPtr   (in/out)								  |
					An object which contains the string to check for a  match |
					with a regular expression.				  |

       int	    offset    (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 max- |
					imum 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_RegExpInfo	      *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_RegExp-
       Match  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_RegExpMatch except it operates |
       on the Tcl objects strObj and patObj instead of UTF strings.  Tcl_RegExpMatchObj is gener- |
       ally 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 compiling the regular expression then Tcl_Reg-
       ExpCompile 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_RegExpCom-
       pile;  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 infor-
       mation 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 parenthesized 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 perfor- |
       mance 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 cre- |
       ate 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 compiling 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 nor- |
		mal regular expression syntax accepted by the Tcl regexp and regsub commands.	  |

	 TCL_REG_EXTENDED									  |
		Compile extended regular expressions (`EREs').	This mode corresponds to the reg- |
		ular expression 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_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 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.  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 |
		expressions 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_CANMATCH									  |
		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 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 speci- |
       fied 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_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 regu- |
       lar 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 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 subex- |
       pression matched.  The first element in the array refers  to  the  range  matched  by  the |
       entire  regular	expression, and subsequent elements refer to the parenthesized subexpres- |
       sions 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  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.

SEE ALSO
       re_syntax(n)

KEYWORDS
       match,  pattern,  regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegEx-
       pInfo

Tcl					       8.1			       Tcl_RegExpMatch(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:51 PM.