libghc-pcre-light-doc 0.4-6 / usr / share / doc / libghc-pcre-light-doc / html / pcre-light.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A small, efficient and portable regex library for Perl 5 compatible regular expressions
--   
--   A small, efficient and portable regex library for Perl 5 compatible
--   regular expressions
--   
--   The PCRE library is a set of functions that implement regular
--   expression pattern matching using the same syntax and semantics as
--   Perl 5.
--   
--   Test coverage data for this library is available at:
--   <a>http://code.haskell.org/~dons/tests/pcre-light/hpc_index.html</a>
@package pcre-light
@version 0.4


-- | Documentation based on <i>man pcreapi</i>, written by Philip Hazel,
--   2007.
--   
--   License : BSD3 Maintainer: Don Stewart <a>dons@galois.com</a>
--   Stability : experimental Portability: CPP, FFI Tested with: GHC 6.8.2
--   
--   Raw FFI bindings to PCRE functions and constants.
module Text.Regex.PCRE.Light.Base
type PCRE = ()

-- | An abstract pointer to a compiled PCRE Regex structure The structure
--   allocated by the PCRE library will be deallocated automatically by the
--   Haskell storage manager.
data Regex
Regex :: {-# UNPACK #-} !(ForeignPtr PCRE) -> {-# UNPACK #-} !ByteString -> Regex

-- | Compile a pattern to an internal form. The pattern is a C string
--   terminated by a binary zero. A pointer to a single block of memory
--   that is obtained via pcre_malloc is returned. It is up to the caller
--   to free the memory (via pcre_free) when it is no longer required
--   
--   The options argument contains various bit settings that affect the
--   compilation. It should be zero if no options are required.
--   
--   If errptr is NULL, pcre_compile() returns NULL immediately. Otherwise,
--   if compilation of a pattern fails, pcre_compile() returns NULL, and
--   sets the variable pointed to by errptr to point to a textual error
--   message.
--   
--   The offset from the start of the pattern to the character where the
--   error was discovered is placed in the variable pointed to by
--   erroffset, which must not be NULL.
c_pcre_compile :: CString -> PCREOption -> Ptr CString -> Ptr CInt -> Ptr Word8 -> IO (Ptr PCRE)

-- | This function matches a compiled regular expression against a given
--   subject string, using a matching algorithm that is similar to Perl's.
--   It returns offsets to captured substrings.
--   
--   Its arguments are, in order:
--   
--   <ul>
--   <li><tt>code</tt> Points to the compiled pattern (result of
--   pcre_compile)</li>
--   <li><a>extra</a> Points to an associated pcre_extra structure (result
--   of pcre_study), or is NULL</li>
--   <li><tt>subject</tt> Points to the subject string</li>
--   <li><a>length</a> Length of the subject string, in bytes</li>
--   <li><tt>startoffset</tt> Offset in bytes in the subject at which to
--   start matching</li>
--   <li><tt>options</tt> Option bits</li>
--   <li><tt>ovector</tt> Points to a vector of ints for result
--   substrings</li>
--   <li><tt>ovecsize</tt> Number of elements in the vector (a multiple of
--   3)</li>
--   </ul>
--   
--   Note, subject not required to be null terminated.
c_pcre_exec :: Ptr PCRE -> Ptr PCREExtra -> Ptr Word8 -> CInt -> CInt -> PCREExecOption -> Ptr CInt -> CInt -> IO CInt

-- | Return information about a compiled pattern
c_pcre_fullinfo :: Ptr PCRE -> Ptr PCREExtra -> PCREInfo -> Ptr a -> IO CInt

-- | A type for PCRE compile-time options. These are newtyped CInts, which
--   can be bitwise-or'd together, using '(Data.Bits..|.)'
data PCREOption

-- | Combine a list of options into a single option, using bitwise (.|.)
combineOptions :: [PCREOption] -> PCREOption

-- | <a>anchored</a>
--   
--   If this bit is set, the pattern is forced to be <i>anchored</i>, that
--   is, it is constrained to match only at the first matching point in the
--   string that is being searched (the <i>subject string</i>). This effect
--   can also be achieved by appropriate constructs in the pattern itself,
--   which is the only way to do it in Perl.
anchored :: PCREOption

-- | <a>auto_callout</a>
--   
--   If this bit is set, <a>compile</a> automatically inserts callout
--   items, all with number 255, before each pattern item. For discussion
--   of the callout facility, see the man pcrecallout documentation
auto_callout :: PCREOption

-- | <tt>bsr_anycrlf</tt> and <tt>bsr_unicode</tt>
--   
--   These options (which are mutually exclusive) control what the \R
--   escape sequence matches. The choice is either to match only CR, LF, or
--   CRLF, or to match any Unicode new- line sequence. The default is
--   specified when PCRE is built. It can be overridden from within the
--   pattern, or by setting an option when a compiled pattern is matched.
--   
--   bsr_anycrlf :: PCREOption bsr_anycrlf = PCREOption bsr_anycrlf_cint
--   
--   <tt>bsr_unicode</tt>. See <tt>bse_anycrlf</tt>
--   
--   bsr_unicode :: PCREOption bsr_unicode = PCREOption bsr_unicode_cint
--   
--   <a>caseless</a>
--   
--   If this bit is set, letters in the pattern match both upper and lower
--   case letters. It is equivalent to Perl's /i option, and it can be
--   changed within a pattern by a (?i) option setting. In UTF-8 mode, PCRE
--   always understands the concept of case for characters whose values are
--   less than 128, so caseless matching is always possible. For characters
--   with higher values, the concept of case is supported if PCRE is
--   compiled with Unicode property sup- port, but not otherwise. If you
--   want to use caseless matching for characters 128 and above, you must
--   ensure that PCRE is compiled with Unicode property support as well as
--   with UTF-8 support.
caseless :: PCREOption

-- | <a>dollar_endonly</a>
--   
--   If this bit is set, a dollar metacharacter in the pattern matches only
--   at the end of the subject string. Without this option, a dollar also
--   matches immediately before a newline at the end of the string (but not
--   before any other newlines). The <a>dollar_endonly</a> option is
--   ignored if <a>multiline</a> is set. There is no equivalent to this
--   option in Perl, and no way to set it within a pattern.
dollar_endonly :: PCREOption

-- | <a>dotall</a>
--   
--   If this bit is set, a dot metacharater in the pattern matches all
--   characters, including those that indicate newline. Without it, a dot
--   does not match when the current position is at a newline. This option
--   is equivalent to Perl's /s option, and it can be changed within a
--   pattern by a (?s) option setting. A negative class such as [^a] always
--   matches newline characters, independent of the setting of this option.
dotall :: PCREOption

-- | <a>dupnames</a>
--   
--   If this bit is set, names used to identify capturing subpatterns need
--   not be unique. This can be helpful for certain types of pattern when
--   it is known that only one instance of the named subpattern can ever be
--   matched. There are more details of named subpatterns in the <i>man
--   pcreapi</i> documentation.
dupnames :: PCREOption

-- | <a>extended</a>
--   
--   If this bit is set, whitespace data characters in the pattern are
--   totally ignored except when escaped or inside a character class.
--   Whitespace does not include the VT character (code 11). In addition,
--   characters between an unescaped # outside a character class and the
--   next newline, inclusive, are also ignored. This is equivalent to
--   Perl's /x option, and it can be changed within a pattern by a (?x)
--   option setting.
--   
--   This option makes it possible to include comments inside complicated
--   patterns. Note, however, that this applies only to data characters.
--   Whitespace characters may never appear within special character
--   sequences in a pattern, for example within the sequence (?( which
--   introduces a conditional subpattern.
extended :: PCREOption

-- | <a>extra</a>
--   
--   This option was invented in order to turn on additional functionality
--   of PCRE that is incompatible with Perl, but it is currently of very
--   little use. When set, any backslash in a pattern that is followed by a
--   letter that has no special meaning causes an error, thus reserving
--   these combinations for future expansion. By default, as in Perl, a
--   backslash followed by a letter with no special meaning is treated as a
--   literal. (Perl can, however, be persuaded to give a warning for this.)
--   There are at present no other features controlled by this option. It
--   can also be set by a (?X) option setting within a pattern.
extra :: PCREOption

-- | <a>firstline</a>
--   
--   If this option is set, an unanchored pattern is required to match
--   before or at the first newline in the subject string, though the
--   matched text may continue over the newline.
firstline :: PCREOption

-- | <a>multiline</a>
--   
--   By default, PCRE treats the subject string as consisting of a single
--   line of characters (even if it actually contains newlines). The
--   <i>start of line</i> metacharacter (^) matches only at the start of
--   the string, while the <i>end of line</i> metacharacter ($) matches
--   only at the end of the string, or before a terminating newline (unless
--   <a>dollar_endonly</a> is set). This is the same as Perl.
--   
--   When <a>multiline</a> it is set, the <i>start of line</i> and <i>end
--   of line</i> constructs match immediately following or immediately
--   before internal newlines in the subject string, respectively, as well
--   as at the very start and end. This is equivalent to Perl's /m option,
--   and it can be changed within a pattern by a (?m) option setting. If
--   there are no newlines in a subject string, or no occur- rences of ^ or
--   $ in a pattern, setting PCRE_MULTILINE has no effect.
multiline :: PCREOption

-- | newline_cr', <a>newline_lf</a>, <a>newline_crlf</a>,
--   <tt>newline_anycrlf</tt>, <tt>newline_any</tt>
--   
--   These options override the default newline definition that was chosen
--   when PCRE was built. Setting the first or the second specifies that a
--   newline is indicated by a single character (CR or LF, respectively).
--   Setting <a>newline_crlf</a> specifies that a newline is indicated by
--   the two-character CRLF sequence. Setting <tt>newline_anycrlf</tt>
--   specifies that any of the three preceding sequences should be
--   recognized. Setting <tt>newline_any</tt> specifies that any Unicode
--   newline sequence should be recognized. The Unicode newline sequences
--   are the three just mentioned, plus the single characters VT (vertical
--   tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line
--   separator, U+2028), and PS (paragraph separator, U+2029). The last two
--   are recognized only in UTF-8 mode.
--   
--   The newline setting in the options word uses three bits that are
--   treated as a number, giving eight possibilities. Currently only six
--   are used (default plus the five values above). This means that if you
--   set more than one newline option, the combination may or may not be
--   sensible. For example, <a>newline_cr</a> with <a>newline_lf</a> is
--   equivalent to <a>newline_crlf</a>, but other combinations may yield
--   unused numbers and cause an error.
--   
--   The only time that a line break is specially recognized when compiling
--   a pattern is if <a>extended</a> is set, and an unescaped # outside a
--   character class is encountered. This indicates a comment that lasts
--   until after the next line break sequence. In other circumstances, line
--   break sequences are treated as literal data, except that in
--   <a>extended</a> mode, both CR and LF are treated as whitespace
--   characters and are therefore ignored. --
--   
--   The newline option that is set at compile time becomes the default
--   that is used for <tt>exec</tt> but it can be overridden.
--   
--   newline_any :: PCREOption newline_any = PCREOption newline_any_cint
--   
--   <tt>newline_anycrlf</tt>, see <tt>newline_any</tt> newline_anycrlf ::
--   PCREOption newline_anycrlf = PCREOption newline_anycrlf_cint
--   
--   <a>newline_cr</a>, see <tt>newline_any</tt>
newline_cr :: PCREOption

-- | <a>newline_crlf</a>, see <tt>newline_any</tt>
newline_crlf :: PCREOption

-- | <a>newline_lf</a>, see <tt>newline_any</tt>
newline_lf :: PCREOption

-- | <a>no_auto_capture</a>
--   
--   If this option is set, it disables the use of numbered capturing
--   parentheses in the pattern. Any opening paren- thesis that is not
--   followed by ? behaves as if it were followed by ?: but named
--   parentheses can still be used for capturing (and they acquire numbers
--   in the usual way). There is no equivalent of this option in Perl.
no_auto_capture :: PCREOption

-- | <a>ungreedy</a>
--   
--   This option inverts the <i>greediness</i> of the quantifiers so that
--   they are not greedy by default, but become greedy if followed by
--   <i>?</i>. It is not compatible with Perl. It can also be set by a (?U)
--   option setting within the pattern.
ungreedy :: PCREOption

-- | <a>utf8</a>
--   
--   This option causes PCRE to regard both the pattern and the subject as
--   strings of UTF-8 characters instead of single-byte character strings.
--   However, it is available only when PCRE is built to include UTF-8
--   support. If not, the use of this option provokes an error. Details of
--   how this option changes the behaviour of PCRE are given in the section
--   on UTF-8 support in the main pcre page.
utf8 :: PCREOption

-- | <a>no_utf8_check</a>
--   
--   When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string
--   is automatically checked. There is a discussion about the validity of
--   UTF-8 strings in the main pcre page. If an invalid UTF-8 sequence of
--   bytes is found, compile() returns an error. If you already know that
--   your pattern is valid, and you want to skip this check for performance
--   reasons, you can set the <a>no_utf8_check</a> option. When it is set,
--   the effect of passing an invalid UTF-8 string as a pattern is
--   undefined. It may cause your program to crash. Note that this option
--   can also be passed to <tt>exec</tt>, to suppress the UTF-8 validity
--   checking of subject strings.
no_utf8_check :: PCREOption
data PCREExecOption

-- | Combine a list of exec options into a single option, using bitwise
--   (.|.)
combineExecOptions :: [PCREExecOption] -> PCREExecOption

-- | <a>anchored</a>.
--   
--   The <a>anchored</a> option limits <tt>exec</tt> to matching at the
--   first matching position. If a pattern was compiled with
--   <a>anchored</a>, or turned out to be anchored by virtue of its
--   contents, it cannot be made unachored at matching time.
exec_anchored :: PCREExecOption

-- | <a>newline_cr</a>, <a>newline_lf</a>, <a>newline_crlf</a>,
--   <tt>newline_anycrlf</tt>, <tt>newline_any</tt>
--   
--   These options override the newline definition that was chosen or
--   defaulted when the pattern was compiled. For details, see the
--   description of <tt>compile</tt> above. Dur- ing matching, the newline
--   choice affects the behaviour of the dot, circumflex, and dollar
--   metacharacters. It may also alter the way the match position is
--   advanced after a match failure for an unanchored pattern.
--   
--   When <a>newline_crlf</a>, <tt>newline_anycrlf</tt>, or
--   <tt>newline_any</tt> is set, and a match attempt for an unanchored
--   pattern fails when the current position is at a CRLF sequence, and the
--   pattern contains no explicit matches for CR or LF characters, the
--   match position is advanced by two characters instead of one, in other
--   words, to after the CRLF.
--   
--   The above rule is a compromise that makes the most common cases work
--   as expected. For example, if the pattern is .+A (and the <a>dotall</a>
--   option is not set), it does not match the string <i>\\r\\nA</i>
--   because, after failing at the start, it skips both the CR and the LF
--   before retrying. However, the pattern <i>[\\r\\n]A</i> does match that
--   string, because it contains an explicit CR or LF reference, and so
--   advances only by one character after the first failure.
--   
--   An explicit match for CR of LF is either a literal appear- ance of one
--   of those characters, or one of the \r or \n escape sequences. Implicit
--   matches such as [^X] do not count, nor does \s (which includes CR and
--   LF in the char- acters that it matches).
--   
--   Notwithstanding the above, anomalous effects may still occur when CRLF
--   is a valid newline sequence and explicit \r or \n escapes appear in
--   the pattern.
--   
--   exec_newline_any :: PCREExecOption exec_newline_any = PCREExecOption
--   exec_newline_any_cint
--   
--   <tt>exec_newline_anycrlf</tt>, see <tt>exec_newline_any</tt>
--   exec_newline_anycrlf :: PCREExecOption exec_newline_anycrlf =
--   PCREExecOption exec_newline_anycrlf_cint
--   
--   <a>exec_newline_cr</a>, see <tt>exec_newline_any</tt>
exec_newline_cr :: PCREExecOption

-- | <a>exec_newline_crlf</a>, see <tt>exec_newline_any</tt>
exec_newline_crlf :: PCREExecOption

-- | <a>exec_newline_lf</a>, see <tt>exec_newline_any</tt>
exec_newline_lf :: PCREExecOption

-- | <tt>PCRE_NOTBOL</tt>
--   
--   This option specifies that first character of the subject string is
--   not the beginning of a line, so the circumflex metacharacter should
--   not match before it. Setting this without <a>multiline</a> (at compile
--   time) causes circumflex never to match. This option affects only the
--   behaviour of the circumflex metacharacter. It does not affect \A.
exec_notbol :: PCREExecOption

-- | <tt>noteol</tt>
--   
--   This option specifies that the end of the subject string is not the
--   end of a line, so the dollar metacharacter should not match it nor
--   (except in multiline mode) a newline immediately before it. Setting
--   this without <a>multiline</a> (at compile time) causes dollar never to
--   match. This option affects only the behaviour of the dollar
--   metacharacter. It does not affect \Z or \z.
exec_noteol :: PCREExecOption

-- | PCRE_NOTEMPTY
--   
--   An empty string is not considered to be a valid match if this option
--   is set. If there are alternatives in the pattern, they are tried. If
--   all the alternatives match the empty string, the entire match fails.
--   For example, if the pattern
--   
--   <pre>
--   a?b?
--   </pre>
--   
--   is applied to a string not beginning with <i>a</i> or <i>b</i>, it
--   matches the empty string at the start of the subject. With
--   <tt>notempty</tt> set, this match is not valid, so 'PCRE searches
--   further into the string for occurrences of <i>a</i> or <i>b</i>.
--   
--   Perl has no direct equivalent of <tt>notempty</tt>, but it does make a
--   special case of a pattern match of the empty string within its split()
--   function, and when using the /g modifier. It is possible to emulate
--   Perl's behaviour after matching a null string by first trying the
--   match again at the same offset with PCRE_NOTEMPTY and PCRE_ANCHORED,
--   and then if that fails by advancing the starting offset (see below)
--   and trying an ordinary match again. There is some code that
--   demonstrates how to do this in the pcredemo.c sample program.
exec_notempty :: PCREExecOption

-- | <a>no_utf8_check</a>
--   
--   When <a>utf8</a> is set at compile time, the validity of the subject
--   as a UTF-8 string is automatically checked when exec() is subsequently
--   called. The value of startoffset is also checked to ensure that it
--   points to the start of a UTF-8 character. There is a discussion about
--   the validity of UTF-8 strings in the section on UTF-8 support in the
--   main pcre page. If an invalid UTF-8 sequence of bytes is found, exec()
--   returns the error <a>error_badutf8</a>. If startoffset contains an
--   invalid value, <a>error_badutf8_offset</a> is returned.
--   
--   If you already know that your subject is valid, and you want to skip
--   these checks for performance reasons, you can set the
--   <a>no_utf8_check</a> option when calling <tt>exec</tt>. You might want
--   to do this for the second and subsequent calls to exec() if you are
--   making repeated calls to find all the matches in a single subject
--   string. However, you should be sure that the value of startoffset
--   points to the start of a UTF-8 character. When <a>no_utf8_check</a> is
--   set, the effect of passing an invalid UTF-8 string as a subject, or a
--   value of startoff- set that does not point to the start of a UTF-8
--   character, is undefined. Your program may crash.
exec_no_utf8_check :: PCREExecOption

-- | <tt>partial</tt>
--   
--   This option turns on the partial matching feature. If the subject
--   string fails to match the pattern, but at some point during the
--   matching process the end of the subject was reached (that is, the
--   subject partially matches the pattern and the failure to match
--   occurred only because there were not enough subject characters),
--   <tt>exec</tt> returns <a>error_partial</a> instead of
--   <a>error_nomatch</a>. When <tt>partial</tt> is used, there are
--   restrictions on what may appear in the pattern. These are discussed in
--   the pcrepartial documentation.
exec_partial :: PCREExecOption

-- | A type for PCRE Errors: exec-time error codes.
type PCREError = CInt
error_nomatch :: PCREError
error_null :: PCREError
error_badoption :: PCREError
error_badmagic :: PCREError
error_unknown_node :: PCREError
error_nomemory :: PCREError
error_nosubstring :: PCREError
error_matchlimit :: PCREError
error_callout :: PCREError
error_badutf8 :: PCREError
error_badutf8_offset :: PCREError
error_partial :: PCREError
error_badpartial :: PCREError
error_internal :: PCREError
error_badcount :: PCREError
error_dfa_uitem :: PCREError
error_dfa_ucond :: PCREError
error_dfa_umlimit :: PCREError
error_dfa_wssize :: PCREError
error_dfa_recurse :: PCREError
error_recursionlimit :: PCREError

-- | PCRE Info requests -- provides information about the compiled pattern.
type PCREInfo = CInt
info_options :: PCREInfo
info_size :: PCREInfo
info_capturecount :: PCREInfo
info_backrefmax :: PCREInfo
info_firstbyte :: PCREInfo
info_firstchar :: PCREInfo
info_firsttable :: PCREInfo
info_lastliteral :: PCREInfo
info_nameentrysize :: PCREInfo
info_namecount :: PCREInfo
info_nametable :: PCREInfo

-- | Request types for config()
info_studysize :: PCREInfo
info_default_tables :: PCREInfo
type PCREConfig = CInt
config_utf8 :: PCREConfig
config_newline :: PCREConfig
config_link_size :: PCREConfig
config_posix_malloc_threshold :: PCREConfig
config_match_limit :: PCREConfig
config_stackrecurse :: PCREConfig
config_unicode_properties :: PCREConfig
config_match_limit_recursion :: PCREConfig

-- | PCREExtraFlags. bit flags for extra structure.
type PCREExtraFlags = CInt
extra_study_data :: PCREExtraFlags
extra_match_limit :: PCREExtraFlags
extra_callout_data :: PCREExtraFlags
extra_tables :: PCREExtraFlags
extra_match_limit_recursion :: PCREExtraFlags

-- | Get sizeof CInt from hsc2hs
size_of_cint :: Int
instance Eq Regex
instance Ord Regex
instance Show Regex
instance Eq PCREOption
instance Ord PCREOption
instance Show PCREOption
instance Read PCREOption
instance Eq PCREExecOption
instance Ord PCREExecOption
instance Show PCREExecOption
instance Read PCREExecOption


module Text.Regex.PCRE.Light

-- | An abstract pointer to a compiled PCRE Regex structure The structure
--   allocated by the PCRE library will be deallocated automatically by the
--   Haskell storage manager.
data Regex

-- | <a>compile</a>
--   
--   Compile a perl-compatible regular expression stored in a strict
--   bytestring.
--   
--   An example
--   
--   <pre>
--   let r = compile (pack "^(b+|a){1,2}?bc") []
--   </pre>
--   
--   Or using GHC's -XOverloadedStrings flag, and importing
--   Data.ByteString.Char8, we can avoid the pack:
--   
--   <pre>
--   let r = compile "^(b+|a){1,2}?bc" []
--   </pre>
--   
--   If the regular expression is invalid, an exception is thrown. If this
--   is unsuitable, <a>compileM</a> is availlable, which returns failure in
--   a monad.
--   
--   To do case insentive matching,
--   
--   <pre>
--   compile "^(b+|a){1,2}?bc" [caseless]
--   </pre>
--   
--   Other flags are documented below.
--   
--   The resulting abstract regular expression can be passed to
--   <a>match</a> for matching against a subject string.
--   
--   The arguments are:
--   
--   <ul>
--   <li><tt>pat</tt>: A ByteString containing the regular expression to be
--   compiled.</li>
--   <li><tt>flags</tt>, optional bit flags. If <a>Nothing</a> is provided,
--   defaults are used.</li>
--   </ul>
--   
--   Valid compile-time flags are:
--   
--   <ul>
--   <li><a>anchored</a> - Force pattern anchoring</li>
--   <li><a>auto_callout</a> - Compile automatic callouts</li>
--   <li><tt>bsr_anycrlf</tt> - \R matches only CR, LF, or CRLF</li>
--   <li><tt>bsr_unicode</tt> - \R matches all Unicode line endings</li>
--   <li><a>caseless</a> - Do caseless matching</li>
--   <li><a>dollar_endonly</a> - <a>$</a> not to match newline at end</li>
--   <li><a>dotall</a> - matches anything including NL</li>
--   <li><a>dupnames</a> - Allow duplicate names for subpatterns</li>
--   <li><a>extended</a> - Ignore whitespace and # comments</li>
--   <li><a>extra</a> - PCRE extra features (not much use currently)</li>
--   <li><a>firstline</a> - Force matching to be before newline</li>
--   <li><a>multiline</a> - <a>^</a> and <a>$</a> match newlines within
--   data</li>
--   <li><tt>newline_any</tt> - Recognize any Unicode newline sequence</li>
--   <li><tt>newline_anycrlf</tt> - Recognize CR, LF, and CRLF as newline
--   sequences</li>
--   <li><a>newline_cr</a> - Set CR as the newline sequence</li>
--   <li><a>newline_crlf</a> - Set CRLF as the newline sequence</li>
--   <li><a>newline_lf</a> - Set LF as the newline sequence</li>
--   <li><a>no_auto_capture</a> - Disable numbered capturing parentheses
--   (named ones available)</li>
--   <li><a>ungreedy</a> - Invert greediness of quantifiers</li>
--   <li><a>utf8</a> - Run in UTF-8 mode</li>
--   <li><a>no_utf8_check</a> - Do not check the pattern for UTF-8
--   validity</li>
--   </ul>
--   
--   The regex is allocated via malloc on the C side, and will be
--   deallocated by the runtime when the Haskell value representing it goes
--   out of scope.
--   
--   See 'man pcreapi for more details.
--   
--   Caveats: patterns with embedded nulls, such as <a>0*</a> seem to be
--   mishandled, as this won't currently match the subject <a>000</a>.
compile :: ByteString -> [PCREOption] -> Regex

-- | <a>compileM</a> A safe version of <a>compile</a> with failure wrapped
--   in an Either.
--   
--   Examples,
--   
--   <pre>
--   &gt; compileM ".*" [] :: Either String Regex
--   Right (Regex 0x000000004bb5b980 ".*")
--   </pre>
--   
--   <pre>
--   &gt; compileM "*" [] :: Either String Regex
--   Left "nothing to repeat"
--   </pre>
compileM :: ByteString -> [PCREOption] -> Either String Regex

-- | <a>match</a>
--   
--   Matches a compiled regular expression against a given subject string,
--   using a matching algorithm that is similar to Perl's. If the subject
--   string doesn't match the regular expression, <a>Nothing</a> is
--   returned, otherwise the portion of the string that matched is
--   returned, along with any captured subpatterns.
--   
--   The arguments are:
--   
--   <ul>
--   <li><tt>regex</tt>, a PCRE regular expression value produced by
--   compile</li>
--   <li><tt>subject</tt>, the subject string to match against</li>
--   <li><tt>options</tt>, an optional set of exec-time flags to exec.</li>
--   </ul>
--   
--   Available runtime options are:
--   
--   <ul>
--   <li><a>exec_anchored</a> - Match only at the first position</li>
--   <li><tt>exec_newline_any</tt> - Recognize any Unicode newline
--   sequence</li>
--   <li><tt>exec_newline_anycrlf</tt> - Recognize CR, LF, and CRLF as
--   newline sequences</li>
--   <li><a>exec_newline_cr</a> - Set CR as the newline sequence</li>
--   <li><a>exec_newline_crlf</a> - Set CRLF as the newline sequence</li>
--   <li><a>exec_newline_lf</a> - Set LF as the newline sequence</li>
--   <li><a>exec_notbol</a> - Subject is not the beginning of a line</li>
--   <li><a>exec_noteol</a> - Subject is not the end of a line</li>
--   <li><a>exec_notempty</a> - An empty string is not a valid match</li>
--   <li><a>exec_no_utf8_check</a> - Do not check the subject for
--   UTF-8</li>
--   <li><a>exec_partial</a> - Return PCRE_ERROR_PARTIAL for a partial
--   match</li>
--   </ul>
--   
--   The result value, and any captured subpatterns, are returned. If the
--   regex is invalid, or the subject string is empty, Nothing is returned.
match :: Regex -> ByteString -> [PCREExecOption] -> Maybe [ByteString]
captureCount :: Regex -> Int

-- | A type for PCRE compile-time options. These are newtyped CInts, which
--   can be bitwise-or'd together, using '(Data.Bits..|.)'
data PCREOption

-- | <a>anchored</a>
--   
--   If this bit is set, the pattern is forced to be <i>anchored</i>, that
--   is, it is constrained to match only at the first matching point in the
--   string that is being searched (the <i>subject string</i>). This effect
--   can also be achieved by appropriate constructs in the pattern itself,
--   which is the only way to do it in Perl.
anchored :: PCREOption

-- | <a>auto_callout</a>
--   
--   If this bit is set, <a>compile</a> automatically inserts callout
--   items, all with number 255, before each pattern item. For discussion
--   of the callout facility, see the man pcrecallout documentation
auto_callout :: PCREOption

-- | <tt>bsr_anycrlf</tt> and <tt>bsr_unicode</tt>
--   
--   These options (which are mutually exclusive) control what the \R
--   escape sequence matches. The choice is either to match only CR, LF, or
--   CRLF, or to match any Unicode new- line sequence. The default is
--   specified when PCRE is built. It can be overridden from within the
--   pattern, or by setting an option when a compiled pattern is matched.
--   
--   bsr_anycrlf :: PCREOption bsr_anycrlf = PCREOption bsr_anycrlf_cint
--   
--   <tt>bsr_unicode</tt>. See <tt>bse_anycrlf</tt>
--   
--   bsr_unicode :: PCREOption bsr_unicode = PCREOption bsr_unicode_cint
--   
--   <a>caseless</a>
--   
--   If this bit is set, letters in the pattern match both upper and lower
--   case letters. It is equivalent to Perl's /i option, and it can be
--   changed within a pattern by a (?i) option setting. In UTF-8 mode, PCRE
--   always understands the concept of case for characters whose values are
--   less than 128, so caseless matching is always possible. For characters
--   with higher values, the concept of case is supported if PCRE is
--   compiled with Unicode property sup- port, but not otherwise. If you
--   want to use caseless matching for characters 128 and above, you must
--   ensure that PCRE is compiled with Unicode property support as well as
--   with UTF-8 support.
caseless :: PCREOption

-- | <a>dollar_endonly</a>
--   
--   If this bit is set, a dollar metacharacter in the pattern matches only
--   at the end of the subject string. Without this option, a dollar also
--   matches immediately before a newline at the end of the string (but not
--   before any other newlines). The <a>dollar_endonly</a> option is
--   ignored if <a>multiline</a> is set. There is no equivalent to this
--   option in Perl, and no way to set it within a pattern.
dollar_endonly :: PCREOption

-- | <a>dotall</a>
--   
--   If this bit is set, a dot metacharater in the pattern matches all
--   characters, including those that indicate newline. Without it, a dot
--   does not match when the current position is at a newline. This option
--   is equivalent to Perl's /s option, and it can be changed within a
--   pattern by a (?s) option setting. A negative class such as [^a] always
--   matches newline characters, independent of the setting of this option.
dotall :: PCREOption

-- | <a>dupnames</a>
--   
--   If this bit is set, names used to identify capturing subpatterns need
--   not be unique. This can be helpful for certain types of pattern when
--   it is known that only one instance of the named subpattern can ever be
--   matched. There are more details of named subpatterns in the <i>man
--   pcreapi</i> documentation.
dupnames :: PCREOption

-- | <a>extended</a>
--   
--   If this bit is set, whitespace data characters in the pattern are
--   totally ignored except when escaped or inside a character class.
--   Whitespace does not include the VT character (code 11). In addition,
--   characters between an unescaped # outside a character class and the
--   next newline, inclusive, are also ignored. This is equivalent to
--   Perl's /x option, and it can be changed within a pattern by a (?x)
--   option setting.
--   
--   This option makes it possible to include comments inside complicated
--   patterns. Note, however, that this applies only to data characters.
--   Whitespace characters may never appear within special character
--   sequences in a pattern, for example within the sequence (?( which
--   introduces a conditional subpattern.
extended :: PCREOption

-- | <a>extra</a>
--   
--   This option was invented in order to turn on additional functionality
--   of PCRE that is incompatible with Perl, but it is currently of very
--   little use. When set, any backslash in a pattern that is followed by a
--   letter that has no special meaning causes an error, thus reserving
--   these combinations for future expansion. By default, as in Perl, a
--   backslash followed by a letter with no special meaning is treated as a
--   literal. (Perl can, however, be persuaded to give a warning for this.)
--   There are at present no other features controlled by this option. It
--   can also be set by a (?X) option setting within a pattern.
extra :: PCREOption

-- | <a>firstline</a>
--   
--   If this option is set, an unanchored pattern is required to match
--   before or at the first newline in the subject string, though the
--   matched text may continue over the newline.
firstline :: PCREOption

-- | <a>multiline</a>
--   
--   By default, PCRE treats the subject string as consisting of a single
--   line of characters (even if it actually contains newlines). The
--   <i>start of line</i> metacharacter (^) matches only at the start of
--   the string, while the <i>end of line</i> metacharacter ($) matches
--   only at the end of the string, or before a terminating newline (unless
--   <a>dollar_endonly</a> is set). This is the same as Perl.
--   
--   When <a>multiline</a> it is set, the <i>start of line</i> and <i>end
--   of line</i> constructs match immediately following or immediately
--   before internal newlines in the subject string, respectively, as well
--   as at the very start and end. This is equivalent to Perl's /m option,
--   and it can be changed within a pattern by a (?m) option setting. If
--   there are no newlines in a subject string, or no occur- rences of ^ or
--   $ in a pattern, setting PCRE_MULTILINE has no effect.
multiline :: PCREOption

-- | newline_cr', <a>newline_lf</a>, <a>newline_crlf</a>,
--   <tt>newline_anycrlf</tt>, <tt>newline_any</tt>
--   
--   These options override the default newline definition that was chosen
--   when PCRE was built. Setting the first or the second specifies that a
--   newline is indicated by a single character (CR or LF, respectively).
--   Setting <a>newline_crlf</a> specifies that a newline is indicated by
--   the two-character CRLF sequence. Setting <tt>newline_anycrlf</tt>
--   specifies that any of the three preceding sequences should be
--   recognized. Setting <tt>newline_any</tt> specifies that any Unicode
--   newline sequence should be recognized. The Unicode newline sequences
--   are the three just mentioned, plus the single characters VT (vertical
--   tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line
--   separator, U+2028), and PS (paragraph separator, U+2029). The last two
--   are recognized only in UTF-8 mode.
--   
--   The newline setting in the options word uses three bits that are
--   treated as a number, giving eight possibilities. Currently only six
--   are used (default plus the five values above). This means that if you
--   set more than one newline option, the combination may or may not be
--   sensible. For example, <a>newline_cr</a> with <a>newline_lf</a> is
--   equivalent to <a>newline_crlf</a>, but other combinations may yield
--   unused numbers and cause an error.
--   
--   The only time that a line break is specially recognized when compiling
--   a pattern is if <a>extended</a> is set, and an unescaped # outside a
--   character class is encountered. This indicates a comment that lasts
--   until after the next line break sequence. In other circumstances, line
--   break sequences are treated as literal data, except that in
--   <a>extended</a> mode, both CR and LF are treated as whitespace
--   characters and are therefore ignored. --
--   
--   The newline option that is set at compile time becomes the default
--   that is used for <tt>exec</tt> but it can be overridden.
--   
--   newline_any :: PCREOption newline_any = PCREOption newline_any_cint
--   
--   <tt>newline_anycrlf</tt>, see <tt>newline_any</tt> newline_anycrlf ::
--   PCREOption newline_anycrlf = PCREOption newline_anycrlf_cint
--   
--   <a>newline_cr</a>, see <tt>newline_any</tt>
newline_cr :: PCREOption

-- | <a>newline_crlf</a>, see <tt>newline_any</tt>
newline_crlf :: PCREOption

-- | <a>newline_lf</a>, see <tt>newline_any</tt>
newline_lf :: PCREOption

-- | <a>no_auto_capture</a>
--   
--   If this option is set, it disables the use of numbered capturing
--   parentheses in the pattern. Any opening paren- thesis that is not
--   followed by ? behaves as if it were followed by ?: but named
--   parentheses can still be used for capturing (and they acquire numbers
--   in the usual way). There is no equivalent of this option in Perl.
no_auto_capture :: PCREOption

-- | <a>ungreedy</a>
--   
--   This option inverts the <i>greediness</i> of the quantifiers so that
--   they are not greedy by default, but become greedy if followed by
--   <i>?</i>. It is not compatible with Perl. It can also be set by a (?U)
--   option setting within the pattern.
ungreedy :: PCREOption

-- | <a>utf8</a>
--   
--   This option causes PCRE to regard both the pattern and the subject as
--   strings of UTF-8 characters instead of single-byte character strings.
--   However, it is available only when PCRE is built to include UTF-8
--   support. If not, the use of this option provokes an error. Details of
--   how this option changes the behaviour of PCRE are given in the section
--   on UTF-8 support in the main pcre page.
utf8 :: PCREOption

-- | <a>no_utf8_check</a>
--   
--   When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string
--   is automatically checked. There is a discussion about the validity of
--   UTF-8 strings in the main pcre page. If an invalid UTF-8 sequence of
--   bytes is found, compile() returns an error. If you already know that
--   your pattern is valid, and you want to skip this check for performance
--   reasons, you can set the <a>no_utf8_check</a> option. When it is set,
--   the effect of passing an invalid UTF-8 string as a pattern is
--   undefined. It may cause your program to crash. Note that this option
--   can also be passed to <tt>exec</tt>, to suppress the UTF-8 validity
--   checking of subject strings.
no_utf8_check :: PCREOption
data PCREExecOption

-- | <a>anchored</a>.
--   
--   The <a>anchored</a> option limits <tt>exec</tt> to matching at the
--   first matching position. If a pattern was compiled with
--   <a>anchored</a>, or turned out to be anchored by virtue of its
--   contents, it cannot be made unachored at matching time.
exec_anchored :: PCREExecOption

-- | <a>newline_cr</a>, <a>newline_lf</a>, <a>newline_crlf</a>,
--   <tt>newline_anycrlf</tt>, <tt>newline_any</tt>
--   
--   These options override the newline definition that was chosen or
--   defaulted when the pattern was compiled. For details, see the
--   description of <tt>compile</tt> above. Dur- ing matching, the newline
--   choice affects the behaviour of the dot, circumflex, and dollar
--   metacharacters. It may also alter the way the match position is
--   advanced after a match failure for an unanchored pattern.
--   
--   When <a>newline_crlf</a>, <tt>newline_anycrlf</tt>, or
--   <tt>newline_any</tt> is set, and a match attempt for an unanchored
--   pattern fails when the current position is at a CRLF sequence, and the
--   pattern contains no explicit matches for CR or LF characters, the
--   match position is advanced by two characters instead of one, in other
--   words, to after the CRLF.
--   
--   The above rule is a compromise that makes the most common cases work
--   as expected. For example, if the pattern is .+A (and the <a>dotall</a>
--   option is not set), it does not match the string <i>\\r\\nA</i>
--   because, after failing at the start, it skips both the CR and the LF
--   before retrying. However, the pattern <i>[\\r\\n]A</i> does match that
--   string, because it contains an explicit CR or LF reference, and so
--   advances only by one character after the first failure.
--   
--   An explicit match for CR of LF is either a literal appear- ance of one
--   of those characters, or one of the \r or \n escape sequences. Implicit
--   matches such as [^X] do not count, nor does \s (which includes CR and
--   LF in the char- acters that it matches).
--   
--   Notwithstanding the above, anomalous effects may still occur when CRLF
--   is a valid newline sequence and explicit \r or \n escapes appear in
--   the pattern.
--   
--   exec_newline_any :: PCREExecOption exec_newline_any = PCREExecOption
--   exec_newline_any_cint
--   
--   <tt>exec_newline_anycrlf</tt>, see <tt>exec_newline_any</tt>
--   exec_newline_anycrlf :: PCREExecOption exec_newline_anycrlf =
--   PCREExecOption exec_newline_anycrlf_cint
--   
--   <a>exec_newline_cr</a>, see <tt>exec_newline_any</tt>
exec_newline_cr :: PCREExecOption

-- | <a>exec_newline_crlf</a>, see <tt>exec_newline_any</tt>
exec_newline_crlf :: PCREExecOption

-- | <a>exec_newline_lf</a>, see <tt>exec_newline_any</tt>
exec_newline_lf :: PCREExecOption

-- | <tt>PCRE_NOTBOL</tt>
--   
--   This option specifies that first character of the subject string is
--   not the beginning of a line, so the circumflex metacharacter should
--   not match before it. Setting this without <a>multiline</a> (at compile
--   time) causes circumflex never to match. This option affects only the
--   behaviour of the circumflex metacharacter. It does not affect \A.
exec_notbol :: PCREExecOption

-- | <tt>noteol</tt>
--   
--   This option specifies that the end of the subject string is not the
--   end of a line, so the dollar metacharacter should not match it nor
--   (except in multiline mode) a newline immediately before it. Setting
--   this without <a>multiline</a> (at compile time) causes dollar never to
--   match. This option affects only the behaviour of the dollar
--   metacharacter. It does not affect \Z or \z.
exec_noteol :: PCREExecOption

-- | PCRE_NOTEMPTY
--   
--   An empty string is not considered to be a valid match if this option
--   is set. If there are alternatives in the pattern, they are tried. If
--   all the alternatives match the empty string, the entire match fails.
--   For example, if the pattern
--   
--   <pre>
--   a?b?
--   </pre>
--   
--   is applied to a string not beginning with <i>a</i> or <i>b</i>, it
--   matches the empty string at the start of the subject. With
--   <tt>notempty</tt> set, this match is not valid, so 'PCRE searches
--   further into the string for occurrences of <i>a</i> or <i>b</i>.
--   
--   Perl has no direct equivalent of <tt>notempty</tt>, but it does make a
--   special case of a pattern match of the empty string within its split()
--   function, and when using the /g modifier. It is possible to emulate
--   Perl's behaviour after matching a null string by first trying the
--   match again at the same offset with PCRE_NOTEMPTY and PCRE_ANCHORED,
--   and then if that fails by advancing the starting offset (see below)
--   and trying an ordinary match again. There is some code that
--   demonstrates how to do this in the pcredemo.c sample program.
exec_notempty :: PCREExecOption

-- | <a>no_utf8_check</a>
--   
--   When <a>utf8</a> is set at compile time, the validity of the subject
--   as a UTF-8 string is automatically checked when exec() is subsequently
--   called. The value of startoffset is also checked to ensure that it
--   points to the start of a UTF-8 character. There is a discussion about
--   the validity of UTF-8 strings in the section on UTF-8 support in the
--   main pcre page. If an invalid UTF-8 sequence of bytes is found, exec()
--   returns the error <a>error_badutf8</a>. If startoffset contains an
--   invalid value, <a>error_badutf8_offset</a> is returned.
--   
--   If you already know that your subject is valid, and you want to skip
--   these checks for performance reasons, you can set the
--   <a>no_utf8_check</a> option when calling <tt>exec</tt>. You might want
--   to do this for the second and subsequent calls to exec() if you are
--   making repeated calls to find all the matches in a single subject
--   string. However, you should be sure that the value of startoffset
--   points to the start of a UTF-8 character. When <a>no_utf8_check</a> is
--   set, the effect of passing an invalid UTF-8 string as a subject, or a
--   value of startoff- set that does not point to the start of a UTF-8
--   character, is undefined. Your program may crash.
exec_no_utf8_check :: PCREExecOption

-- | <tt>partial</tt>
--   
--   This option turns on the partial matching feature. If the subject
--   string fails to match the pattern, but at some point during the
--   matching process the end of the subject was reached (that is, the
--   subject partially matches the pattern and the failure to match
--   occurred only because there were not enough subject characters),
--   <tt>exec</tt> returns <a>error_partial</a> instead of
--   <a>error_nomatch</a>. When <tt>partial</tt> is used, there are
--   restrictions on what may appear in the pattern. These are discussed in
--   the pcrepartial documentation.
exec_partial :: PCREExecOption


module Text.Regex.PCRE.Light.Char8

-- | An abstract pointer to a compiled PCRE Regex structure The structure
--   allocated by the PCRE library will be deallocated automatically by the
--   Haskell storage manager.
data Regex

-- | <a>compile</a>
--   
--   Compile a perl-compatible regular expression, in a strict bytestring.
--   The arguments are:
--   
--   <ul>
--   <li><tt>pat</tt>: A ByteString, which may or may not be
--   zero-terminated, containing the regular expression to be
--   compiled.</li>
--   <li><tt>flags</tt>, optional bit flags. If <a>Nothing</a> is provided,
--   defaults are used.</li>
--   </ul>
--   
--   Valid compile-time flags are:
--   
--   <ul>
--   <li><a>anchored</a> - Force pattern anchoring</li>
--   <li><a>auto_callout</a> - Compile automatic callouts</li>
--   <li><tt>bsr_anycrlf</tt> - \R matches only CR, LF, or CRLF</li>
--   <li><tt>bsr_unicode</tt> - \R matches all Unicode line endings</li>
--   <li><a>caseless</a> - Do caseless matching</li>
--   <li><a>dollar_endonly</a> - <a>$</a> not to match newline at end</li>
--   <li><a>dotall</a> - matches anything including NL</li>
--   <li><a>dupnames</a> - Allow duplicate names for subpatterns</li>
--   <li><a>extended</a> - Ignore whitespace and # comments</li>
--   <li><a>extra</a> - PCRE extra features (not much use currently)</li>
--   <li><a>firstline</a> - Force matching to be before newline</li>
--   <li><a>multiline</a> - <a>^</a> and <a>$</a> match newlines within
--   data</li>
--   <li><tt>newline_any</tt> - Recognize any Unicode newline sequence</li>
--   <li><tt>newline_anycrlf</tt> - Recognize CR, LF, and CRLF as newline
--   sequences</li>
--   <li><a>newline_cr</a> - Set CR as the newline sequence</li>
--   <li><a>newline_crlf</a> - Set CRLF as the newline sequence</li>
--   <li><a>newline_lf</a> - Set LF as the newline sequence</li>
--   <li><a>no_auto_capture</a> - Disable numbered capturing parentheses
--   (named ones available)</li>
--   <li><a>ungreedy</a> - Invert greediness of quantifiers</li>
--   <li><a>utf8</a> - Run in UTF-8 mode</li>
--   <li><a>no_utf8_check</a> - Do not check the pattern for UTF-8
--   validity</li>
--   </ul>
--   
--   If compilation of the pattern fails, the <a>Left</a> constructor is
--   returned with the error string. Otherwise an abstract type
--   representing the compiled regular expression is returned. The regex is
--   allocated via malloc on the C side, and will be deallocated by the
--   runtime when the Haskell value representing it goes out of scope.
--   
--   As regexes are often defined statically, GHC will compile them to
--   null-terminated, strict C strings, enabling compilation of the pattern
--   without copying. This may be useful for very large patterns.
--   
--   See man pcreapi for more details.
compile :: String -> [PCREOption] -> Regex

-- | <a>compileM</a> A safe version of <a>compile</a> with failure lifted
--   into an Either
compileM :: String -> [PCREOption] -> Either String Regex

-- | <a>match</a>
--   
--   Matches a compiled regular expression against a given subject string,
--   using a matching algorithm that is similar to Perl's. If the subject
--   string doesn't match the regular expression, <a>Nothing</a> is
--   returned, otherwise the portion of the string that matched is
--   returned, along with any captured subpatterns.
--   
--   The arguments are:
--   
--   <ul>
--   <li><tt>regex</tt>, a PCRE regular expression value produced by
--   compile</li>
--   <li><tt>subject</tt>, the subject string to match against</li>
--   <li><tt>options</tt>, an optional set of exec-time flags to exec.</li>
--   </ul>
--   
--   Available runtime options are:
--   
--   <ul>
--   <li><a>anchored</a> - Match only at the first position</li>
--   <li><tt>bsr_anycrlf</tt> - '\\R' matches only CR, LF, or CRLF</li>
--   <li><tt>bsr_unicode</tt> - '\\R' matches all Unicode line endings</li>
--   <li><tt>newline_any</tt> - Recognize any Unicode newline sequence</li>
--   <li><tt>newline_anycrlf</tt> - Recognize CR, LF, and CRLF as newline
--   sequences</li>
--   <li><a>newline_cr</a> - Set CR as the newline sequence</li>
--   <li><a>newline_crlf</a> - Set CRLF as the newline sequence</li>
--   <li><a>newline_lf</a> - Set LF as the newline sequence</li>
--   <li><tt>notbol</tt> - Subject is not the beginning of a line</li>
--   <li><tt>noteol</tt> - Subject is not the end of a line</li>
--   <li><tt>notempty</tt> - An empty string is not a valid match</li>
--   <li><a>no_utf8_check</a> - Do not check the subject for UTF-8</li>
--   <li><tt>partial</tt> - Return PCRE_ERROR_PARTIAL for a partial
--   match</li>
--   </ul>
--   
--   The result value, and any captured subpatterns, are returned. If the
--   regex is invalid, or the subject string is empty, Nothing is returned.
match :: Regex -> String -> [PCREExecOption] -> Maybe [String]

-- | A type for PCRE compile-time options. These are newtyped CInts, which
--   can be bitwise-or'd together, using '(Data.Bits..|.)'
data PCREOption

-- | <a>anchored</a>
--   
--   If this bit is set, the pattern is forced to be <i>anchored</i>, that
--   is, it is constrained to match only at the first matching point in the
--   string that is being searched (the <i>subject string</i>). This effect
--   can also be achieved by appropriate constructs in the pattern itself,
--   which is the only way to do it in Perl.
anchored :: PCREOption

-- | <a>auto_callout</a>
--   
--   If this bit is set, <a>compile</a> automatically inserts callout
--   items, all with number 255, before each pattern item. For discussion
--   of the callout facility, see the man pcrecallout documentation
auto_callout :: PCREOption

-- | <tt>bsr_anycrlf</tt> and <tt>bsr_unicode</tt>
--   
--   These options (which are mutually exclusive) control what the \R
--   escape sequence matches. The choice is either to match only CR, LF, or
--   CRLF, or to match any Unicode new- line sequence. The default is
--   specified when PCRE is built. It can be overridden from within the
--   pattern, or by setting an option when a compiled pattern is matched.
--   
--   bsr_anycrlf :: PCREOption bsr_anycrlf = PCREOption bsr_anycrlf_cint
--   
--   <tt>bsr_unicode</tt>. See <tt>bse_anycrlf</tt>
--   
--   bsr_unicode :: PCREOption bsr_unicode = PCREOption bsr_unicode_cint
--   
--   <a>caseless</a>
--   
--   If this bit is set, letters in the pattern match both upper and lower
--   case letters. It is equivalent to Perl's /i option, and it can be
--   changed within a pattern by a (?i) option setting. In UTF-8 mode, PCRE
--   always understands the concept of case for characters whose values are
--   less than 128, so caseless matching is always possible. For characters
--   with higher values, the concept of case is supported if PCRE is
--   compiled with Unicode property sup- port, but not otherwise. If you
--   want to use caseless matching for characters 128 and above, you must
--   ensure that PCRE is compiled with Unicode property support as well as
--   with UTF-8 support.
caseless :: PCREOption

-- | <a>dollar_endonly</a>
--   
--   If this bit is set, a dollar metacharacter in the pattern matches only
--   at the end of the subject string. Without this option, a dollar also
--   matches immediately before a newline at the end of the string (but not
--   before any other newlines). The <a>dollar_endonly</a> option is
--   ignored if <a>multiline</a> is set. There is no equivalent to this
--   option in Perl, and no way to set it within a pattern.
dollar_endonly :: PCREOption

-- | <a>dotall</a>
--   
--   If this bit is set, a dot metacharater in the pattern matches all
--   characters, including those that indicate newline. Without it, a dot
--   does not match when the current position is at a newline. This option
--   is equivalent to Perl's /s option, and it can be changed within a
--   pattern by a (?s) option setting. A negative class such as [^a] always
--   matches newline characters, independent of the setting of this option.
dotall :: PCREOption

-- | <a>dupnames</a>
--   
--   If this bit is set, names used to identify capturing subpatterns need
--   not be unique. This can be helpful for certain types of pattern when
--   it is known that only one instance of the named subpattern can ever be
--   matched. There are more details of named subpatterns in the <i>man
--   pcreapi</i> documentation.
dupnames :: PCREOption

-- | <a>extended</a>
--   
--   If this bit is set, whitespace data characters in the pattern are
--   totally ignored except when escaped or inside a character class.
--   Whitespace does not include the VT character (code 11). In addition,
--   characters between an unescaped # outside a character class and the
--   next newline, inclusive, are also ignored. This is equivalent to
--   Perl's /x option, and it can be changed within a pattern by a (?x)
--   option setting.
--   
--   This option makes it possible to include comments inside complicated
--   patterns. Note, however, that this applies only to data characters.
--   Whitespace characters may never appear within special character
--   sequences in a pattern, for example within the sequence (?( which
--   introduces a conditional subpattern.
extended :: PCREOption

-- | <a>extra</a>
--   
--   This option was invented in order to turn on additional functionality
--   of PCRE that is incompatible with Perl, but it is currently of very
--   little use. When set, any backslash in a pattern that is followed by a
--   letter that has no special meaning causes an error, thus reserving
--   these combinations for future expansion. By default, as in Perl, a
--   backslash followed by a letter with no special meaning is treated as a
--   literal. (Perl can, however, be persuaded to give a warning for this.)
--   There are at present no other features controlled by this option. It
--   can also be set by a (?X) option setting within a pattern.
extra :: PCREOption

-- | <a>firstline</a>
--   
--   If this option is set, an unanchored pattern is required to match
--   before or at the first newline in the subject string, though the
--   matched text may continue over the newline.
firstline :: PCREOption

-- | <a>multiline</a>
--   
--   By default, PCRE treats the subject string as consisting of a single
--   line of characters (even if it actually contains newlines). The
--   <i>start of line</i> metacharacter (^) matches only at the start of
--   the string, while the <i>end of line</i> metacharacter ($) matches
--   only at the end of the string, or before a terminating newline (unless
--   <a>dollar_endonly</a> is set). This is the same as Perl.
--   
--   When <a>multiline</a> it is set, the <i>start of line</i> and <i>end
--   of line</i> constructs match immediately following or immediately
--   before internal newlines in the subject string, respectively, as well
--   as at the very start and end. This is equivalent to Perl's /m option,
--   and it can be changed within a pattern by a (?m) option setting. If
--   there are no newlines in a subject string, or no occur- rences of ^ or
--   $ in a pattern, setting PCRE_MULTILINE has no effect.
multiline :: PCREOption

-- | newline_cr', <a>newline_lf</a>, <a>newline_crlf</a>,
--   <tt>newline_anycrlf</tt>, <tt>newline_any</tt>
--   
--   These options override the default newline definition that was chosen
--   when PCRE was built. Setting the first or the second specifies that a
--   newline is indicated by a single character (CR or LF, respectively).
--   Setting <a>newline_crlf</a> specifies that a newline is indicated by
--   the two-character CRLF sequence. Setting <tt>newline_anycrlf</tt>
--   specifies that any of the three preceding sequences should be
--   recognized. Setting <tt>newline_any</tt> specifies that any Unicode
--   newline sequence should be recognized. The Unicode newline sequences
--   are the three just mentioned, plus the single characters VT (vertical
--   tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line
--   separator, U+2028), and PS (paragraph separator, U+2029). The last two
--   are recognized only in UTF-8 mode.
--   
--   The newline setting in the options word uses three bits that are
--   treated as a number, giving eight possibilities. Currently only six
--   are used (default plus the five values above). This means that if you
--   set more than one newline option, the combination may or may not be
--   sensible. For example, <a>newline_cr</a> with <a>newline_lf</a> is
--   equivalent to <a>newline_crlf</a>, but other combinations may yield
--   unused numbers and cause an error.
--   
--   The only time that a line break is specially recognized when compiling
--   a pattern is if <a>extended</a> is set, and an unescaped # outside a
--   character class is encountered. This indicates a comment that lasts
--   until after the next line break sequence. In other circumstances, line
--   break sequences are treated as literal data, except that in
--   <a>extended</a> mode, both CR and LF are treated as whitespace
--   characters and are therefore ignored. --
--   
--   The newline option that is set at compile time becomes the default
--   that is used for <tt>exec</tt> but it can be overridden.
--   
--   newline_any :: PCREOption newline_any = PCREOption newline_any_cint
--   
--   <tt>newline_anycrlf</tt>, see <tt>newline_any</tt> newline_anycrlf ::
--   PCREOption newline_anycrlf = PCREOption newline_anycrlf_cint
--   
--   <a>newline_cr</a>, see <tt>newline_any</tt>
newline_cr :: PCREOption

-- | <a>newline_crlf</a>, see <tt>newline_any</tt>
newline_crlf :: PCREOption

-- | <a>newline_lf</a>, see <tt>newline_any</tt>
newline_lf :: PCREOption

-- | <a>no_auto_capture</a>
--   
--   If this option is set, it disables the use of numbered capturing
--   parentheses in the pattern. Any opening paren- thesis that is not
--   followed by ? behaves as if it were followed by ?: but named
--   parentheses can still be used for capturing (and they acquire numbers
--   in the usual way). There is no equivalent of this option in Perl.
no_auto_capture :: PCREOption

-- | <a>ungreedy</a>
--   
--   This option inverts the <i>greediness</i> of the quantifiers so that
--   they are not greedy by default, but become greedy if followed by
--   <i>?</i>. It is not compatible with Perl. It can also be set by a (?U)
--   option setting within the pattern.
ungreedy :: PCREOption

-- | <a>utf8</a>
--   
--   This option causes PCRE to regard both the pattern and the subject as
--   strings of UTF-8 characters instead of single-byte character strings.
--   However, it is available only when PCRE is built to include UTF-8
--   support. If not, the use of this option provokes an error. Details of
--   how this option changes the behaviour of PCRE are given in the section
--   on UTF-8 support in the main pcre page.
utf8 :: PCREOption

-- | <a>no_utf8_check</a>
--   
--   When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string
--   is automatically checked. There is a discussion about the validity of
--   UTF-8 strings in the main pcre page. If an invalid UTF-8 sequence of
--   bytes is found, compile() returns an error. If you already know that
--   your pattern is valid, and you want to skip this check for performance
--   reasons, you can set the <a>no_utf8_check</a> option. When it is set,
--   the effect of passing an invalid UTF-8 string as a pattern is
--   undefined. It may cause your program to crash. Note that this option
--   can also be passed to <tt>exec</tt>, to suppress the UTF-8 validity
--   checking of subject strings.
no_utf8_check :: PCREOption
data PCREExecOption

-- | <a>anchored</a>.
--   
--   The <a>anchored</a> option limits <tt>exec</tt> to matching at the
--   first matching position. If a pattern was compiled with
--   <a>anchored</a>, or turned out to be anchored by virtue of its
--   contents, it cannot be made unachored at matching time.
exec_anchored :: PCREExecOption

-- | <a>newline_cr</a>, <a>newline_lf</a>, <a>newline_crlf</a>,
--   <tt>newline_anycrlf</tt>, <tt>newline_any</tt>
--   
--   These options override the newline definition that was chosen or
--   defaulted when the pattern was compiled. For details, see the
--   description of <tt>compile</tt> above. Dur- ing matching, the newline
--   choice affects the behaviour of the dot, circumflex, and dollar
--   metacharacters. It may also alter the way the match position is
--   advanced after a match failure for an unanchored pattern.
--   
--   When <a>newline_crlf</a>, <tt>newline_anycrlf</tt>, or
--   <tt>newline_any</tt> is set, and a match attempt for an unanchored
--   pattern fails when the current position is at a CRLF sequence, and the
--   pattern contains no explicit matches for CR or LF characters, the
--   match position is advanced by two characters instead of one, in other
--   words, to after the CRLF.
--   
--   The above rule is a compromise that makes the most common cases work
--   as expected. For example, if the pattern is .+A (and the <a>dotall</a>
--   option is not set), it does not match the string <i>\\r\\nA</i>
--   because, after failing at the start, it skips both the CR and the LF
--   before retrying. However, the pattern <i>[\\r\\n]A</i> does match that
--   string, because it contains an explicit CR or LF reference, and so
--   advances only by one character after the first failure.
--   
--   An explicit match for CR of LF is either a literal appear- ance of one
--   of those characters, or one of the \r or \n escape sequences. Implicit
--   matches such as [^X] do not count, nor does \s (which includes CR and
--   LF in the char- acters that it matches).
--   
--   Notwithstanding the above, anomalous effects may still occur when CRLF
--   is a valid newline sequence and explicit \r or \n escapes appear in
--   the pattern.
--   
--   exec_newline_any :: PCREExecOption exec_newline_any = PCREExecOption
--   exec_newline_any_cint
--   
--   <tt>exec_newline_anycrlf</tt>, see <tt>exec_newline_any</tt>
--   exec_newline_anycrlf :: PCREExecOption exec_newline_anycrlf =
--   PCREExecOption exec_newline_anycrlf_cint
--   
--   <a>exec_newline_cr</a>, see <tt>exec_newline_any</tt>
exec_newline_cr :: PCREExecOption

-- | <a>exec_newline_crlf</a>, see <tt>exec_newline_any</tt>
exec_newline_crlf :: PCREExecOption

-- | <a>exec_newline_lf</a>, see <tt>exec_newline_any</tt>
exec_newline_lf :: PCREExecOption

-- | <tt>PCRE_NOTBOL</tt>
--   
--   This option specifies that first character of the subject string is
--   not the beginning of a line, so the circumflex metacharacter should
--   not match before it. Setting this without <a>multiline</a> (at compile
--   time) causes circumflex never to match. This option affects only the
--   behaviour of the circumflex metacharacter. It does not affect \A.
exec_notbol :: PCREExecOption

-- | <tt>noteol</tt>
--   
--   This option specifies that the end of the subject string is not the
--   end of a line, so the dollar metacharacter should not match it nor
--   (except in multiline mode) a newline immediately before it. Setting
--   this without <a>multiline</a> (at compile time) causes dollar never to
--   match. This option affects only the behaviour of the dollar
--   metacharacter. It does not affect \Z or \z.
exec_noteol :: PCREExecOption

-- | PCRE_NOTEMPTY
--   
--   An empty string is not considered to be a valid match if this option
--   is set. If there are alternatives in the pattern, they are tried. If
--   all the alternatives match the empty string, the entire match fails.
--   For example, if the pattern
--   
--   <pre>
--   a?b?
--   </pre>
--   
--   is applied to a string not beginning with <i>a</i> or <i>b</i>, it
--   matches the empty string at the start of the subject. With
--   <tt>notempty</tt> set, this match is not valid, so 'PCRE searches
--   further into the string for occurrences of <i>a</i> or <i>b</i>.
--   
--   Perl has no direct equivalent of <tt>notempty</tt>, but it does make a
--   special case of a pattern match of the empty string within its split()
--   function, and when using the /g modifier. It is possible to emulate
--   Perl's behaviour after matching a null string by first trying the
--   match again at the same offset with PCRE_NOTEMPTY and PCRE_ANCHORED,
--   and then if that fails by advancing the starting offset (see below)
--   and trying an ordinary match again. There is some code that
--   demonstrates how to do this in the pcredemo.c sample program.
exec_notempty :: PCREExecOption

-- | <a>no_utf8_check</a>
--   
--   When <a>utf8</a> is set at compile time, the validity of the subject
--   as a UTF-8 string is automatically checked when exec() is subsequently
--   called. The value of startoffset is also checked to ensure that it
--   points to the start of a UTF-8 character. There is a discussion about
--   the validity of UTF-8 strings in the section on UTF-8 support in the
--   main pcre page. If an invalid UTF-8 sequence of bytes is found, exec()
--   returns the error <a>error_badutf8</a>. If startoffset contains an
--   invalid value, <a>error_badutf8_offset</a> is returned.
--   
--   If you already know that your subject is valid, and you want to skip
--   these checks for performance reasons, you can set the
--   <a>no_utf8_check</a> option when calling <tt>exec</tt>. You might want
--   to do this for the second and subsequent calls to exec() if you are
--   making repeated calls to find all the matches in a single subject
--   string. However, you should be sure that the value of startoffset
--   points to the start of a UTF-8 character. When <a>no_utf8_check</a> is
--   set, the effect of passing an invalid UTF-8 string as a subject, or a
--   value of startoff- set that does not point to the start of a UTF-8
--   character, is undefined. Your program may crash.
exec_no_utf8_check :: PCREExecOption

-- | <tt>partial</tt>
--   
--   This option turns on the partial matching feature. If the subject
--   string fails to match the pattern, but at some point during the
--   matching process the end of the subject was reached (that is, the
--   subject partially matches the pattern and the failure to match
--   occurred only because there were not enough subject characters),
--   <tt>exec</tt> returns <a>error_partial</a> instead of
--   <a>error_nomatch</a>. When <tt>partial</tt> is used, there are
--   restrictions on what may appear in the pattern. These are discussed in
--   the pcrepartial documentation.
exec_partial :: PCREExecOption