// -*- c++ -*-

/*
 * jakelib2-regex - Regular Expressions for Jakelib2
 * Copyright (C) 2003 Florian Wolff  (florian@donuz.de)
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * $Id: Pattern.h,v 1.1 2003/09/24 17:14:54 florian Exp $
 */

#ifndef INCLUDE_JAKELIB2_UTIL_REGEX_PATTERN_H
# define INCLUDE_JAKELIB2_UTIL_REGEX_PATTERN_H

# include "pcre.h"

namespace jakelib {
  namespace util {
    class ArrayList;

    namespace regex {
      class Matcher;
      
      /**
       * The representation of a compiled Perl-compatible regular expression.
       *
       * <b>Regular expression support is provided by the PCRE library package,
       * which is open source software, written by Philip Hazel, and copyright
       * by the University of Cambridge, England. (http://www.pcre.org)</b>
       *
       * The following example shows how to test whether a regular expression matches
       * a given string:
       *
       * <code><pre>
       * Pattern* p = Pattern::compile("[0-9]*");
       * Matcher* m = p->matcher(" +31415 ");
       * if (m->matches()) { ... } </pre></code>
       *
       * A short form for this example is:
       *
       * <code><pre>
       * if (Pattern::matches("[0-9]*", " +31415 ")) { ... } </pre></code>
       *
       * The syntax and semantics of the regular expressions supported by PCRE are described
       * below. Regular expressions are also described in the Perl  documentation  and  in  a
       * number  of  other books, some of which have copious examples. Jeffrey Friedl's
       * "Mastering Regular Expressions", published by O'Reilly (ISBN 1-56592-257), covers
       * them in great detail.
       *
       * The  description here is intended as reference documentation. The basic operation of
       * PCRE is on strings of bytes.
       *
       * A regular expression is a pattern that is matched against a subject string from left
       * to right. Most characters stand for themselves in a pattern, and match the
       * corresponding characters in the subject. As a trivial example, the pattern
       *
       * <tt>The quick brown fox</tt>
       *
       * matches a portion of a subject string that is identical to itself. The power of
       * regular expressions comes from the ability to include alternatives and repetitions in
       * the pattern. These are encoded in the pattern by the use of meta-characters, which
       * do not stand for themselves but instead are interpreted in some special way.
       *
       * There are two different sets of meta-characters: those that are recognized anywhere
       * in the pattern except within square brackets, and those that are recognized in
       * square brackets. Outside square brackets, the meta-characters are as follows:
       *
       * <table>
       * <tr><td><tt>\\</tt></td>  <td>general escape character with several uses</td></tr>
       * <tr><td><tt>^</tt></td>  <td>assert start of subject (or line, in multiline mode)</td></tr>
       * <tr><td><tt>$</tt></td>  <td>assert end of subject (or line, in multiline mode)</td></tr>
       * <tr><td><tt>.</tt></td>  <td>match any character except newline (by default)</td></tr>
       * <tr><td><tt>[</tt></td>  <td>start character class definition</td></tr>
       * <tr><td><tt>|</tt></td>  <td>start of alternative branch</td></tr>
       * <tr><td><tt>(</tt></td>  <td>start subpattern</td></tr>
       * <tr><td><tt>)</tt></td>  <td>end subpattern</td></tr>
       * <tr><td><tt>?</tt></td>  <td>extends the meaning of <tt>(</tt>
       *        also 0 or 1 quantifier
       *        also quantifier minimizer</td></tr>
       * <tr><td><tt>*</tt></td>  <td>0 or more quantifier</td></tr>
       * <tr><td><tt>+</tt></td>  <td>1 or more quantifier</td></tr>
       * <tr><td><tt>{</tt></td>  <td>start min/max quantifier</td></tr>
       * </table>
       *
       * Part of a pattern that is in square brackets is called a  "character  class".  In  a
       * character class the only meta-characters are:
       *
       * <table>
       * <tr><td><tt>\\</tt></td>  <td>general escape character</td></tr>
       * <tr><td><tt>^</tt></td>  <td>negate the class, but only if the first character</td></tr>
       * <tr><td><tt>-</tt></td>  <td>indicates character range</td></tr>
       * <tr><td><tt>]</tt></td>  <td>terminates the character class</td></tr>
       * </table>
       *
       * The following sections describe the use of each of the meta-characters.
       *
       * 
       * <b>BACKSLASH</b>
       *
       * The  backslash  character  has  several  uses.  Firstly, if it is followed by a
       * non-alphameric character, it takes away any special meaning  that  character  may  have.
       * This use of backslash as an escape character applies both inside and outside
       * character classes.
       *
       * For example, if you want to match a "<tt>*</tt>" character, you write "<tt>\\*</tt>"
       * in the pattern.
       * This  applies whether or not the following character would otherwise be interpreted
       * as a meta-character, so it is always safe to precede a non-alphameric
       * with "<tt>\\</tt>" to
       * specify that it stands for itself. In particular, if you want to match a backslash,
       * you write "<tt>\\\\</tt>".
       *
       * A second use of backslash provides a way of encoding non-printing characters in
       * patterns in a visible manner. There is no restriction on the appearance of non-printing
       * characters, apart from the binary zero that terminates a pattern, but when a pattern
       * is being prepared by text editing, it is usually easier to use one of the  following
       * escape sequences than the binary character it represents:
       *
       * <table>
       * <tr><td><tt>\\a</tt></td>  <td>alarm, that is, the BEL character (hex 07)</td></tr>
       * <tr><td><tt>\\cx</tt></td>  <td>"control-x", where x is any character</td></tr>
       * <tr><td><tt>\\e</tt></td>  <td>escape (hex 1B)</td></tr>
       * <tr><td><tt>\\f</tt></td>  <td>formfeed (hex 0C)</td></tr>
       * <tr><td><tt>\\n</tt></td>  <td>newline (hex 0A)</td></tr>
       * <tr><td><tt>\\r</tt></td>  <td>carriage return (hex 0D)</td></tr>
       * <tr><td><tt>\\t</tt></td>  <td>tab (hex 09)</td></tr>
       * <tr><td><tt>\\xhh</tt></td>  <td>character with hex code hh</td></tr>
       * <tr><td><tt>\\ddd</tt></td>  <td>character with octal code ddd, or backreference</td></tr>
       * </table>
       *
       * The precise effect of "<tt>\\cx</tt>" is as follows: if "<tt>x</tt>" is a lower
       * case letter, it is converted to upper case. Then bit 6 of the character (hex 40)
       * is inverted.  Thus  "<tt>\\cz</tt>"
       * becomes hex 1A, but "<tt>\\c{</tt>" becomes hex 3B, while "<tt>\\c;</tt>" becomes hex 7B.
       *
       * After  "<tt>\\x</tt>", up to two hexadecimal digits are read (letters can be in upper or lower
       * case).
       *
       * After "<tt>\\0</tt>" up to two further octal digits are read. In  both  cases,
       * if  there  are fewer  than  two  digits,  just  those  that are present are used.
       * Thus the sequence "<tt>\\0\\x\\07</tt>" specifies two binary zeros followed by
       * a BEL  character.   Make  sure  you
       * supply  two digits after the initial zero if the character that follows is itself an
       * octal digit.
       *
       * The handling of a backslash followed by a digit other than 0 is  complicated.
       * Outside  a character class, PCRE reads it and any following digits as a decimal number.
       * If the number is less than 10, or if there have been at  least  that  many  previous
       * capturing left parentheses in the expression, the entire sequence is taken as a back
       * reference. A description of how this works is given later, following the  discussion
       * of parenthesized subpatterns.
       *
       * Inside  a character class, or if the decimal number is greater than 9 and there have
       * not been that many capturing subpatterns, PCRE re-reads up  to  three  octal  digits
       * following  the  backslash,  and generates a single byte from the least significant 8
       * bits of the value. Any subsequent digits stand for themselves.  For example:
       *
       * <table>
       * <tr><td><tt>\\040</tt></td>  <td>is another way of writing a space</td></tr>
       * <tr><td><tt>\\40</tt></td>  <td>is the same, provided there are fewer than 40
       *                                 previous capturing subpatterns</td></tr>
       * <tr><td><tt>\\7</tt></td>  <td>is always a back reference</td></tr>
       * <tr><td><tt>\\11</tt></td>  <td>might be a back reference, or another way of
       *                                 writing a tab</td></tr>
       * <tr><td><tt>\\011</tt></td>  <td>is always a tab</td></tr>
       * <tr><td><tt>\\0113</tt></td>  <td>is a tab followed by the character "3"</td></tr>
       * <tr><td><tt>\\113</tt></td>  <td>is the character with octal code 113 (since there
       *                                  can be no more than 99 back references)</td></tr>
       * <tr><td><tt>\\377</tt></td>  <td>is a byte consisting entirely of 1 bits</td></tr>
       * <tr><td><tt>\\81</tt></td>  <td>is either a back reference, or a binary zero
       *                                 followed by the two characters "8" and "1"</td></tr>
       * </table>
       *
       * Note that octal values of 100 or greater must not be introduced by a  leading  zero,
       * because no more than three octal digits are ever read.
       *
       * All  the  sequences that define a single byte value can be used both inside and
       * outside character classes. In addition, inside a character class, the sequence
       * "<tt>\\b</tt>"  is interpreted  as the backspace character (hex 08).
       * Outside a character class it has a different meaning (see below).
       *
       * The third use of backslash is for specifying generic character types: 
       *
       * <table>
       * <tr><td><tt>\\d</tt></td>  <td>any decimal digit</td></tr>
       * <tr><td><tt>\\D</tt></td>  <td>any character that is not a decimal digit</td></tr>
       * <tr><td><tt>\\s</tt></td>  <td>any whitespace character</td></tr>
       * <tr><td><tt>\\S</tt></td>  <td>any character that is not a whitespace character</td></tr>
       * <tr><td><tt>\\w</tt></td>  <td>any "word" character</td></tr>
       * <tr><td><tt>\\W</tt></td>  <td>any "non-word" character</td></tr>
       * </table>
       * 
       * Each pair of escape sequences partitions the complete set of
       * characters  into  two  disjoint  sets.  Any  given character
       * matches one, and only one, of each pair.
       * 
       * A "word" character is any letter or digit or the  underscore
       * character,  that  is,  any  character which can be part of a
       * Perl "word". The definition of letters and  digits  is  controlled
       * by PCRE's character tables, and may vary if localespecific
       * matching is  taking  place  (see  "Locale  support"
       * above). For example, in the "<tt>fr</tt>" (French) locale, some character
       *  codes greater than 128 are used for accented  letters,
       * and these are matched by \c \\w.
       * 
       * These character type sequences can appear  both  inside  and
       * outside  character classes. They each match one character of
       * the appropriate type. If the current matching  point  is  at
       * the end of the subject string, all of them fail, since there
       * is no character to match.
       * 
       * The fourth use of backslash is  for  certain  simple  assertions.
       *  An assertion specifies a condition that has to be met
       * at a particular point in  a  match,  without  consuming  any
       * characters  from  the subject string. The use of subpatterns
       * for more complicated  assertions  is  described  below.  The
       * backslashed assertions are
       * 
       * <table>
       * <tr><td><tt>\\b</tt></td>  <td>word boundary</td></tr>
       * <tr><td><tt>\\B</tt></td>  <td>not a word boundary</td></tr>
       * <tr><td><tt>\\A</tt></td>  <td>start of subject (independent of multiline mode)</td></tr>
       * <tr><td><tt>\\Z</tt></td>  <td>end of subject or newline at  end  (independent  of</td></tr>
       * multiline mode)</td></tr>
       * <tr><td><tt>\\z</tt></td>  <td>end of subject (independent of multiline mode)</td></tr>
       * </table>
       * 
       * These assertions may not appear in  character  classes  (but
       * note that "<tt>\\b</tt>" has a different meaning, namely the backspace
       * character, inside a character class).
       * 
       * A word boundary is a position in the  subject  string  where
       * the current character and the previous character do not both
       * match \c \\w or \c \\W (i.e. one matches \c \\w and  the  other  matches
       * \c \\W),  or the start or end of the string if the first or last
       * character matches \\w, respectively.
       * 
       * The \c \\A, \c \\Z, and \c \\z assertions differ  from  the  traditional
       * circumflex  and  dollar  (described below) in that they only
       * ever match at the very start and end of the subject  string,
       * whatever  options  are  set.
       * If the startoffset argument of \c Matcher::find() is  non-zero,
       * \c \\A can never match. The
       * difference between \c \\Z and \c \\z is that \c \\Z  matches  before  a
       * newline  that is the last character of the string as well as
       * at the end of the string, whereas \\z  matches  only  at  the
       * end.
       * 
       * 
       * <b>CIRCUMFLEX AND DOLLAR</b>
       *
       * Outside a character class, in the default matching mode, the
       * circumflex  character  is an assertion which is true only if
       * the current matching point is at the start  of  the  subject
       * string. If the startoffset argument of Matcher::find() is nonzero,
       * circumflex can never match. Inside a character  class,
       * circumflex has an entirely different meaning (see below).
       * 
       * Circumflex need not be the first character of the pattern if
       * a  number of alternatives are involved, but it should be the
       * first thing in each alternative in which it appears  if  the
       * pattern is ever to match that branch. If all possible alternatives
       * start with a circumflex, that is, if the pattern  is
       * constrained to match only at the start of the subject, it is
       * said to be an "anchored" pattern. (There are also other constructs
       * that can cause a pattern to be anchored.)
       * 
       * A dollar character is an assertion which is true only if the
       * current  matching point is at the end of the subject string,
       * or immediately before a newline character that is  the  last
       * character in the string (by default). Dollar need not be the
       * last character of the pattern if a  number  of  alternatives
       * are  involved,  but it should be the last item in any branch
       * in which it appears.  Dollar has no  special  meaning  in  a
       * character class.
       * 
       * The meanings of the circumflex  and  dollar  characters  are
       * changed  if  the  \c MULTILINE option is set. When this is
       * the case,  they  match  immediately  after  and  immediately
       * before an internal "<tt>\\n</tt>" character, respectively, in addition
       * to matching at the start and end of the subject string.  For
       * example, the pattern <tt>/^abc$/</tt> matches the subject string
       * "<tt>def\\nabc</tt>" in multiline mode, but not otherwise. Consequently,
       * patterns  that  are  anchored  in single line mode
       * because all branches start with "<tt>^</tt>" are not anchored in multiline
       * mode, and a match for circumflex is possible when the
       * startoffset argument of \c Matcher::find() is non-zero.
       * 
       * Note that the sequences \c \\A, \c \\Z, and \c \\z can be used to  match
       * the  start  and end of the subject in both modes, and if all
       * branches of a pattern start with \c \\A it is  always  anchored,
       * whether \c MULTILINE is set or not.
       * 
       * 
       * <b>FULL STOP (PERIOD, DOT)</b>
       *
       * Outside a character class, a dot in the pattern matches  any
       * one character in the subject, including a non-printing character,
       * but not (by default)  newline.   If  the  \c DOTALL
       * option  is set, dots match newlines as well. The handling of
       * dot is entirely independent of the  handling  of  circumflex
       * and  dollar,  the  only  relationship  being  that they both
       * involve newline characters. Dot has no special meaning in  a
       * character class.
       * 
       * 
       * <b>SQUARE BRACKETS</b>
       *
       * An opening square bracket introduces a character class, terminated
       * by  a  closing  square  bracket.  A  closing square
       * bracket on its own is  not  special.  If  a  closing  square
       * bracket  is  required as a member of the class, it should be
       * the first data character in the class (after an initial circumflex,
       * if present) or escaped with a backslash.
       * 
       * A character class matches a single character in the subject;
       * the  character  must  be in the set of characters defined by
       * the class, unless the first character in the class is a circumflex,
       * in which case the subject character must not be in
       * the set defined by the class. If a  circumflex  is  actually
       * required  as  a  member  of  the class, ensure it is not the
       * first character, or escape it with a backslash.
       * 
       * For example, the character class <tt>[aeiou]</tt> matches  any  lower
       * case vowel, while <tt>[^aeiou]</tt> matches any character that is not
       * a lower case vowel. Note that a circumflex is just a convenient
       * notation for specifying the characters which are in
       * the class by enumerating those that are not. It  is  not  an
       * assertion:  it  still  consumes a character from the subject
       * string, and fails if the current pointer is at  the  end  of
       * the string.
       * 
       * When caseless matching  is  set,  any  letters  in  a  class
       * represent  both their upper case and lower case versions, so
       * for example, a caseless <tt>[aeiou]</tt> matches "A" as well as  "a",
       * and  a caseless <tt>[^aeiou]</tt> does not match "A", whereas a caseful
       * version would.
       * 
       * The newline character is never treated in any special way in
       * character  classes,  whatever the setting of the \c DOTALL
       * or \c MULTILINE options is. A  class  such  as  <tt>[^a]</tt>  will
       * always match a newline.
       * 
       * The minus (hyphen) character can be used to specify a  range
       * of  characters  in  a  character  class.  For example, \c [d-m]
       * matches any letter between \c d and \c m, inclusive.  If  a  minus
       * character  is required in a class, it must be escaped with a
       * backslash or appear in a position where it cannot be  interpreted
       * as indicating a range, typically as the first or last
       * character in the class.
       * 
       * It is not possible to have the literal character "<tt>]</tt>" as  the
       * end  character  of  a  range.  A  pattern such as \c [W-]46] is
       * interpreted as a class of two characters ("<tt>W</tt>" and "<tt>-</tt>")  followed
       * by a literal string "<tt>46]</tt>", so it would match "<tt>W46]</tt>" or
       * "<tt>-46]</tt>". However, if the "<tt>]</tt>" is escaped with a  backslash  it
       * is  interpreted  as  the end of range, so \c [W-\\]46] is interpreted
       * as a single class containing a range followed by  two
       * separate characters. The octal or hexadecimal representation
       * of "<tt>]</tt>" can also be used to end a range.
       * 
       * Ranges operate in ASCII collating sequence. They can also be
       * used  for  characters  specified  numerically,  for  example
       * \c [\\000-\\037]. If a range that includes letters is  used  when
       * caseless  matching  is set, it matches the letters in either
       * case. For example, \c [W-c] is equivalent  to  \c [][\\^_`wxyzabc],
       * matched  caselessly,  and  if  character tables for the "<tt>fr</tt>"
       * locale are in use, \c [\\xc8-\\xcb] matches accented E characters
       * in both cases.
       * 
       * The character types \c \\d, \c \\D, \c \\s, \c \\S, \c \\w,  and  \c \\W  may  also
       * appear  in  a  character  class, and add the characters that
       * they match to the class. For example, \c [\\dABCDEF] matches any
       * hexadecimal  digit.  A  circumflex  can conveniently be used
       * with the upper case character types to specify a  more  restricted
       *  set of characters than the matching lower case type.
       * For example, the class \c [^\\W_] matches any letter  or  digit,
       * but not underscore.
       * 
       * All non-alphameric characters other than \c \\, \c -, \c ^  (at  the
       * start)  and  the  terminating \c ] are non-special in character
       * classes, but it does no harm if they are escaped.
       * 
       *
       * <b>POSIX CHARACTER CLASSES</b>
       *
       * Perl 5.6 (not yet released at the time of writing) is  going
       * to  support  the POSIX notation for character classes, which
       * uses names enclosed by \c [: and \c :] within the enclosing
       * square brackets. PCRE supports this notation. For example,
       * 
       * \c [01[:alpha:]%]
       * 
       * matches "<tt>0</tt>", "<tt>1</tt>", any alphabetic character, or "<tt>%</tt>".
       * The supported class names are:
       * 
       * <table>
       * <tr><td>\c alnum </td>  <td>letters and digits</td></tr>
       * <tr><td>\c alpha </td>  <td>letters</td></tr>
       * <tr><td>\c ascii </td>  <td>character codes 0 - 127</td></tr>
       * <tr><td>\c cntrl </td>  <td>control characters</td></tr>
       * <tr><td>\c digit </td>  <td>decimal digits (same as <tt>\\d</tt>)</td></tr>
       * <tr><td>\c graph </td>  <td>printing characters, excluding space</td></tr>
       * <tr><td>\c lower </td>  <td>lower case letters</td></tr>
       * <tr><td>\c print </td>  <td>printing characters, including space</td></tr>
       * <tr><td>\c punct </td>  <td>printing characters, excluding letters and digits</td></tr>
       * <tr><td>\c space </td>  <td>white space (same as <tt>\\s</tt>)</td></tr>
       * <tr><td>\c upper </td>  <td>upper case letters</td></tr>
       * <tr><td>\c word  </td>  <td>"word" characters (same as <tt>\\w</tt>)</td></tr>
       * <tr><td>\c xdigit </td>  <td>hexadecimal digits</td></tr>
       * </table>
       *
       * The names "<tt>ascii</tt>" and "<tt>word</tt>" are  Perl  extensions.  Another
       * Perl  extension is negation, which is indicated by a \c ^ character
       * after the colon. For example,
       * 
       * \c [12[:^digit:]]
       * 
       * matches "<tt>1</tt>", "<tt>2</tt>", or any non-digit.  PCRE  (and  Perl)  also
       * recognize the POSIX syntax \c [.ch.] and \c [=ch=] where "<tt>ch</tt>" is a
       * "collating element", but these are  not  supported,  and  an
       * error is given if they are encountered.
       * 
       * 
       * <b>VERTICAL BAR</b>
       *
       * Vertical bar characters are  used  to  separate  alternative
       * patterns. For example, the pattern
       * 
       * \c gilbert|sullivan
       * 
       * matches either "<tt>gilbert</tt>" or "<tt>sullivan</tt>".
       * Any number of alternatives
       * may  appear,  and an empty alternative is permitted
       * (matching the empty string). The  matching  process  tries
       * each  alternative in turn, from left to right, and the first
       * one that succeeds is used. If the alternatives are within  a
       * subpattern  (defined  below), "succeeds" means matching the
       * rest of the main pattern as well as the alternative  in  the
       * subpattern.
       * 
       * 
       * <b>INTERNAL OPTION SETTING</b>
       *
       * The settings of \c CASE_INSENSITIVE, \c MULTILINE and \c DOTALL,
       * can be changed from within the pattern by
       * a sequence of Perl option letters enclosed between "<tt>(?</tt>"  and
       * "<tt>)</tt>". The option letters are
       * 
       * <table>
       * <tr><td><tt>i</tt></td>  <td>for \c CASE_INSENSITIVE </td></tr>
       * <tr><td><tt>m</tt></td>  <td>for \c MULTILINE </td></tr>
       * <tr><td><tt>s</tt></td>  <td>for \c DOTALL </td></tr>
       * </table>
       * 
       * For example, \c (?im) sets caseless, multiline matching. It  is
       * also possible to unset these options by preceding the letter
       * with a hyphen, and a combined setting and unsetting such  as
       * \c (?im-s),  which sets \c CASE_INSENSITIVE and \c MULTILINE while
       * unsetting \c DOTALL, is also  permitted.
       * If  a  letter  appears both before and after the hyphen, the
       * option is unset.
       * 
       * The scope of these option changes depends on  where  in  the
       * pattern  the  setting  occurs. For settings that are outside
       * any subpattern (defined below), the effect is the same as if
       * the  options were set or unset at the start of matching. The
       * following patterns all behave in exactly the same way:
       * 
       * \c (?i)abc
       * \c a(?i)bc
       * \c ab(?i)c
       * \c abc(?i)
       * 
       * which in turn is the same as compiling the pattern abc  with
       * \c CASE_INSENSITIVE set. In other words, such "top level" settings
       * apply to the whole pattern  (unless  there  are  other
       * changes  inside subpatterns). If there is more than one setting
       * of the same option at top level, the rightmost  setting
       * is used.
       * 
       * If an option change occurs inside a subpattern,  the  effect
       * is  different.  This is a change of behaviour in Perl 5.005.
       * An option change inside a subpattern affects only that  part
       * of the subpattern that follows it, so
       * 
       * \c (a(?i)b)c
       * 
       * matches \c abc  and \c aBc  and  no  other   strings   (assuming
       * \c CASE_INSENSITIVE is not used).  By this means, options can be
       * made to have different settings in different  parts  of  the
       * pattern.  Any  changes  made  in one alternative do carry on
       * into subsequent branches within  the  same  subpattern.  For
       * example,
       * 
       * \c (a(?i)b|c)
       * 
       * matches \c ab, \c aB, \c c, and \c C, even though when  matching
       * \c C the first branch is abandoned before the option setting.
       * This is because the effects of  option  settings  happen  at
       * compile  time. There would be some very weird behaviour otherwise.
       * 
       * 
       * <b>SUBPATTERNS</b>
       *
       * Subpatterns are delimited by parentheses  (round  brackets),
       * which can be nested.  Marking part of a pattern as a subpattern
       * does two things:
       * 
       * 1. It localizes a set of alternatives. For example, the pat-
       * tern
       * 
       * \c cat(aract|erpillar|)
       * 
       * matches one of the words "\c cat",  "\c cataract",  or  "\c caterpillar".
       * Without  the  parentheses, it would match "\c cataract",
       * "\c erpillar" or the empty string.
       * 
       * 2. It sets up the subpattern as a capturing  subpattern  (as
       * defined  above). When the whole pattern matches, that portion
       * of the subject string that matched  the  subpattern  is
       * passed  back  to  the  caller  via  the \c Matcher::group() method
       * Opening parentheses are counted  from  left  to
       * right (starting from 1) to obtain the numbers of the capturing
       * subpatterns.
       * 
       * For example, if the string "<tt>the red king</tt>" is matched against
       * the pattern
       * 
       * <tt>the ((red|white) (king|queen))</tt>
       * 
       * the captured substrings are "<tt>red king</tt>", "\c red",  and  "\c king",
       * and are numbered 1, 2, and 3, respectively.
       * 
       * The fact that plain parentheses fulfil two functions is  not
       * always  helpful.  There are often times when a grouping subpattern
       * is required without a capturing requirement.  If  an
       * opening parenthesis is followed by "\c ?:", the subpattern does
       * not do any capturing, and is not counted when computing  the
       * number of any subsequent capturing subpatterns. For example,
       * if the string "<tt>the white queen</tt>" is matched against the  pat-
       * tern
       * 
       * <tt>the ((?:red|white) (king|queen))</tt>
       * 
       * the captured substrings are "<tt>white queen</tt>" and  "\c queen",  and
       * are  numbered  1  and 2. The maximum number of captured substrings
       * is 99, and the maximum number  of  all  subpatterns,
       * both capturing and non-capturing, is 200.
       * 
       * As a  convenient  shorthand,  if  any  option  settings  are
       * required  at  the  start  of a non-capturing subpattern, the
       * option letters may appear between the "\c ?" and the "\c :".  Thus
       * the two patterns
       * 
       * \c (?i:saturday|sunday)
       * \c (?:(?i)saturday|sunday)
       * 
       * match exactly the same set of strings.  Because  alternative
       * branches  are  tried from left to right, and options are not
       * reset until the end of the subpattern is reached, an  option
       * setting  in  one  branch does affect subsequent branches, so
       * the above patterns match "\c SUNDAY" as well as "\c Saturday".
       * 
       * <b>Copyright notice:</b>
       * <pre>Regular expression support is provided by the PCRE library package,
       * which is open source software, written by Philip Hazel, and copyright
       * by the University of Cambridge, England.</pre>
       *
       * @class Pattern
       * @version $Id: Pattern.h,v 1.1 2003/09/24 17:14:54 florian Exp $
       * @author Philip Hazel (ph10@cam.ac.uk), Florian 'Overflo' Wolff (florian@donuz.de)
       */
      class Pattern : public jakelib::lang::Object
      {
        friend class Matcher;

      public:
        ~Pattern();

      protected:
        Pattern(jakelib::lang::String* pattern, jint flags);

      public:
        /**
         * @brief Compiles the given regular expression and returns its compiled
         * representation.
         *
         * @param pattern The regular expression
         * @param flags  A bit-wise flag that may include one or more of the following:
         * \c CASE_INSENSITIVE, \c MULTILINE, \c DOTALL.
         */
        static Pattern* compile(jakelib::lang::String* pattern, jint flags = 0);

        /**
         * @brief A wrapper for <tt>static Pattern* compile(String* pattern, jint flags)</tt>.
         */
        static Pattern* compile(char* pattern, jint flags = 0);

        /**
         * @brief Returns the bit-wise flag that was set when the expression was compiled.
         */
        jint flags();

        /**
         * @brief Returns the regular expression itself.
         */
        jakelib::lang::String* pattern();

        /**
         * @brief Splits the given sequence of characters around matches of the expression.
         *
         * @param input The \c String to be split up
         * @param limit If \c limit is a non-zero, positive number, the output will at most
         *              contain \c limit entries.
         * @return An \c ArrayList containing the substrings.
         */
        jakelib::util::ArrayList* split(jakelib::lang::String* input, jint limit = 0);

        /**
         * @brief A wrapper for <tt>ArrayList* split(String* pattern, jint limit)</tt>.
         */
        jakelib::util::ArrayList* split(char* input, jint limit = 0);

        /**
         * @brief Returns a \c Matcher for the given input \c String.
         */
        Matcher* matcher(jakelib::lang::String* input);

        /**
         * @brief A wrapper for <tt>Matcher* matcher(String* input)</tt>.
         */
        Matcher* matcher(char* input);

        /**
         * @brief Tests whether the given regular expression matches the given \c String.
         *
         * This is just a convenience method that compiles the given expression,
         * obtains a \c Matcher and tests whether the expression matches the
         * \c input. If you intend to match your expression more than only once,
         * you should not use \c matches but compile the expression explicitly
         * and reuse the resulting \c Pattern.
         *
         * @param pattern The regular expression
         * @param input The input \c String to match against
         */
        static jboolean matches(jakelib::lang::String* pattern, jakelib::lang::String* input);

        /** 
         * @brief A wrapper for <tt>jboolean matches(String* pattern, String* input)</tt>.
         */
        static jboolean matches(char* pattern, char* input);

        /** @brief Enabled case-insensitive matching. */
        static const jint CASE_INSENSITIVE;

        /**
         * @brief Enables multiline mode: <tt>^</tt> and <tt>$</tt> will match at
         * the beginning/end of a line.
         */ 
        static const jint MULTILINE;

        /**
         * @brief Enables dotall mode: "<tt>.</tt>" will match any character including
         * the line terminator.
         */
        static const jint DOTALL;

        JAKELIB_DECLARE_CLASS(Pattern);

      protected:
        pcre *re;
        jakelib::lang::String* _pattern;
        jint _flags;
        jint captureCount;
      };

    }
  }
}

#endif

