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

-- | 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 :: 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)
