Tcl_RegExpCompile man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

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_Reg-
       ExpGetInfo - 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	 effi- |
					ciently 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_RegExpCom-
					pile.

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

       Tcl_Obj	    *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 |
					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 regu-
       lar  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 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_RegExpCom-
       pile  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_RegExpCompile returns NULL and leaves an error mes-
       sage in the interpreter result.	Note:  the return value from  Tcl_Reg-
       ExpCompile  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  pro-
       vides 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 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.

       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  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 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:						       |

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

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

	 TCL_REG_BASIC							       ||
		Compile basic regular expressions (`BREs').  This mode	corre- |
		sponds	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 ordi- |
		nary characters.					       |

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

	 TCL_REG_NEW-							       |
	 LINE							    |	       |
		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  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 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	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  Tcl_RegExpExec,	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:						       |

	 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 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	subex- |
       pressions  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 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 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_CAN- |
       MATCH 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_RegEx-
       pIndices, Tcl_RegExpInfo

Tcl				      8.1		    Tcl_RegExpMatch(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net