-- 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.3


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

-- | <a>StateQueue</a> is a data structure that can efficiently insert
--   elements (preserving their order) and check whether an element with
--   the given <a>Int</a> 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 <a>insert</a> doesn't take a key, it won't affect any
--   <a>insertUnique</a>.
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.Show.Show a => GHC.Show.Show (Text.Regex.Applicative.StateQueue.StateQueue a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Text.Regex.Applicative.StateQueue.StateQueue a)
instance Data.Foldable.Foldable Text.Regex.Applicative.StateQueue.StateQueue


-- | 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
--   <tt><a>ReObject</a> s r</tt>, where <tt>s</tt> is the type of symbols
--   and <tt>r</tt> is the result type (as in the <a>RE</a> type). Think of
--   <a>ReObject</a> as a collection of <a>Thread</a>s ordered by priority.
--   E.g. threads generated by the left part of <a>&lt;|&gt;</a> 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 <a>step</a>.
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 <a>Nothing</a> 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 <a>Just</a> for ordinary
--   threads and <a>Nothing</a> 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
--   <a>stepThread</a> 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 <a>ReObject</a>, 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


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

-- | <a>reference</a> <tt>r</tt> <tt>s</tt> should give the same results as
--   <tt>s</tt> <tt>=~</tt> <tt>r</tt>.
--   
--   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.Base.Monad (Text.Regex.Applicative.Reference.P s)
instance GHC.Base.Functor (Text.Regex.Applicative.Reference.P s)
instance GHC.Base.Applicative (Text.Regex.Applicative.Reference.P s)
instance GHC.Base.Alternative (Text.Regex.Applicative.Reference.P s)


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

-- | Type of regular expressions that recognize symbols of type <tt>s</tt>
--   and produce a result of type <tt>a</tt>.
--   
--   Regular expressions can be built using <a>Functor</a>,
--   <a>Applicative</a> and <a>Alternative</a> instances in the following
--   natural way:
--   
--   <ul>
--   <li><tt>f</tt> <a>&lt;$&gt;</a> <tt>ra</tt> matches iff <tt>ra</tt>
--   matches, and its return value is the result of applying <tt>f</tt> to
--   the return value of <tt>ra</tt>.</li>
--   <li><a>pure</a> <tt>x</tt> matches the empty string (i.e. it does not
--   consume any symbols), and its return value is <tt>x</tt></li>
--   <li><tt>rf</tt> <a>&lt;*&gt;</a> <tt>ra</tt> matches a string iff it
--   is a concatenation of two strings: one matched by <tt>rf</tt> and the
--   other matched by <tt>ra</tt>. The return value is <tt>f a</tt>, where
--   <tt>f</tt> and <tt>a</tt> are the return values of <tt>rf</tt> and
--   <tt>ra</tt> respectively.</li>
--   <li><tt>ra</tt> <a>&lt;|&gt;</a> <tt>rb</tt> matches a string which is
--   accepted by either <tt>ra</tt> or <tt>rb</tt>. It is left-biased, so
--   if both can match, the result of <tt>ra</tt> is used.</li>
--   <li><a>empty</a> is a regular expression which does not match any
--   string.</li>
--   <li><a>many</a> <tt>ra</tt> matches concatenation of zero or more
--   strings matched by <tt>ra</tt> and returns the list of <tt>ra</tt>'s
--   return values on those strings.</li>
--   <li><a>some</a> <tt>ra</tt> matches concatenation of one or more
--   strings matched by <tt>ra</tt> and returns the list of <tt>ra</tt>'s
--   return values on those strings.</li>
--   </ul>
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 <a>psym</a>, 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 <a>IsString</a> instance for regular expression,
--   so if you enable the <tt>OverloadedStrings</tt> language extension,
--   you can write <tt>string "foo"</tt> simply as <tt>"foo"</tt>.
--   
--   Example:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   import Text.Regex.Applicative
--   
--   number = "one" *&gt; pure 1  &lt;|&gt;  "two" *&gt; pure 2
--   
--   main = print $ "two" =~ number
--   </pre>
string :: Eq a => [a] -> RE a [a]

-- | Match zero or more instances of the given expression, which are
--   combined using the given folding function.
--   
--   <a>Greediness</a> argument controls whether this regular expression
--   should match as many as possible (<a>Greedy</a>) or as few as possible
--   (<a>NonGreedy</a>) 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. <i>non-greedily</i>). A greedy equivalent of
--   <a>few</a> is <a>many</a>.
--   
--   Examples:
--   
--   <pre>
--   Text.Regex.Applicative&gt; findFirstPrefix (few anySym  &lt;* "b") "ababab"
--   Just ("a","abab")
--   Text.Regex.Applicative&gt; findFirstPrefix (many anySym  &lt;* "b") "ababab"
--   Just ("ababa","")
--   </pre>
few :: RE s a -> RE s [a]

-- | <a>RE</a> is a profunctor. This is its contravariant map.
--   
--   (A dependency on the <tt>profunctors</tt> 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:
--   
--   <pre>
--   Text.Regex.Applicative&gt; match (sym 'a' &lt;|&gt; sym 'b') "a"
--   Just 'a'
--   Text.Regex.Applicative&gt; match (sym 'a' &lt;|&gt; sym 'b') "ab"
--   Nothing
--   </pre>
match :: RE s a -> [s] -> Maybe a

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

-- | Replace matches of the regular expression with its value.
--   
--   <pre>
--   Text.Regex.Applicative &gt; replace ("!" &lt;$ sym 'f' &lt;* some (sym 'o')) "quuxfoofooooofoobarfobar"
--   "quux!!!bar!bar"
--   </pre>
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 <a>&lt;|&gt;</a> 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.
--   
--   Examples:
--   
--   <pre>
--   Text.Regex.Applicative&gt; findFirstPrefix ("a" &lt;|&gt; "ab") "abc"
--   Just ("a","bc")
--   Text.Regex.Applicative&gt; findFirstPrefix ("ab" &lt;|&gt; "a") "abc"
--   Just ("ab","c")
--   Text.Regex.Applicative&gt; findFirstPrefix "bc" "abc"
--   Nothing
--   </pre>
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.
--   
--   Examples:
--   
--   <pre>
--   Text.Regex.Applicative Data.Char&gt; let keyword = "if"
--   Text.Regex.Applicative Data.Char&gt; let identifier = many $ psym isAlpha
--   Text.Regex.Applicative Data.Char&gt; let lexeme = (Left &lt;$&gt; keyword) &lt;|&gt; (Right &lt;$&gt; identifier)
--   Text.Regex.Applicative Data.Char&gt; findLongestPrefix lexeme "if foo"
--   Just (Left "if"," foo")
--   Text.Regex.Applicative Data.Char&gt; findLongestPrefix lexeme "iffoo"
--   Just (Right "iffoo","")
--   </pre>
findLongestPrefix :: RE s a -> [s] -> Maybe (a, [s])

-- | Find the shortest prefix (analogous to <a>findLongestPrefix</a>)
findShortestPrefix :: RE s a -> [s] -> Maybe (a, [s])

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


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

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

-- | Hexadecimal digit i.e. <tt>'0'</tt>..<tt>'9'</tt>,
--   <tt>'a'</tt>..<tt>'f'</tt>, <tt>'A'</tt>..<tt>'F'</tt>.
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
