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

-- | Common "Text.Regex.*" API for Regex matching
--   
--   This package does not provide the ability to do regular expression
--   matching. Instead, it provides the type classes that constitute the
--   abstract API that is implemented by regex-* backends such as:
--   
--   
--   
- regex-posix
--   
- regex-parsec
--   
- regex-dfa
--   
- regex-tdfa
--   
- regex-pcre
--   
--   
--   See also https://wiki.haskell.org/Regular_expressions for more
--   information.
@package regex-base
@version 0.94.0.3

-- | 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,
--   Extract ByteString, and Extract Text.
--   There are no data values. The RegexContext instances are in
--   Text.Regex.Base.Context, 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 separately, 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

-- | No options set at all in the backend.
blankCompOpt :: RegexOptions regex compOpt execOpt => compOpt

-- | No options set at all in the backend.
blankExecOpt :: RegexOptions regex compOpt execOpt => execOpt

-- | Reasonable options (extended, caseSensitive, multiline regex).
defaultCompOpt :: RegexOptions regex compOpt execOpt => compOpt

-- | Reasonable options (extended, caseSensitive, multiline regex).
defaultExecOpt :: RegexOptions regex compOpt execOpt => execOpt

-- | Forget old flags and use new ones.
setExecOpts :: RegexOptions regex compOpt execOpt => execOpt -> regex -> regex

-- | Retrieve the current flags.
getExecOpts :: RegexOptions regex compOpt execOpt => regex -> execOpt

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

-- | Use the defaultCompOpt and defaultExecOpt.
makeRegex :: RegexMaker regex compOpt execOpt source => source -> regex

-- | Specify your own options.
makeRegexOpts :: RegexMaker regex compOpt execOpt source => compOpt -> execOpt -> source -> regex

-- | Use the defaultCompOpt and defaultExecOpt, reporting
--   errors with fail.
makeRegexM :: (RegexMaker regex compOpt execOpt source, MonadFail m) => source -> m regex

-- | Specify your own options, reporting errors with fail
makeRegexOptsM :: (RegexMaker regex compOpt execOpt source, MonadFail 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. Conversely, 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.
--   
--   
--   [ c | let notVowel = makeRegex "[^aeiou]" :: Regex, c <- ['a'..'z'], matchTest notVowel [c]  ]
--   
--   "bcdfghjklmnpqrstvwxyz"
--   
--   
--   The strictness of these functions is instance dependent.
class Extract source => RegexLike regex source

-- | This returns the first match in the source (it checks the whole
--   source, not just at the start). This returns an array of
--   (offset,length) index pairs for the match and captured substrings. The
--   offset is 0-based. A (-1) for an offset means a failure to match. The
--   lower bound of the array is 0, and the 0th element is the
--   (offset,length) for the whole match.
matchOnce :: RegexLike regex source => regex -> source -> Maybe MatchArray

-- | matchAll returns a list of matches. The matches are in order
--   and do not overlap. If any match succeeds but has 0 length then this
--   will be the last match in the list.
matchAll :: RegexLike regex source => regex -> source -> [MatchArray]

-- | matchCount returns the number of non-overlapping matches
--   returned by matchAll.
matchCount :: RegexLike regex source => regex -> source -> Int

-- | matchTest returns True if there is a match somewhere
--   in the source (it checks the whole source not just at the start).
matchTest :: RegexLike regex source => regex -> source -> Bool

-- | This is matchAll with the actual subsections of the source
--   instead of just the (offset,length) information.
matchAllText :: RegexLike regex source => regex -> source -> [MatchText source]

-- | This can return a tuple of three items: the source before the match,
--   an array of the match and captured substrings (with their indices),
--   and the source after the match.
matchOnceText :: RegexLike regex source => regex -> source -> Maybe (source, MatchText source, source)

-- | RegexContext is the polymorphic interface to do matching.
--   Since target is polymorphic you may need to supply the type
--   explicitly in contexts where it cannot be inferred.
--   
--   The monadic matchM version uses fail to report when
--   the regex has no match in source. Two examples:
--   
--   Here the contest Bool is inferred:
--   
--   
--   [ c | let notVowel = makeRegex "[^aeiou]" :: Regex, c <- ['a'..'z'], match notVowel [c]  ]
--   
--   "bcdfghjklmnpqrstvwxyz"
--   
--   
--   Here the context [String] must be supplied:
--   
--   
--   let notVowel = (makeRegex "[^aeiou]" :: Regex )
--   in do { c <- ['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"]
--   
class RegexLike regex source => RegexContext regex source target
match :: RegexContext regex source target => regex -> source -> target
matchM :: (RegexContext regex source target, MonadFail m) => regex -> source -> m target

-- | Extract allows for indexing operations on String or
--   ByteString.
class Extract source

-- | before is a renamed take.
before :: Extract source => Int -> source -> source

-- | after is a renamed drop.
after :: Extract source => Int -> source -> source

-- | When there is no match, this can construct an empty data value.
empty :: Extract source => source

-- | extract takes an offset and length, and has this default
--   implementation:
--   
--   
--   extract (off, len) source = before len (after off source)
--   
extract :: Extract source => (Int, Int) -> source -> source

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

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

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

-- | Used in results of RegexContext instances.
newtype AllTextMatches (f :: Type -> Type) b
AllTextMatches :: f b -> AllTextMatches (f :: Type -> Type) b
[getAllTextMatches] :: AllTextMatches (f :: Type -> Type) b -> f b
instance Text.Regex.Base.RegexLike.Extract Data.ByteString.Lazy.Internal.ByteString
instance Text.Regex.Base.RegexLike.Extract Data.ByteString.Internal.Type.ByteString
instance Text.Regex.Base.RegexLike.Extract GHC.Internal.Base.String
instance Text.Regex.Base.RegexLike.Extract (Data.Sequence.Internal.Seq a)
instance Text.Regex.Base.RegexLike.Extract Data.Text.Internal.Lazy.Text
instance Text.Regex.Base.RegexLike.Extract Data.Text.Internal.Text

-- | This is a module of instances of RegexContext (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
--   interchangeably. These instances provide the different results that
--   can be gotten from a match or matchM operation (often
--   via the =~ and =~~ operators with combine
--   makeRegex with match and matchM 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.
--   
--   RegexContext a b c takes a regular expression suppied
--   in a type a generated by RegexMaker and a target
--   text supplied in type b to a result type c using the
--   match class function. The matchM class function works
--   like match unless there is no match found, in which case it
--   calls fail in the (arbitrary) monad context.
--   
--   There are a few type synonyms from Text.Regex.Base.RegexLike
--   that are used here:
--   
--   
--   -- | 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))
--   
--   
--   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.
--   
--   
--   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 }
--   
--   
--   The newtypes' f parameters are the containers, usually
--   [] or Array Int, (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 MatchOffset
--   of (-1) and non-negative otherwise. The semantics of submatches depend
--   on the backend and its compile and execution options. Where provided,
--   MatchLength 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:
--   
--    RegexContext a b Bool : Whether there is any match or
--   not.
--   
--    RegexContext a b () : Useful as a guard with
--   matchM or =~~ in a monad, since failure to match
--   calls fail.
--   
--    RegexContext a b b : This returns the text of the
--   whole match. It will return empty from the Extract type
--   class if there is no match. These are defined in each backend module,
--   but documented here for convenience.
--   
--    RegexContext a b (MatchOffset, MatchLength)
--   : This returns the initial index and length of the whole match.
--   MatchLength will always be non-negative, and 0 for a failed match.
--   
--    RegexContext a b (MatchResult b) : The
--   MatchResult structure with details for the match. This is the
--   structure copied from the old JRegex pacakge.
--   
--    RegexContext a b (b, b, b) : The text before the
--   match, the text of the match, the text after the match
--   
--    RegexContext a b (b, MatchText b, b) : The
--   text before the match, the details of the match, and the text after
--   the match
--   
--    RegexContext a b (b, b, b, [b]) : 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 Text.Regex API.
--   
--   Two containers of the submatch offset information:
--   
--    RegexContext a b MatchArray : Array of
--   (MatchOffset, MatchLength) for all the sub
--   matches. The whole match is at the intial 0th index. Noncaptured
--   submatches will have a MatchOffset of (-1) The array
--   will have no elements and bounds (1,0) if there is no match.
--   
--    RegexContext a b (AllSubmatches []
--   (MatchOffset, MatchLength) : List of
--   (MatchOffset, MatchLength) 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:
--   
--   
--   RegexContext a b (AllTextSubmatches (Array Int) (b, (MatchOffset, MatchLength)))
--   
--   
--   
--   RegexContext a b (AllTextSubmatches [] (b, (MatchOffset, MatchLength)))
--   
--   
--   Two containers of the submatch text information:
--   
--   
--   RegexContext a b (AllTextSubmatches [] b)
--   
--   
--   
--   RegexContext a b (AllTextSubmatches (Array Int) b)
--   
--   
--   These instances are for all the matches (non-overlapping). Note that
--   backends are supposed to supply RegexLike instances for which
--   the default matchAll and matchAllText stop searching
--   after returning any successful but empty match.
--   
--    RegexContext a b Int : The number of matches,
--   non-negative.
--   
--   Two containers for locations of all matches:
--   
--   
--   RegexContext a b (AllMatches [] (MatchOffset, MatchLength))
--   
--   
--   
--   RegexContext a b (AllMatches (Array Int) (MatchOffset, MatchLength))
--   
--   
--   Two containers for the locations of all matches and their submatches:
--   
--   
--   RegexContext a b [MatchArray]
--   
--   
--   
--   RegexContext a b (AllMatches (Array Int) MatchArray)
--   
--   
--   Two containers for the text and locations of all matches and their
--   submatches:
--   
--   
--   RegexContext a b [MatchText b]
--   
--   
--   
--   RegexContext a b (AllTextMatches (Array Int) (MatchText b))
--   
--   
--   Two containers for text of all matches:  RegexContext a b
--   (AllTextMatches [] b) 
--   
--   
--   RegexContext a b (AllTextMatches (Array Int) b)
--   
--   
--   Four containers for text of all matches and their submatches:
--   
--   
--   RegexContext a b [[b]]
--   
--   
--   
--   RegexContext a b (AllTextMatches (Array Int) [b])
--   
--   
--   
--   RegexContext a b (AllTextMatches [] (Array Int b))
--   
--   
--   
--   RegexContext a b (AllTextMatches (Array Int) (Array Int b))
--   
--   
--   Unused matches are empty (defined via Extract)
module Text.Regex.Base.Context
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllMatches [] (Text.Regex.Base.RegexLike.MatchOffset, Text.Regex.Base.RegexLike.MatchLength))
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllMatches (GHC.Internal.Arr.Array GHC.Types.Int) (Text.Regex.Base.RegexLike.MatchOffset, Text.Regex.Base.RegexLike.MatchLength))
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllMatches (GHC.Internal.Arr.Array GHC.Types.Int) Text.Regex.Base.RegexLike.MatchArray)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllSubmatches [] (Text.Regex.Base.RegexLike.MatchOffset, Text.Regex.Base.RegexLike.MatchLength))
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextMatches (GHC.Internal.Arr.Array GHC.Types.Int) (Text.Regex.Base.RegexLike.MatchText b))
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextMatches [] b)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextMatches (GHC.Internal.Arr.Array GHC.Types.Int) b)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextMatches (GHC.Internal.Arr.Array GHC.Types.Int) [b])
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextMatches [] (GHC.Internal.Arr.Array GHC.Types.Int b))
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextMatches (GHC.Internal.Arr.Array GHC.Types.Int) (GHC.Internal.Arr.Array GHC.Types.Int b))
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextSubmatches (GHC.Internal.Arr.Array GHC.Types.Int) (b, (Text.Regex.Base.RegexLike.MatchOffset, Text.Regex.Base.RegexLike.MatchLength)))
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextSubmatches [] (b, (Text.Regex.Base.RegexLike.MatchOffset, Text.Regex.Base.RegexLike.MatchLength)))
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextSubmatches [] b)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.AllTextSubmatches (GHC.Internal.Arr.Array GHC.Types.Int) b)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b Text.Regex.Base.RegexLike.MatchArray
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b GHC.Types.Bool
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b GHC.Types.Int
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b [Text.Regex.Base.RegexLike.MatchArray]
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b [Text.Regex.Base.RegexLike.MatchText b]
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b [[b]]
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.MatchResult b)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (Text.Regex.Base.RegexLike.MatchOffset, Text.Regex.Base.RegexLike.MatchLength)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (b, Text.Regex.Base.RegexLike.MatchText b, b)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (b, b, b)
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b (b, b, b, [b])
instance Text.Regex.Base.RegexLike.RegexLike a b => Text.Regex.Base.RegexLike.RegexContext a b ()

-- | Classes and instances for Regex matching.
--   
--   This module merely imports and re-exports the common part of the new
--   api: Text.Regex.Base.RegexLike and
--   Text.Regex.Base.Context.
--   
--   To see what result types the instances of RegexContext can produce,
--   please read the Text.Regex.Base.Context 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:
--   
--   
--   
- Text.Regex.Posix from regex-posix
--   
- Text.Regex from regex-compat (uses
--   regex-posix)
--   
- Text.Regex.Parsec from regex-parsec
--   
- Text.Regex.DFA from regex-dfa
--   
- Text.Regex.PCRE from regex-pcre
--   
- Test.Regex.TRE from regex-tre
--   
--   
--   In fact, just importing one of the backends is adequate, you do not
--   also need to import this module.
--   
--   
Example
--   
--   The code
--   
--   
--   import Text.Regex.Base
--   import Text.Regex.Posix ((=~),(=~~)) -- or TDFA or PCRE or ...
--   
--   main = do
--       print b
--       print c
--       print d
--     where
--       b :: Bool
--       b = ("abaca" =~ "(.)a")
--       c :: [MatchArray]
--       c = ("abaca" =~ "(.)a")
--       d :: Maybe (String,String,String,[String])
--       d = ("abaca" =~~ "(.)a")
--   
--   
--   will output
--   
--   
--   True
--   [array (0,1) [(0,(1,2)),(1,(1,1))],array (0,1) [(0,(3,2)),(1,(3,1))]]
--   Just ("a","ba","ca",["b"])
--   
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:
--   
--   
--   instance (RegexLike regex source) => RegexContext regex source source where
--   
--   
--   runs into overlapping restrictions. To avoid this I have each backend
--   define, for its own Regex type:
--   
--   
--   instance RegexContext Regex String String where
--     match = polymatch
--     matchM = polymatchM
--   
--   
--   
--   instance RegexContext Regex ByteString ByteString where
--     match = polymatch
--     matchM = polymatchM
--   
--   
--   
--   instance RegexContext Regex Text Text where
--     match = polymatch
--     matchM = polymatchM
--   
module Text.Regex.Base.Impl
polymatch :: RegexLike a b => a -> b -> b
polymatchM :: (RegexLike a b, MonadFail m) => a -> b -> m b
