mrw-cxx/mrw/regexp.hpp

/** @file

    $Id$

    $Date$
    $Author$

    @copy © Marc Wäckerlin
    @license LGPL, see file <a href="license.html">COPYING</a>

    $Log$
    Revision 1.1  2004/12/14 20:20:30  marc
    initial version


*/

#include <regex.h>
#include <string>
#include <stdexcept>

namespace mrw {

  /** @defgroup regexp Regular Expressions

      A simple wrapper around the C POSIX regular expression library
      with a C++ Interface.

      Usage sample:
      @code
        std::ifstream file(filename);           // read from a file
        mrw::RegExp findBrackets("^\\[.*\\]$"); // look for "[some text]"
        for (std::string line;
             mrw::getline(file, line);)         // read line by line
          if (findBrackets(line))               // check for regular expression
            found(line);                        // found, do something
      @endcode

  */

  /** @brief a regular expression
      
      This class manages a simple regular expression.
      
      Usage sample:
      @code
        std::ifstream file(filename);           // read from a file
        mrw::RegExp findBrackets("^\\[.*\\]$"); // look for "[some text]"
        for (std::string line;
             mrw::getline(file, line);)         // read line by line
          if (findBrackets(line))               // check for regular expression
            found(line);                        // found, do something
      @endcode

  */
  class RegExp {
  
  public:

    /** @brief flags that influence regular expressions

        Flag @c newline treats a newline in the text to be compared as
        dividing the text into multiple lines, so that @c $ can match
        before the newline and @c ^ can match after.  Also, don't
        permit @c . to match a newline, and don't permit @c [^...] to
        match a newline.

        Otherwise, newline acts like any other ordinary character.

        Flag @c nosub is used internally, don't specify it.

    */
    enum Flags {
      extended = REG_EXTENDED,  ///< use extended regular expressions
      icase    = REG_ICASE,     ///< ignore case in match
      nosub    = REG_NOSUB,     ///< @b internal (report only success/fail)
      newline  = REG_NEWLINE    ///< treat lines individually
    };

    /** @brief define a new regular expression

        The regular expression is compiled on instanciation and can
        then be matced several times on different texts.

        @param pattern the regular expression pattern, thee the @c man
                       page for POSIX regular expressions (on linux: @c
                       info&nbsp;7&nbsp;regex)
        @param flags   special flags, they default to extended|nosub and
                       should consist of the Flag values combined with @c |

        @throw std::invalid_argument if pattern compilation fails
    */
    RegExp(const std::string& pattern, int flags = extended)
      throw(std::exception, std::bad_exception);

    /** @brief cleans up expression from memory */
    ~RegExp() throw();

    /** @brief apply the expression, match a text against the expression

        @param text a text that is matched against the regular expression
        @return
          - true if @c text matches
          - false otherwise */
    bool operator()(const std::string& text) const throw();
  
  private:
  
    regex_t _regex;
  
  };
}