Source/cmRegularExpression.h

   1 /*=========================================================================
   2
   3   Program:   Insight Segmentation & Registration Toolkit
   4   Module:    $RCSfile: cmRegularExpression.h,v $
   5   Language:  C++
   6   Date:      $Date: 2002-10-04 22:16:13 $
   7   Version:   $Revision: 1.11 $
   8
   9   Copyright (c) 2002 Insight Consortium. All rights reserved.
  10   See ITKCopyright.txt or http://www.itk.org/HTML/Copyright.htm for details.
  11
  12      This software is distributed WITHOUT ANY WARRANTY; without even
  13      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  14      PURPOSE.  See the above copyright notices for more information.
  15
  16 =========================================================================*/
  17 // Original Copyright notice:
  18 // Copyright (C) 1991 Texas Instruments Incorporated.
  19 //
  20 // Permission is granted to any individual or institution to use, copy, modify,
  21 // and distribute this software, provided that this complete copyright and
  22 // permission notice is maintained, intact, in all copies and supporting
  23 // documentation.
  24 //
  25 // Texas Instruments Incorporated provides this software "as is" without
  26 // express or implied warranty.
  27 //
  28 // Created: MNF 06/13/89  Initial Design and Implementation
  29 // Updated: LGO 08/09/89  Inherit from Generic
  30 // Updated: MBN 09/07/89  Added conditional exception handling
  31 // Updated: MBN 12/15/89  Sprinkled "const" qualifiers all over the place!
  32 // Updated: DLS 03/22/91  New lite version
  33 //
  34
  35 #ifndef cmRegularExpression_h
  36 #define cmRegularExpression_h
  37
  38 #include "cmStandardIncludes.h"
  39
  40 const int NSUBEXP = 10;
  41
  42 /** \class cmRegularExpression
  43  * \brief Implements pattern matching with regular expressions.
  44  *
  45  * This is the header file for the regular expression class.  An object of
  46  * this class contains a regular expression, in a special "compiled" format.
  47  * This compiled format consists of several slots all kept as the objects
  48  * private data.  The cmRegularExpression class provides a convenient way to
  49  * represent regular expressions.  It makes it easy to search for the same
  50  * regular expression in many different strings without having to compile a
  51  * string to regular expression format more than necessary.
  52  *
  53  * This class implements pattern matching via regular expressions.
  54  * A regular expression allows a programmer to specify  complex
  55  * patterns  that  can  be searched for and matched against the
  56  * character string of a string object. In its simplest form, a
  57  * regular  expression  is  a  sequence  of  characters used to
  58  * search for exact character matches. However, many times  the
  59  * exact  sequence to be found is not known, or only a match at
  60  * the beginning or end of a string is desired. The cmRegularExpression regu-
  61  * lar  expression  class implements regular expression pattern
  62  * matching as is found and implemented in many  UNIX  commands
  63  * and utilities.
  64  *
  65  * Example: The perl code
  66  *
  67  *    $filename =~ m"([a-z]+)\.cc";
  68  *    print $1;
  69  *
  70  * Is written as follows in C++
  71  *
  72  *    cmRegularExpression re("([a-z]+)\\.cc");
  73  *    re.find(filename);
  74  *    cerr << re.match(1);
  75  *
  76  *
  77  * The regular expression class provides a convenient mechanism
  78  * for  specifying  and  manipulating  regular expressions. The
  79  * regular expression object allows specification of such  pat-
  80  * terns  by using the following regular expression metacharac-
  81  * ters:
  82  *
  83  *  ^        Matches at beginning of a line
  84  *
  85  *  $        Matches at end of a line
  86  *
  87  * .         Matches any single character
  88  *
  89  * [ ]       Matches any character(s) inside the brackets
  90  *
  91  * [^ ]      Matches any character(s) not inside the brackets
  92  *
  93  *  -        Matches any character in range on either side of a dash
  94  *
  95  *  *        Matches preceding pattern zero or more times
  96  *
  97  *  +        Matches preceding pattern one or more times
  98  *
  99  *  ?        Matches preceding pattern zero or once only
 100  *
 101  * ()        Saves a matched expression and uses it in a  later match
 102  *
 103  * Note that more than one of these metacharacters can be  used
 104  * in  a  single  regular expression in order to create complex
 105  * search patterns. For example, the pattern [^ab1-9]  says  to
 106  * match  any  character  sequence that does not begin with the
 107  * characters "ab"  followed  by  numbers  in  the  series  one
 108  * through nine.
 109  *
 110  * There are three constructors for cmRegularExpression.  One just creates an
 111  * empty cmRegularExpression object.  Another creates a cmRegularExpression
 112  * object and initializes it with a regular expression that is given in the
 113  * form of a char*.  The third takes a reference to a cmRegularExpression
 114  * object as an argument and creates an object initialized with the
 115  * information from the given cmRegularExpression object.
 116  *
 117  * The  find  member function  finds   the  first  occurence   of  the regualr
 118  * expression of that object in the string given to find as an argument.  Find
 119  * returns a boolean, and  if true,  mutates  the private  data appropriately.
 120  * Find sets pointers to the beginning and end of  the thing last  found, they
 121  * are pointers into the actual string  that was searched.   The start and end
 122  * member functions return indicies  into the searched string that  correspond
 123  * to the beginning   and  end pointers  respectively.   The    compile member
 124  * function takes a char* and puts the  compiled version of the char* argument
 125  * into the object's private data fields.  The == and  != operators only check
 126  * the  to see  if   the compiled  regular  expression   is the same, and  the
 127  * deep_equal functions also checks  to see if the  start and end pointers are
 128  * the same.  The is_valid  function returns false if  program is set to NULL,
 129  * (i.e. there is no valid compiled exression).  The set_invalid function sets
 130  * the  program to NULL  (Warning: this deletes the compiled  expression). The
 131  * following examples may help clarify regular expression usage:
 132  *
 133  *   *  The regular expression  "^hello" matches  a "hello"  only at  the
 134  *      beginning of a  line.  It would match "hello  there" but not "hi,
 135  *      hello there".
 136  *
 137  *   *  The regular expression "long$" matches a  "long"  only at the end
 138  *      of a line. It would match "so long\0", but not "long ago".
 139  *
 140  *   *  The regular expression "t..t..g"  will match anything that  has a
 141  *      "t" then any two characters, another "t", any  two characters and
 142  *      then a "g".   It will match  "testing", or "test again" but would
 143  *      not match "toasting"
 144  *
 145  *   *  The regular  expression "[1-9ab]" matches any  number one through
 146  *      nine, and the characters  "a" and  "b".  It would match "hello 1"
 147  *      or "begin", but would not match "no-match".
 148  *
 149  *   *  The  regular expression "[^1-9ab]"  matches any character that is
 150  *      not a number one  through nine, or  an "a" or "b".   It would NOT
 151  *      match "hello 1" or "begin", but would match "no-match".
 152  *
 153  *   *  The regular expression "br* " matches  something that begins with
 154  *      a "b", is followed by zero or more "r"s, and ends in a space.  It
 155  *      would match "brrrrr ", and "b ", but would not match "brrh ".
 156  *
 157  *   *  The regular expression "br+ " matches something  that begins with
 158  *      a "b", is followed by one or more "r"s, and ends in  a space.  It
 159  *      would match "brrrrr ",  and  "br ", but would not  match "b  " or
 160  *      "brrh ".
 161  *
 162  *   *  The regular expression "br? " matches  something that begins with
 163  *      a "b", is followed by zero or one "r"s, and ends in  a space.  It
 164  *      would  match  "br ", and "b  ", but would not match  "brrrr "  or
 165  *      "brrh ".
 166  *
 167  *   *  The regular expression "(..p)b" matches  something ending with pb
 168  *      and beginning with whatever the two characters before the first p
 169  *      encounterd in the line were.  It would find  "repb" in "rep drepa
 170  *      qrepb".  The regular expression "(..p)a"  would find "repa qrepb"
 171  *      in "rep drepa qrepb"
 172  *
 173  *   *  The regular expression "d(..p)" matches something ending  with p,
 174  *      beginning with d, and having  two characters  in between that are
 175  *      the same as the two characters before  the first p  encounterd in
 176  *      the line.  It would match "drepa qrepb" in "rep drepa qrepb".
 177  *
 178  */
 179 class cmRegularExpression
 180 {
 181 public:
 182   /**
 183    * Instantiate cmRegularExpression with program=NULL.
 184    */
 185   inline cmRegularExpression ();
 186
 187   /**
 188    * Instantiate cmRegularExpression with compiled char*.
 189    */
 190   inline cmRegularExpression (char const*);
 191
 192   /**
 193    * Instantiate cmRegularExpression as a copy of another regular expression.
 194    */
 195   cmRegularExpression (cmRegularExpression const&);
 196
 197   /**
 198    * Destructor.
 199    */
 200   inline ~cmRegularExpression();
 201
 202   /**
 203    * Compile a regular expression into internal code
 204    * for later pattern matching.
 205    */
 206   void compile (char const*);
 207
 208   /**
 209    * Matches the regular expression to the given string.
 210    * Returns true if found, and sets start and end indexes accordingly.
 211    */
 212   bool find (char const*);
 213
 214   /**
 215    * Matches the regular expression to the given std string.
 216    * Returns true if found, and sets start and end indexes accordingly.
 217    */
 218   bool find (std::string const&);
 219
 220   /**
 221    * Index to start of first find.
 222    */
 223   inline std::string::size_type start() const;
 224
 225   /**
 226    * Index to end of first find.
 227    */
 228   inline std::string::size_type end() const;
 229
 230   /**
 231    * Returns true if two regular expressions have the same
 232    * compiled program for pattern matching.
 233    */
 234   bool operator== (cmRegularExpression const&) const;
 235
 236   /**
 237    * Returns true if two regular expressions have different
 238    * compiled program for pattern matching.
 239    */
 240   inline bool operator!= (cmRegularExpression const&) const;
 241
 242   /**
 243    * Returns true if have the same compiled regular expressions
 244    * and the same start and end pointers.
 245    */
 246   bool deep_equal (cmRegularExpression const&) const;
 247
 248   /**
 249    * True if the compiled regexp is valid.
 250    */
 251   inline bool is_valid() const;
 252
 253   /**
 254    * Marks the regular expression as invalid.
 255    */
 256   inline void set_invalid();
 257
 258   /**
 259    * Destructor.
 260    */
 261   // awf added
 262   std::string::size_type start(int n) const;
 263   std::string::size_type end(int n) const;
 264   std::string match(int n) const;
 265
 266 private:
 267   const char* startp[NSUBEXP];
 268   const char* endp[NSUBEXP];
 269   char  regstart;                       // Internal use only
 270   char  reganch;                        // Internal use only
 271   const char* regmust;                  // Internal use only
 272   int   regmlen;                        // Internal use only
 273   char* program;
 274   int   progsize;
 275   const char* searchstring;
 276 };
 277
 278 /**
 279  * Create an empty regular expression.
 280  */
 281 inline cmRegularExpression::cmRegularExpression ()
 282 {
 283   this->program = 0;
 284 }
 285
 286 /**
 287  * Creates a regular expression from string s, and
 288  * compiles s.
 289  */
 290 inline cmRegularExpression::cmRegularExpression (const char* s)
 291 {
 292   this->program = 0;
 293   if ( s )
 294     {
 295     this->compile(s);
 296     }
 297 }
 298
 299 /**
 300  * Destroys and frees space allocated for the regular expression.
 301  */
 302 inline cmRegularExpression::~cmRegularExpression ()
 303 {
 304 //#ifndef WIN32
 305   delete [] this->program;
 306 //#endif
 307 }
 308
 309 /**
 310  * Set the start position for the regular expression.
 311  */
 312 inline std::string::size_type cmRegularExpression::start () const
 313 {
 314   return(this->startp[0] - searchstring);
 315 }
 316
 317
 318 /**
 319  * Returns the start/end index of the last item found.
 320  */
 321 inline std::string::size_type cmRegularExpression::end () const
 322 {
 323   return(this->endp[0] - searchstring);
 324 }
 325
 326 /**
 327  * Returns true if two regular expressions have different
 328  * compiled program for pattern matching.
 329  */
 330 inline bool cmRegularExpression::operator!= (const cmRegularExpression& r) const
 331 {
 332   return(!(*this == r));
 333 }
 334
 335 /**
 336  * Returns true if a valid regular expression is compiled
 337  * and ready for pattern matching.
 338  */
 339 inline bool cmRegularExpression::is_valid () const
 340 {
 341   return (this->program != 0);
 342 }
 343
 344
 345 inline void cmRegularExpression::set_invalid ()
 346 {
 347 //#ifndef WIN32
 348   delete [] this->program;
 349 //#endif
 350   this->program = 0;
 351 }
 352
 353 /**
 354  * Return start index of nth submatch. start(0) is the start of the full match.
 355  */
 356 inline std::string::size_type cmRegularExpression::start(int n) const
 357 {
 358   return this->startp[n] - searchstring;
 359 }
 360
 361
 362 /**
 363  * Return end index of nth submatch. end(0) is the end of the full match.
 364  */
 365 inline std::string::size_type cmRegularExpression::end(int n) const
 366 {
 367   return this->endp[n] - searchstring;
 368 }
 369
 370 /**
 371  * Return nth submatch as a string.
 372  */
 373 inline std::string cmRegularExpression::match(int n) const
 374 {
 375   return std::string(this->startp[n], this->endp[n] - this->startp[n]);
 376 }
 377
 378 #endif // cmRegularExpressionh