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


-- | Replaces/Enhances Text.Regex
--   
--   Interface API for regex-posix,pcre,parsec,tdfa,dfa
@package regex-base
@version 0.93


-- | Classes and instances for Regex matching.
--   
--   All the classes are declared here, and some common type aliases, and
--   the MatchResult data type.
--   
--   The only instances here are for Extract String and Extract ByteString.
--   There are no data values. The <a>RegexContext</a> instances are in
--   <a>Text.Regex.Base.Context</a>, except for ones which run afoul of a
--   repeated variable (RegexContext regex a a), which are defined in each
--   modules' String and ByteString modules.
module Text.Regex.Base.RegexLike

-- | 0 based index from start of source, or (-1) for unused
type MatchOffset = Int

-- | non-negative length of a match
type MatchLength = Int

-- | 0 based array, with 0th index indicating the full match. If the full
--   match location is not available, represent as (0,0).
type MatchArray = Array Int (MatchOffset, MatchLength)
type MatchText source = Array Int (source, (MatchOffset, MatchLength))

-- | This is the same as the type from JRegex.
data MatchResult a
MR :: a -> a -> a -> [a] -> Array Int a -> MatchResult a
mrBefore :: MatchResult a -> a
mrMatch :: MatchResult a -> a
mrAfter :: MatchResult a -> a
mrSubList :: MatchResult a -> [a]
mrSubs :: MatchResult a -> Array Int a

-- | Rather than carry them around spearately, the options for how to
--   execute a regex are kept as part of the regex. There are two types of
--   options. Those that can only be specified at compilation time and
--   never changed are CompOpt. Those that can be changed later and affect
--   how matching is performed are ExecOpt. The actually types for these
--   depend on the backend.
class RegexOptions regex compOpt execOpt | regex -> compOpt execOpt, compOpt -> regex execOpt, execOpt -> regex compOpt
blankCompOpt :: (RegexOptions regex compOpt execOpt) => compOpt
blankExecOpt :: (RegexOptions regex compOpt execOpt) => execOpt
defaultCompOpt :: (RegexOptions regex compOpt execOpt) => compOpt
defaultExecOpt :: (RegexOptions regex compOpt execOpt) => execOpt
setExecOpts :: (RegexOptions regex compOpt execOpt) => execOpt -> regex -> regex
getExecOpts :: (RegexOptions regex compOpt execOpt) => regex -> execOpt

-- | RegexMaker captures the creation of the compiled regular expression
--   from a source type and an option type. <a>makeRegexM</a> and
--   <a>makeRegexM</a> report parse error using <tt>MonadError</tt>,
--   usually (Either String regex).
--   
--   The <a>makeRegex</a> function has a default implementation that
--   depends on makeRegexOpts and used <a>defaultCompOpt</a> and
--   <a>defaultExecOpt</a>. Similarly for <a>makeRegexM</a> and
--   <a>makeRegexOptsM</a>.
--   
--   There are also default implementaions for <a>makeRegexOpts</a> and
--   <a>makeRegexOptsM</a> in terms of each other. So a minimal instance
--   definition needs to only define one of these, hopefully
--   <a>makeRegexOptsM</a>.
class (RegexOptions regex compOpt execOpt) => RegexMaker regex compOpt execOpt source | regex -> compOpt execOpt, compOpt -> regex execOpt, execOpt -> regex compOpt
makeRegex :: (RegexMaker regex compOpt execOpt source) => source -> regex
makeRegexOpts :: (RegexMaker regex compOpt execOpt source) => compOpt -> execOpt -> source -> regex
makeRegexM :: (RegexMaker regex compOpt execOpt source, Monad m) => source -> m regex
makeRegexOptsM :: (RegexMaker regex compOpt execOpt source, Monad m) => compOpt -> execOpt -> source -> m regex

-- | RegexLike is parametrized on a regular expression type and a source
--   type to run the matching on.
--   
--   There are default implementations: matchTest and matchOnceText use
--   matchOnce; matchCount and matchAllText use matchAll. matchOnce uses
--   matchOnceText and matchAll uses matchAllText. So a minimal complete
--   instance need to provide at least (matchOnce or matchOnceText) and
--   (matchAll or matchAllText). Additional definitions are often provided
--   where they will increase efficiency.
--   
--   <pre>
--   [ c | let notVowel = makeRegex "[^aeiou]" :: Regex, c &lt;- ['a'..'z'], matchTest notVowel [c]  ]
--   
--   "bcdfghjklmnpqrstvwxyz"
--   </pre>
--   
--   The strictness of these functions is instance dependent.
class (Extract source) => RegexLike regex source
matchOnce :: (RegexLike regex source) => regex -> source -> Maybe MatchArray
matchAll :: (RegexLike regex source) => regex -> source -> [MatchArray]
matchCount :: (RegexLike regex source) => regex -> source -> Int
matchTest :: (RegexLike regex source) => regex -> source -> Bool
matchAllText :: (RegexLike regex source) => regex -> source -> [MatchText source]
matchOnceText :: (RegexLike regex source) => regex -> source -> Maybe (source, MatchText source, source)

-- | RegexContext is the polymorphic interface to do matching. Since
--   <tt>target</tt> is polymorphic you may need to suply the type
--   explicitly in contexts where it cannot be inferred.
--   
--   The monadic <a>matchM</a> version uses <a>fail</a> to report when the
--   <tt>regex</tt> has no match in <tt>source</tt>. Two examples:
--   
--   Here the contest <a>Bool</a> is inferred:
--   
--   <pre>
--   [ c | let notVowel = makeRegex "[^aeiou]" :: Regex, c &lt;- ['a'..'z'], match notVowel [c]  ]
--   
--   "bcdfghjklmnpqrstvwxyz"
--   </pre>
--   
--   Here the context '[String]' must be supplied:
--   
--   <pre>
--   let notVowel = (makeRegex "[^aeiou]" :: Regex )
--   in do { c &lt;- ['a'..'z'] ; matchM notVowel [c] } :: [String]
--   
--   ["b","c","d","f","g","h","j","k","l","m","n","p","q","r","s","t","v","w","x","y","z"]
--   </pre>
class (RegexLike regex source) => RegexContext regex source target
match :: (RegexContext regex source target) => regex -> source -> target
matchM :: (RegexContext regex source target, Monad m) => regex -> source -> m target

-- | Extract allows for indexing operations on String or ByteString.
class Extract source
before :: (Extract source) => Int -> source -> source
after :: (Extract source) => Int -> source -> source
empty :: (Extract source) => source
extract :: (Extract source) => (Int, Int) -> source -> source

-- | Used in results of RegexContext instances
newtype AllSubmatches f b
AllSubmatches :: (f b) -> AllSubmatches f b
getAllSubmatches :: AllSubmatches f b -> (f b)

-- | Used in results of RegexContext instances
newtype AllTextSubmatches f b
AllTextSubmatches :: (f b) -> AllTextSubmatches f b
getAllTextSubmatches :: AllTextSubmatches f b -> (f b)

-- | Used in results of RegexContext instances
newtype AllMatches f b
AllMatches :: (f b) -> AllMatches f b
getAllMatches :: AllMatches f b -> (f b)

-- | Used in results of RegexContext instances
newtype AllTextMatches f b
AllTextMatches :: (f b) -> AllTextMatches f b
getAllTextMatches :: AllTextMatches f b -> (f b)
instance Extract (Seq a)
instance Extract ByteString
instance Extract ByteString
instance Extract String


-- | This is a module of instances of <a>RegexContext</a> (defined in
--   Text.Regex.Base.RegexLike). Nothing else is exported. This is usually
--   imported via the Text.Regex.Base convenience package which itself is
--   re-exported from newer Text.Regex.XXX modules provided by the
--   different regex-xxx backends.
--   
--   These instances work for all the supported types and backends
--   interchangably. These instances provide the different results that can
--   be gotten from a match or matchM operation (often via the <tt>=~</tt>
--   and <tt>=~~</tt> operators with combine <tt>makeRegex</tt> with
--   <tt>match</tt> and <tt>matchM</tt> respectively). This module name is
--   Context because they operators are context dependent: use them in a
--   context that expects an Int and you get a count of matches, use them
--   in a Bool context and get True if there is a match, etc.
--   
--   <tt>RegexContext a b c</tt> takes a regular expression suppied in a
--   type <tt>a</tt> generated by <tt>RegexMaker</tt> and a target text
--   supplied in type <tt>b</tt> to a result type <tt>c</tt> using the
--   <a>match</a> class function. The <a>matchM</a> class function works
--   like <a>match</a> unless there is no match found, in which case it
--   calls <a>fail</a> in the (arbitrary) monad context.
--   
--   There are a few type synonyms from RegexLike that are used here:
--   
--   <pre>
--    
--   -- | 0 based index from start of source, or (-1) for unused
--   type MatchOffset = Int
--   -- | non-negative length of a match
--   type MatchLength = Int
--   type MatchArray = Array Int (MatchOffset, MatchLength)
--   type MatchText source = Array Int (source, (MatchOffset, MatchLength))
--   </pre>
--   
--   There are also a few newtypes that used to prevent any possible
--   overlap of types, which were not needed for GHC's late overlap
--   detection but are needed for use in Hugs.
--   
--   <pre>
--   newtype AllSubmatches f b = AllSubmatches {getAllSubmatches :: (f b)}
--   newtype AllTextSubmatches f b = AllTextSubmatches {getAllTextSubmatches :: (f b)}
--   newtype AllMatches f b = AllMatches {getAllMatches :: (f b)}
--   newtype AllTextMatches f b = AllTextMatches {getAllTextMatches :: (f b) }
--   </pre>
--   
--   The newtypes' <tt>f</tt> parameters are the containers, usually
--   <tt>[]</tt> or <tt>Array Int</tt>, (where the arrays all have lower
--   bound 0).
--   
--   The two *Submatches newtypes return only information on the first
--   match. The other two newtypes return information on all the
--   non-overlapping matches. The two *Text* newtypes are used to mark
--   result types that contain the same type as the target text.
--   
--   Where provided, noncaptured submatches will have a
--   <tt>MatchOffset</tt> of (-1) and non-negative otherwise. The semantics
--   of submatches depend on the backend and its compile and execution
--   options. Where provided, <tt>MatchLength</tt> will always be
--   non-negative. Arrays with no elements are returned with bounds of
--   (1,0). Arrays with elements will have a lower bound of 0.
--   
--   XXX THIS HADDOCK DOCUMENTATION IS OUT OF DATE XXX
--   
--   These are for finding the first match in the target text:
--   
--   <tt> RegexContext a b Bool </tt> : Whether there is any match or not.
--   
--   <tt> RegexContext a b () </tt> : Useful as a guard with
--   <tt>matchM</tt> or <tt>=~~</tt> in a monad, since failure to match
--   calls <a>fail</a>.
--   
--   <tt> RegexContext a b b </tt> : This returns the text of the whole
--   match. It will return <a>empty</a> from the <a>Extract</a> type class
--   if there is no match. These are defined in each backend module, but
--   documented here for convenience.
--   
--   <tt> RegexContext a b (MatchOffset,MatchLength) </tt> : This returns
--   the initial index and length of the whole match. MatchLength will
--   always be non-negative, and 0 for a failed match.
--   
--   <tt> RegexContext a b (MatchResult b) </tt> : The <a>MatchResult</a>
--   structure with details for the match. This is the structure copied
--   from the old <tt>JRegex</tt> pacakge.
--   
--   <tt> RegexContext a b (b, b, b) </tt> : The text before the match, the
--   text of the match, the text after the match
--   
--   <tt> RegexContext a b (b, MatchText b, b) </tt> : The text before the
--   match, the details of the match, and the text after the match
--   
--   <tt> RegexContext a b (b, b, b, [b]) </tt> : The text before the
--   match, the text of the match, the text after the match, and a list of
--   the text of the 1st and higher sub-parts of the match. This is the
--   same return value as used in the old <tt>Text.Regex</tt> API.
--   
--   Two containers of the submatch offset information:
--   
--   <tt> RegexContext a b MatchArray </tt> : Array of
--   <tt>(MatchOffset,MatchLength)</tt> for all the sub matches. The whole
--   match is at the intial 0th index. Noncaptured submatches will have a
--   <tt>MatchOffset</tt> of (-1) The array will have no elements and
--   bounds (1,0) if there is no match.
--   
--   <tt> RegexContext a b (AllSubmatches [] (MatchOffset,MatchLength)
--   </tt> : List of <tt>(MatchOffset,MatchLength)</tt> The whole match is
--   the first element, the rest are the submatches (if any) in order. The
--   list is empty if there is no match.
--   
--   Two containers of the submatch text and offset information:
--   
--   <pre>
--   RegexContext a b (AllTextSubmatches (Array Int) (b, (MatchOffset, MatchLength)))
--   </pre>
--   
--   <pre>
--   RegexContext a b (AllTextSubmatches [] (b, (MatchOffset, MatchLength)))
--   </pre>
--   
--   Two containers of the submatch text information:
--   
--   <pre>
--   RegexContext a b (AllTextSubmatches [] b)
--   </pre>
--   
--   <pre>
--   RegexContext a b (AllTextSubmatches (Array Int) b)
--   </pre>
--   
--   These instances are for all the matches (non-overlapping). Note that
--   backends are supposed to supply <a>RegexLike</a> instances for which
--   the default <a>matchAll</a> and <a>matchAllText</a> stop searching
--   after returning any successful but empty match.
--   
--   <tt> RegexContext a b Int </tt> : The number of matches, non-negative.
--   
--   Two containers for locations of all matches:
--   
--   <pre>
--   RegexContext a b (AllMatches [] (MatchOffset, MatchLength))
--   </pre>
--   
--   <pre>
--   RegexContext a b (AllMatches (Array Int) (MatchOffset,MatchLength))
--   </pre>
--   
--   Two containers for the locations of all matches and their submatches:
--   
--   <tt> RegexContext a b [MatchArray] </tt> :
--   
--   <pre>
--   RegexContext a b (AllMatches (Array Int) MatchArray)
--   </pre>
--   
--   Two containers for the text and locations of all matches and their
--   submatches:
--   
--   <pre>
--   RegexContext a b [MatchText b]
--   </pre>
--   
--   <pre>
--   RegexContext a b (AllTextMatches (Array Int) (MatchText b))
--   </pre>
--   
--   Two containers for text of all matches: <tt> RegexContext a b
--   (AllTextMatches [] b) </tt>
--   
--   <pre>
--   RegexContext a b (AllTextMatches (Array Int) b)
--   </pre>
--   
--   Four containers for text of all matches and their submatches:
--   
--   <pre>
--   RegexContext a b [[b]]
--   </pre>
--   
--   <pre>
--   RegexContext a b (AllTextMatches (Array Int) [b])
--   </pre>
--   
--   <pre>
--   RegexContext a b (AllTextMatches [] (Array Int b))
--   </pre>
--   
--   <pre>
--   RegexContext a b (AllTextMatches (Array Int) (Array Int b))
--   </pre>
--   
--   Unused matches are <a>empty</a> (defined via <a>Extract</a>)
module Text.Regex.Base.Context
instance (RegexLike a b) => RegexContext a b (AllTextMatches (Array Int) (Array Int b))
instance (RegexLike a b) => RegexContext a b (AllTextMatches [] (Array Int b))
instance (RegexLike a b) => RegexContext a b (AllTextMatches (Array Int) [b])
instance (RegexLike a b) => RegexContext a b [[b]]
instance (RegexLike a b) => RegexContext a b (AllTextMatches (Array Int) b)
instance (RegexLike a b) => RegexContext a b (AllTextMatches [] b)
instance (RegexLike a b) => RegexContext a b (AllTextMatches (Array Int) (MatchText b))
instance (RegexLike a b) => RegexContext a b [MatchText b]
instance (RegexLike a b) => RegexContext a b (AllMatches (Array Int) MatchArray)
instance (RegexLike a b) => RegexContext a b [MatchArray]
instance (RegexLike a b) => RegexContext a b (AllMatches (Array Int) (MatchOffset, MatchLength))
instance (RegexLike a b) => RegexContext a b (AllMatches [] (MatchOffset, MatchLength))
instance (RegexLike a b) => RegexContext a b (AllTextSubmatches (Array Int) b)
instance (RegexLike a b) => RegexContext a b (AllTextSubmatches [] b)
instance (RegexLike a b) => RegexContext a b (AllTextSubmatches [] (b, (MatchOffset, MatchLength)))
instance (RegexLike a b) => RegexContext a b (AllTextSubmatches (Array Int) (b, (MatchOffset, MatchLength)))
instance (RegexLike a b) => RegexContext a b (AllSubmatches [] (MatchOffset, MatchLength))
instance (RegexLike a b) => RegexContext a b MatchArray
instance (RegexLike a b) => RegexContext a b (b, b, b, [b])
instance (RegexLike a b) => RegexContext a b (b, b, b)
instance (RegexLike a b) => RegexContext a b (b, MatchText b, b)
instance (RegexLike a b) => RegexContext a b (MatchResult b)
instance (RegexLike a b) => RegexContext a b (MatchOffset, MatchLength)
instance (RegexLike a b) => RegexContext a b Int
instance (RegexLike a b) => RegexContext a b ()
instance (RegexLike a b) => RegexContext a b Bool


-- | Classes and instances for Regex matching.
--   
--   This module merely imports and re-exports the common part of the new
--   api: <a>Text.Regex.Base.RegexLike</a> and
--   <a>Text.Regex.Base.Context</a>.
--   
--   To see what result types the instances of RegexContext can produce,
--   please read the <a>Text.Regex.Base.Context</a> haddock documentation.
--   
--   This does not provide any of the backends, just the common interface
--   they all use. The modules which provide the backends and their cabal
--   packages are:
--   
--   <ul>
--   <li><tt>Text.Regex.Posix</tt> from regex-posix</li>
--   <li><tt>Text.Regex</tt> from regex-compat (uses regex-posix)</li>
--   <li><tt>Text.Regex.Parsec</tt> from regex-parsec</li>
--   <li><tt>Text.Regex.DFA</tt> from regex-dfa</li>
--   <li><tt>Text.Regex.PCRE</tt> from regex-pcre</li>
--   <li><tt>Test.Regex.TRE</tt> from regex-tre</li>
--   </ul>
--   
--   In fact, just importing one of the backends is adequate, you do not
--   also need to import this module.
--   
--   TODO: Copy Example*hs files into this haddock comment
module Text.Regex.Base
getVersion_Text_Regex_Base :: Version


-- | Helper functions for defining certain instances of RegexContext. These
--   help when defining instances of RegexContext with repeated types:
--   
--   <pre>
--   instance (RegexLike regex source) =&gt; RegexContext regex source source where
--   </pre>
--   
--   runs into overlapping restrictions. To avoid this I have each backend
--   define, for its own Regex type:
--   
--   <pre>
--   instance RegexContext Regex String String where
--     match = polymatch
--     matchM = polymatchM
--   </pre>
--   
--   <pre>
--   instance RegexContext Regex ByteString ByteString where
--     match = polymatch
--     matchM = polymatchM
--   </pre>
module Text.Regex.Base.Impl
polymatch :: (RegexLike a b) => a -> b -> b
polymatchM :: (RegexLike a b, Monad m) => a -> b -> m b