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

-- | Regex-based parsing with applicative interface
--   
--   regex-applicative is a Haskell library for parsing using regular
--   expressions. Parsers can be built using Applicative interface.
@package regex-applicative
@version 0.3.4

-- | This internal module is exposed only for testing and benchmarking. You
--   don't need to import it.
module Text.Regex.Applicative.StateQueue

-- | StateQueue is a data structure that can efficiently insert
--   elements (preserving their order) and check whether an element with
--   the given Int key is already in the queue.
data StateQueue a

-- | The empty state queue
empty :: StateQueue a

-- | Insert an element in the state queue without a key.
--   
--   Since insert doesn't take a key, it won't affect any
--   insertUnique.
insert :: a -> StateQueue a -> StateQueue a

-- | Insert an element in the state queue, unless there is already an
--   element with the same key
insertUnique :: Int -> a -> StateQueue a -> StateQueue a

-- | Get the list of all elements
getElements :: StateQueue a -> [a]
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.Regex.Applicative.StateQueue.StateQueue a)
instance GHC.Internal.Data.Foldable.Foldable Text.Regex.Applicative.StateQueue.StateQueue
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Text.Regex.Applicative.StateQueue.StateQueue a)

-- | Reference implementation (using backtracking).
--   
--   This is exposed for testing purposes only!
module Text.Regex.Applicative.Reference

-- | reference r s should give the same results as
--   s =~ r.
--   
--   However, this is not very efficient implementation and is supposed to
--   be used for testing only.
reference :: RE s a -> [s] -> Maybe a
instance GHC.Internal.Base.Alternative (Text.Regex.Applicative.Reference.P s)
instance GHC.Internal.Base.Applicative (Text.Regex.Applicative.Reference.P s)
instance GHC.Internal.Base.Functor (Text.Regex.Applicative.Reference.P s)
instance GHC.Internal.Base.Monad (Text.Regex.Applicative.Reference.P s)

-- | This is a low-level interface to the regex engine.
module Text.Regex.Applicative.Object

-- | The state of the engine is represented as a "regex object" of type
--   ReObject s r, where s is the type of symbols
--   and r is the result type (as in the RE type). Think of
--   ReObject as a collection of Threads ordered by priority.
--   E.g. threads generated by the left part of <|> come
--   before the threads generated by the right part.
data ReObject s r

-- | Compile a regular expression into a regular expression object
compile :: RE s r -> ReObject s r

-- | Empty object (with no threads)
emptyObject :: ReObject s r

-- | A thread either is a result or corresponds to a symbol in the regular
--   expression, which is expected by that thread.
data Thread s r

-- | List of all threads of an object. Each non-result thread has a unique
--   id.
threads :: ReObject s r -> [Thread s r]

-- | Check if the object has no threads. In that case it never will produce
--   any new threads as a result of step.
failed :: ReObject s r -> Bool

-- | Check whether a thread is a result thread
isResult :: Thread s r -> Bool

-- | Return the result of a result thread, or Nothing if it's not a
--   result thread
getResult :: Thread s r -> Maybe r

-- | Extract the result values from all the result threads of an object
results :: ReObject s r -> [r]
data ThreadId

-- | Returns thread identifier. This will be Just for ordinary
--   threads and Nothing for results.
threadId :: Thread s r -> Maybe ThreadId

-- | Feed a symbol into a regex object
step :: s -> ReObject s r -> ReObject s r

-- | Feed a symbol into a non-result thread. It is an error to call
--   stepThread on a result thread.
stepThread :: s -> Thread s r -> [Thread s r]

-- | Create an object from a list of threads. It is recommended that all
--   threads come from the same ReObject, unless you know what
--   you're doing. However, it should be safe to filter out or rearrange
--   threads.
fromThreads :: [Thread s r] -> ReObject s r

-- | Add a thread to an object. The new thread will have lower priority
--   than the threads which are already in the object.
--   
--   If a (non-result) thread with the same id already exists in the
--   object, the object is not changed.
addThread :: Thread s r -> ReObject s r -> ReObject s r

-- | To get started, see some examples on the wiki:
--   https://github.com/feuerbach/regex-applicative/wiki/Examples
module Text.Regex.Applicative

-- | Type of regular expressions that recognize symbols of type s
--   and produce a result of type a.
--   
--   Regular expressions can be built using Functor,
--   Applicative, Alternative, and Filtrable instances
--   in the following natural way:
--   
--   
--   
- f <$> ra matches iff ra
--   matches, and its return value is the result of applying f to
--   the return value of ra.
--   
- pure x matches the empty string (i.e. it does not
--   consume any symbols), and its return value is x
--   
- rf <*> ra matches a string iff it
--   is a concatenation of two strings: one matched by rf and the
--   other matched by ra. The return value is f a, where
--   f and a are the return values of rf and
--   ra respectively.
--   
- ra <|> rb matches a string which is
--   accepted by either ra or rb. It is left-biased, so
--   if both can match, the result of ra is used.
--   
- empty is a regular expression which does not match any
--   string.
--   
- many ra matches concatenation of zero or more
--   strings matched by ra and returns the list of ra's
--   return values on those strings.
--   
- some ra matches concatenation of one or more
--   strings matched by ra and returns the list of ra's
--   return values on those strings.
--   
- catMaybes ram matches iff ram matches and
--   produces 'Just _'.
--   
- ra <> rb matches ra
--   followed by rb. The return value is a <> b,
--   where a and b are the return values of ra
--   and rb respectively. (See
--   https://github.com/feuerbach/regex-applicative/issues/37#issue-499781703
--   for an example usage.)
--   
- mempty matches the empty string (i.e. it does not consume
--   any symbols), and its return value is the mempty value of type
--   a.
--   
data RE s a

-- | Match and return the given symbol
sym :: Eq s => s -> RE s s

-- | Match and return a single symbol which satisfies the predicate
psym :: (s -> Bool) -> RE s s

-- | Like psym, but allows to return a computed value instead of the
--   original symbol
msym :: (s -> Maybe a) -> RE s a

-- | Match and return any single symbol
anySym :: RE s s

-- | Match and return the given sequence of symbols.
--   
--   Note that there is an IsString instance for regular expression,
--   so if you enable the OverloadedStrings language extension,
--   you can write string "foo" simply as "foo".
--   
--   Example:
--   
--   
--   {-# LANGUAGE OverloadedStrings #-}
--   import Text.Regex.Applicative
--   
--   number = "one" *> pure 1  <|>  "two" *> pure 2
--   
--   main = print $ "two" =~ number
--   
string :: Eq a => [a] -> RE a [a]

-- | Match zero or more instances of the given expression, which are
--   combined using the given folding function.
--   
--   Greediness argument controls whether this regular expression
--   should match as many as possible (Greedy) or as few as possible
--   (NonGreedy) instances of the underlying expression.
reFoldl :: Greediness -> (b -> a -> b) -> b -> RE s a -> RE s b
data Greediness
Greedy :: Greediness
NonGreedy :: Greediness

-- | Match zero or more instances of the given expression, but as few of
--   them as possible (i.e. non-greedily). A greedy equivalent of
--   few is many.
--   
--   Examples:
--   
--   
--   Text.Regex.Applicative> findFirstPrefix (few anySym  <* "b") "ababab"
--   Just ("a","abab")
--   Text.Regex.Applicative> findFirstPrefix (many anySym  <* "b") "ababab"
--   Just ("ababa","")
--   
few :: RE s a -> RE s [a]

-- | RE is a profunctor. This is its contravariant map.
--   
--   (A dependency on the profunctors package doesn't seem
--   justified.)
comap :: (s2 -> s1) -> RE s1 a -> RE s2 a

-- | Return matched symbols as part of the return value
withMatched :: RE s a -> RE s (a, [s])

-- | Attempt to match a string of symbols against the regular expression.
--   Note that the whole string (not just some part of it) should be
--   matched.
--   
--   Examples:
--   
--   
--   Text.Regex.Applicative> match (sym 'a' <|> sym 'b') "a"
--   Just 'a'
--   Text.Regex.Applicative> match (sym 'a' <|> sym 'b') "ab"
--   Nothing
--   
match :: RE s a -> [s] -> Maybe a

-- | 
--   s =~ a = match a s
--   
(=~) :: [s] -> RE s a -> Maybe a
infix 2 =~

-- | Replace matches of the regular expression with its value.
--   
--   
--   Text.Regex.Applicative > replace ("!" <$ sym 'f' <* some (sym 'o')) "quuxfoofooooofoobarfobar"
--   "quux!!!bar!bar"
--   
replace :: RE s [s] -> [s] -> [s]

-- | Find a string prefix which is matched by the regular expression.
--   
--   Of all matching prefixes, pick one using left bias (prefer the left
--   part of <|> to the right part) and greediness.
--   
--   This is the match which a backtracking engine (such as Perl's one)
--   would find first.
--   
--   If match is found, the rest of the input is also returned.
--   
--   See also findFirstPrefixWithUncons, of which this is a special
--   case.
--   
--   Examples:
--   
--   
--   Text.Regex.Applicative> findFirstPrefix ("a" <|> "ab") "abc"
--   Just ("a","bc")
--   Text.Regex.Applicative> findFirstPrefix ("ab" <|> "a") "abc"
--   Just ("ab","c")
--   Text.Regex.Applicative> findFirstPrefix "bc" "abc"
--   Nothing
--   
findFirstPrefix :: RE s a -> [s] -> Maybe (a, [s])

-- | Find the longest string prefix which is matched by the regular
--   expression.
--   
--   Submatches are still determined using left bias and greediness, so
--   this is different from POSIX semantics.
--   
--   If match is found, the rest of the input is also returned.
--   
--   See also findLongestPrefixWithUncons, of which this is a
--   special case.
--   
--   Examples:
--   
--   
--   Text.Regex.Applicative Data.Char> let keyword = "if"
--   Text.Regex.Applicative Data.Char> let identifier = many $ psym isAlpha
--   Text.Regex.Applicative Data.Char> let lexeme = (Left <$> keyword) <|> (Right <$> identifier)
--   Text.Regex.Applicative Data.Char> findLongestPrefix lexeme "if foo"
--   Just (Left "if"," foo")
--   Text.Regex.Applicative Data.Char> findLongestPrefix lexeme "iffoo"
--   Just (Right "iffoo","")
--   
findLongestPrefix :: RE s a -> [s] -> Maybe (a, [s])

-- | Find the shortest prefix (analogous to findLongestPrefix)
--   
--   See also findShortestPrefixWithUncons, of which this is a
--   special case.
findShortestPrefix :: RE s a -> [s] -> Maybe (a, [s])

-- | Find the leftmost substring that is matched by the regular expression.
--   Otherwise behaves like findFirstPrefix. Returns the result
--   together with the prefix and suffix of the string surrounding the
--   match.
findFirstInfix :: RE s a -> [s] -> Maybe ([s], a, [s])

-- | Find the leftmost substring that is matched by the regular expression.
--   Otherwise behaves like findLongestPrefix. Returns the result
--   together with the prefix and suffix of the string surrounding the
--   match.
findLongestInfix :: RE s a -> [s] -> Maybe ([s], a, [s])

-- | Find the leftmost substring that is matched by the regular expression.
--   Otherwise behaves like findShortestPrefix. Returns the result
--   together with the prefix and suffix of the string surrounding the
--   match.
findShortestInfix :: RE s a -> [s] -> Maybe ([s], a, [s])

-- | Find the first prefix, with the given uncons function.
findFirstPrefixWithUncons :: (ss -> Maybe (s, ss)) -> RE s a -> ss -> Maybe (a, ss)

-- | Find the longest prefix, with the given uncons function.
findLongestPrefixWithUncons :: (ss -> Maybe (s, ss)) -> RE s a -> ss -> Maybe (a, ss)

-- | Find the shortest prefix (analogous to findLongestPrefix), with
--   the given uncons function.
findShortestPrefixWithUncons :: (ss -> Maybe (s, ss)) -> RE s a -> ss -> Maybe (a, ss)

-- | Collection of commonly used regular expressions.
module Text.Regex.Applicative.Common

-- | Decimal digit, i.e. '0'..'9'
digit :: Num a => RE Char a

-- | Hexadecimal digit i.e. '0'..'9',
--   'a'..'f', 'A'..'F'.
hexDigit :: Num a => RE Char a

-- | Add optional sign
signed :: Num a => RE Char a -> RE Char a

-- | Parse decimal number without sign.
decimal :: Num a => RE Char a

-- | Parse decimal number without sign.
hexadecimal :: Num a => RE Char a
