FBB::Pattern(3bobcat)						  Pattern matcher					     FBB::Pattern(3bobcat)

NAME

       FBB::Pattern - Performs RE pattern matching

SYNOPSIS

       #include <bobcat/pattern>
       Linking option: -lbobcat

DESCRIPTION

       Pattern objects may be used for Regular Expression (RE) pattern matching. The class is a wrapper around the regcomp(3) family of functions.
       By default it uses `extended regular expressions', requiring you to escape multipliers and bounding-characters when they should	be  inter-
       preted as ordinary characters (i.e., *, +, ?, ^, $, |, (, ), [, ], {, } should be escaped when used as literal characters).

       The Pattern class supports the use of the following (Perl-like) special escape sequences:
        - indicating a word-boundary
       d - indicating a digit ([[:digit:]]) character
       s - indicating a white-space ([:space:]) character
       w - indicating a word ([:alnum:]) character

       The  corresponding  capitals  (e.g., W) define the complementary character sets. The capitalized character set shorthands are not expanded
       inside explicit character-classes (i.e., [ ... ] constructions). So [W] represents a set of two characters:  and W.

       As the backslash () is treated as a special character it should be handled carefully. Pattern converts the escape sequences d s w  (and
       outside of explicit character classes the sequences D S W) to their respective character classes. All other escape sequences are kept as
       is, and the resulting regular expression is offered to the pattern matching compilation	function  regcomp(3).  This  function  will  again
       interpret  escape  sequences.  Consequently  some care should be exercised when defining patterns containing escape sequences. Here are the
       rules:

       o      Special escape sequences (like d) are converted to character classes. E.g.,

		  ---------------------------------------------------------
		  Specify:    Converts to:    regcomp uses:	 Matches:
		  ---------------------------------------------------------
		  d	      [[:digit:]]     [[:digit:]]	 3
		  ---------------------------------------------------------

       o      Ordinary escape sequences (like x) are kept as-is. E.g.,

		  ---------------------------------------------------------
		  Specify:    Converts to:    regcomp uses:	 Matches:
		  ---------------------------------------------------------
		  x	      x	      x 		 x
		  ---------------------------------------------------------

       o      To specify a literal escape sequence, it must be written twice. E.g.,

		  ---------------------------------------------------------
		  Specify:    Converts to:    regcomp uses:	 Matches:
		  ---------------------------------------------------------
		  \x	      \x	      x		 x
		  ---------------------------------------------------------

NAMESPACE

       FBB
       All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

       -

TYPEDEF

       o      Pattern::Position:
	      A nested type representing the offsets of the first character and the offset beyond the  last  character	of  the  matched  text	or
	      indexed subexpression, defined as std::pair<std::string::size_type, std::string::size_type>.

CONSTRUCTORS

       o      Pattern():
	      The  default constructor defines no pattern, but is available as a placeholder for, e.g., containers requiring default constructors.
	      A Pattern object thus constructed cannot be used to match patterns, but can be the  lvalue  in  assignments  where  another  Pattern
	      object is the rvalue. However, it can receive a pattern using the member setPattern() (see below). An FBB::Errno object is thrown if
	      the object could not be constructed.

       o      Pattern(std::string const &pattern, bool caseSensitive = true, size_t nSub = 10, int options = REG_EXTENDED | REG_NEWLINE):
	      This constructor compiles pattern, preparing the Pattern object for pattern matches. The second parameter  determines  whether  case
	      sensitive  matching will be used (the default) or not. Subexpressions are defined by parentheses pairs. Each matching pair defines a
	      subexpression, where the order-number of their opening parentheses determines the subexpression's index. By default at most 10  sub-
	      expressions are recognized.  The options flags may be:

	      REG_EXTENDED:
	      Use POSIX Extended Regular Expression syntax when interpreting regex.  If not set, POSIX Basic Regular Expression syntax is used.

	      REG_NOSUB:
	      Support  for  substring addressing of matches is	not required.	The  nmatch  and  pmatch  parameters to regexec are ignored if the
	      pattern buffer  supplied was compiled with this flag set.

	      REG_NEWLINE:
	      Match-any-character  operators  don't  match a newline.

	      A non-matching list ([^...])  not containing a newline does not match a newline.

	      Match-beginning-of-line operator (^) matches the empty string immediately after a newline, regardless of whether eflags, the  execu-
	      tion flags of regexec, contains REG_NOTBOL.

	      Match-end-of-line  operator  ($)	 matches   the	 empty string  immediately before a newline, regardless of whether eflags contains
	      REG_NOTEOL.

       Pattern offers  copy and move constructors.

MEMBER FUNCTIONS

       All members of std::ostringstream and   std::exception are available, as Pattern inherits from these classes.

       o      std::string before() const:
	      Following a successful match, before() returns the text before the matched text.

       o      std::string beyond() const:
	      Following a successful match, beyond() returns the text beyond the matched text.

       o      size_t end() const:
	      Returns the number of matched elements (text and subexpressions). end() is the lowest index value for which position()  returns  two
	      std::string::npos values (see the position() member function, below).

       o      void match(std::string const &text, int options = 0):
	      Match  a string with a pattern.  If the text could not be matched, an Errno exception is thrown , using Pattern::match() as its pre-
	      fix-text.

	      Options may be:

	      REG_NOTBOL:
	      The match-beginning-of-line operator always fails to match (but see the compilation flag REG_NEWLINE above) This flag  may  be  used
	      when different portions of a string are passed to regexec and the beginning of the string should not be interpreted as the beginning
	      of the line.

	      REG_NOTEOL:
	      The  match-end-of-line  operator	always	fails  to match  (but  see  the  compilation flag REG_NEWLINE)

       o      std::string matched() const:
	      Following a successful match, this function returns the matched text.

       o      std::string const &pattern() const:
	      This member function returns the pattern that is offered to regcomp(3). It returns the contents of a static string that is overwrit-
	      ten at each construction of a Pattern object and at each call of the setPattern() member function.

       o      Pattern::Position position(size_t index) const:
	      With  index == 0 the fully matched text is returned (identical to matched()). Other index values return the corresponding subexpres-
	      sions. std::string::npos, std::string::npos is returned if index is at least end() (which may happen at index value 0).

       o      void setPattern(std::string const &pattern, bool caseSensitive = true, size_t nSub = 10, int options = REG_EXTENDED | REG_NEWLINE):
	      This member function installs a new  compiled pattern in its Pattern object. This member's parameters are identical  to  the  second
	      constructor's  parameters. Refer to that constructor for details about the parameters. Like the constructor, an FBB::Errno exception
	      is thrown if the new pattern could not be compiled.

       o      void swap(Pattern &other):
	      The contents of the current object and the other object are swapped.

OVERLOADED OPERATORS

       o      Pattern &operator=(Pattern &other):
	      A standard overloaded assignment operator.

       o      std::string operator[](size_t index) const:
	      Returns the matched text (for index 0) or the text of a subexpression. An empty string is returned for index  values  which  are	at
	      least end().

       o      Pattern &operator<<(int matchOptions):
	      Defines match-options to be used with the following overloaded operator.

       o      bool operator<<(std::string const &text):
	      Performs	a match(text, matchOptions) call, catching any exception that might be thrown. If no matchOptions were set using the above
	      overloaded operator, none are used. The options set this way are not `sticky': when necessary, they have to  be  re-inserted  before
	      each new pattern matching. The function returns true if the matching was successful, false otherwise.

EXAMPLE

       /*
				     driver.cc
       */

       #include "driver.h"

       #include <bobcat/pattern>

       using namespace std;
       using namespace FBB;

       void showSubstr(string const &str)
       {
	   static int
	       count = 1;

	   cout << "String " << count++ << " is '" << str << "'
";
       }

       int main(int argc, char **argv)
       {
	   {
	       Pattern one("one");
	       Pattern two(one);
	       Pattern three("a");
	       Pattern four;
	       three = two;
	   }

	   try
	   {
	       Pattern pattern("aap|noot|mies");

	       {
		   Pattern extra(Pattern(pattern));
	       }

	       if (pattern << "noot")
		   cout << "noot matches
";
	       else
		   cout << ": noot doesn't match
";
	   }
	   catch (Errno const &e)
	   {
	       cout << e.why() << ": compilation failed" << endl;
	   }

	   string pat = "\d+";

	   while (true)
	   {
	       cout << "Pattern: '" << pat << "'
";

	       try
	       {
		   Pattern patt(pat, argc == 1);   // case sensitive by default,
						   // any arg for case insensitive

		   cout << "Compiled pattern: " << patt.pattern() << endl;

		   Pattern pattern;
		   pattern = patt;		   // assignment operator

		   while (true)
		   {
		       cout << "string to match : ";

		       string st;
		       getline(cin, st);
		       if (st == "")
			   break;
		       cout << "String: '" << st << "'
";
		       try
		       {
			   pattern.match(st);

			   Pattern p3(pattern);

			   cout << "before:  " << p3.before() << "
"
				   "matched: " << p3.matched() << "
"
				   "beyond:  " << pattern.beyond() << "
"
				   "end() = " << pattern.end() << endl;

			   for (size_t idx = 0; idx < pattern.end(); ++idx)
			   {
			       string str = pattern[idx];

			       if (str == "")
				   cout << "part " << idx << " not present
";
			       else
			       {
				   Pattern::Position pos = pattern.position(idx);

				   cout << "part " << idx << ": '" << str << "' (" <<
					   pos.first << "-" << pos.second << ")
";
			       }
			   }
		       }
		       catch (Errno const &e)
		       {
			   cout << e.why() << ": " << st << " doesn't match" << endl;
			   continue;
		       }
		   }
	       }
	       catch (Errno const &e)
	       {
		   cout << e.why() << ": compilation failed" << endl;
	       }

	       cout << "New pattern: ";

	       if (!getline(cin, pat) || !pat.length())
		   return 0;
	   }
       }

FILES

       bobcat/pattern - defines the class interface

SEE ALSO

       bobcat(7), regcomp(3), regex(3), regex(7)

BUGS

       Using Pattern objects as static data members of classes (or as global objects) is potentially dangerous. If the object files defining these
       static data members are stored in a dynamic library they may not be initialized properly or timely,  and  their	eventual  destruction  may
       result	  in	 a     segmentation	fault.	   This     is	   a	 well-known    problem	  with	  static    data,    see,    e.g.,
       http://www.parashift.com/c++-faq-lite/ctors.html#faq-10.15. In situations like this prefer the use of a (shared, unique) pointer to a  Pat-
       tern, initialzing the pointer when, e.g., first used.

DISTRIBUTION FILES

       o      bobcat_3.01.00-x.dsc: detached signature;

       o      bobcat_3.01.00-x.tar.gz: source archive;

       o      bobcat_3.01.00-x_i386.changes: change log;

       o      libbobcat1_3.01.00-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.01.00-x_*.deb: debian package holding the libraries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

COPYRIGHT

       This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).

libbobcat1-dev_3.01.00-x.tar.gz 				     2005-2012						     FBB::Pattern(3bobcat)