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


-- | regex-applicative on text
--   
--   Wrapped regex-applicative primitives to work with Text
@package regex-applicative-text
@version 0.1.0.1


-- | <tt>Text.Regex.Applicative</tt> API specialised to <a>Char</a> and
--   <a>Text</a>.
module Text.Regex.Applicative.Text

-- | Convenience alias for <tt>RE</tt> working (also) on <a>Text</a>.
type RE' a = RE Char a
data RE s a

-- | Match and return the given symbol
sym :: Char -> RE' Char

-- | Match and return a single <a>Char</a> which satisfies the predicate
psym :: (Char -> Bool) -> RE' Char

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

-- | Match and return any single symbol
anySym :: RE' Char

-- | Match and return the given <a>Text</a>.
--   
--   <pre>
--   import Text.Regex.Applicative
--   
--   number = string "one" *&gt; pure 1 &lt;|&gt; string "two" *&gt; pure 2
--   
--   main = print $ "two" =~ number
--   </pre>
string :: Text -> RE' Text

-- | Match zero or more instances of the given expression, which are
--   combined using the given folding function.
--   
--   <tt>Greediness</tt> argument controls whether this regular expression
--   should match as many as possible (<tt>Greedy</tt>) or as few as
--   possible (<tt>NonGreedy</tt>) instances of the underlying expression.
reFoldl :: Greediness -> (b -> a -> b) -> b -> RE' a -> RE' 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>.x
--   
--   <pre>
--   &gt;&gt;&gt; findFirstPrefix (few anySym  &lt;* "b") "ababab"
--   Just ("a","abab")
--   &gt;&gt;&gt; findFirstPrefix (many anySym  &lt;* "b") "ababab"
--   Just ("ababa","")
--   </pre>
few :: RE' a -> RE' [a]

-- | Return matched symbols as part of the return value
withMatched :: RE' a -> RE' (a, Text)

-- | Attempt to match a <a>Text</a> against the regular expression. Note
--   that the whole string (not just some part of it) should be matched.
--   
--   <pre>
--   &gt;&gt;&gt; match (sym 'a' &lt;|&gt; sym 'b') "a"
--   Just 'a'
--   &gt;&gt;&gt; match (sym 'a' &lt;|&gt; sym 'b') "ab"
--   Nothing
--   </pre>
match :: RE' a -> Text -> Maybe a

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

-- | Replace matches of regular expression with it's value.
--   
--   <pre>
--   &gt;&gt;&gt; replace ("!" &lt;$ sym 'f' &lt;* some (sym 'o')) "quuxfoofooooofoobarfobar"
--   "quux!!!bar!bar"
--   </pre>
replace :: RE' Text -> Text -> Text

-- | 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.
--   
--   <pre>
--   &gt;&gt;&gt; findFirstPrefix ("a" &lt;|&gt; "ab") "abc"
--   Just ("a","bc")
--   &gt;&gt;&gt; findFirstPrefix ("ab" &lt;|&gt; "a") "abc"
--   Just ("ab","c")
--   &gt;&gt;&gt; findFirstPrefix "bc" "abc"
--   Nothing
--   </pre>
findFirstPrefix :: RE' a -> Text -> Maybe (a, Text)

-- | 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.
--   
--   <pre>
--   &gt;&gt;&gt; let keyword = "if"
--   &gt;&gt;&gt; let identifier = many $ psym isAlpha
--   &gt;&gt;&gt; let lexeme = (Left &lt;$&gt; keyword) &lt;|&gt; (Right &lt;$&gt; identifier)
--   &gt;&gt;&gt; findLongestPrefix lexeme "if foo"
--   Just (Left "if"," foo")
--   &gt;&gt;&gt; findLongestPrefix lexeme "iffoo"
--   Just (Right "iffoo","")
--   </pre>
findLongestPrefix :: RE' a -> Text -> Maybe (a, Text)

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

-- | 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' a -> Text -> Maybe (Text, a, Text)

-- | 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' a -> Text -> Maybe (Text, a, Text)

-- | 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' a -> Text -> Maybe (Text, a, Text)
