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


-- | Find text patterns, replace the patterns, split on the patterns. Use
--   Megaparsec monadic parsers instead of regular expressions for pattern
--   matching.
@package replace-megaparsec
@version 1.5.0.1


-- | This internal module is for <a>ByteString</a> specializations.
--   
--   The functions in this module are intended to be chosen automatically
--   by rewrite rules in the <a>Replace.Megaparsec</a> module, so you
--   should never need to import this module.
--   
--   Names in this module may change without a major version increment.
module Replace.Megaparsec.Internal.ByteString
sepCapByteString :: (MonadParsec e s m, s ~ ByteString) => m a -> m [Either (Tokens s) a]
anyTillByteString :: (MonadParsec e s m, s ~ ByteString) => m a -> m (Tokens s, a)


-- | This internal module is for <a>Text</a> specializations.
--   
--   The functions in this module are intended to be chosen automatically
--   by rewrite rules in the <a>Replace.Megaparsec</a> module, so you
--   should never need to import this module.
--   
--   Names in this module may change without a major version increment.
module Replace.Megaparsec.Internal.Text
sepCapText :: (MonadParsec e s m, s ~ Text) => m a -> m [Either (Tokens s) a]
anyTillText :: (MonadParsec e s m, s ~ Text) => m a -> m (Tokens s, a)


-- | <b>Replace.Megaparsec</b> is for finding text patterns, and also
--   replacing or splitting on the found patterns. This activity is
--   traditionally done with regular expressions, but
--   <b>Replace.Megaparsec</b> uses <a>Text.Megaparsec</a> parsers instead
--   for the pattern matching.
--   
--   <b>Replace.Megaparsec</b> can be used in the same sort of “pattern
--   capture” or “find all” situations in which one would use Python
--   <a>re.findall</a>, or Perl <a>m//</a>, or Unix <a>grep</a>.
--   
--   <b>Replace.Megaparsec</b> can be used in the same sort of “stream
--   editing” or “search-and-replace” situations in which one would use
--   Python <a>re.sub</a>, or Perl <a>s///</a>, or Unix <a>sed</a>, or
--   <a>awk</a>.
--   
--   <b>Replace.Megaparsec</b> can be used in the same sort of “string
--   splitting” situations in which one would use Python <a>re.split</a> or
--   Perl <a>split</a>.
--   
--   See the <b>replace-megaparsec</b> package README for usage examples.
--   
--   <h2>Type constraints</h2>
--   
--   <h3>output stream type <tt>Tokens s</tt> = input stream type
--   <tt>s</tt></h3>
--   
--   All functions in the <b>Running Parser</b> section require the type of
--   the stream of text that is input to be <tt><a>Stream</a> s</tt> such
--   that <tt><a>Tokens</a> s ~ s</tt>, because we want to output the same
--   type of stream that was input. That requirement is satisfied for all
--   the <a>Stream</a> instances included with <a>Text.Megaparsec</a>:
--   
--   <ul>
--   <li><a>Data.String</a></li>
--   <li><a>Data.Text</a></li>
--   <li><a>Data.Text.Lazy</a></li>
--   <li><a>Data.ByteString</a></li>
--   <li><a>Data.ByteString.Lazy</a></li>
--   </ul>
--   
--   <h3>Custom error type <tt>e</tt> should be <a>Void</a></h3>
--   
--   Megaparsec parsers have a custom error data component <tt>e</tt>. When
--   writing parsers to be used by this module, the custom error type
--   <tt>e</tt> should usually be <a>Void</a>, because every function in
--   this module expects a parser failure to occur on every token in a
--   non-matching section of the input stream, so parser failure error
--   descriptions are not returned, and you'll never see the custom error
--   information.
--   
--   <h2>Special fast input types</h2>
--   
--   Functions in this module will be “fast” when the input stream type
--   <tt>s</tt> is:
--   
--   <ul>
--   <li><a>Data.Text</a></li>
--   <li><a>Data.ByteString</a></li>
--   </ul>
--   
--   We mean “fast” in the same sense as <a>MonadParsec</a>: when returning
--   subsections of the input stream, we return slices of the input stream
--   data, rather than constructing a list of tokens and then building a
--   new stream subsection from that list. This relies on implementation
--   details of the stream representation, so there are specialization
--   re-write rules in this module to make that possible without adding new
--   typeclasses.
module Replace.Megaparsec

-- | <h3>Break on and capture one pattern</h3>
--   
--   Find the first occurence of a pattern in a text stream, capture the
--   found pattern, and break the input text stream on the found pattern.
--   
--   The <a>breakCap</a> function is like <a>takeWhile</a>, but can be
--   predicated beyond more than just the next one token. It's also like
--   <a>breakOn</a>, but the <tt>needle</tt> can be a pattern instead of a
--   constant string.
--   
--   Be careful not to look too far ahead; if the <tt>sep</tt> parser looks
--   to the end of the input then <a>breakCap</a> could be <i>O(n²)</i>.
--   
--   The pattern parser <tt>sep</tt> may match a zero-width pattern (a
--   pattern which consumes no parser input on success).
--   
--   <h4>Output</h4>
--   
--   <ul>
--   <li><tt>Nothing</tt> when no pattern match was found.</li>
--   <li><tt>Just (prefix, parse_result, suffix)</tt> for the result of
--   parsing the pattern match, and the <tt>prefix</tt> string before and
--   the <tt>suffix</tt> string after the pattern match. <tt>prefix</tt>
--   and <tt>suffix</tt> may be zero-length strings.</li>
--   </ul>
--   
--   <h4>Access the matched section of text</h4>
--   
--   If you want to capture the matched string, then combine the pattern
--   parser <tt>sep</tt> with <a>match</a>.
--   
--   With the matched string, we can reconstruct the input string. For all
--   <tt>input</tt>, <tt>sep</tt>, if
--   
--   <pre>
--   let (<a>Just</a> (prefix, (infix, _), suffix)) = breakCap (<a>match</a> sep) input
--   </pre>
--   
--   then
--   
--   <pre>
--   input == prefix <a>&lt;&gt;</a> infix <a>&lt;&gt;</a> suffix
--   </pre>
breakCap :: (Ord e, Stream s, Tokens s ~ s) => Parsec e s a -> s -> Maybe (s, a, s)

-- | <h3>Break on and capture one pattern</h3>
--   
--   Monad transformer version of <a>breakCap</a>.
--   
--   The parser <tt>sep</tt> will run in the underlying monad context.
breakCapT :: forall m e s a. (Ord e, Stream s, Tokens s ~ s, Monad m) => ParsecT e s m a -> s -> m (Maybe (s, a, s))

-- | <h3>Split on and capture all patterns</h3>
--   
--   Find all occurences of the pattern <tt>sep</tt>, split the input
--   string, capture all the patterns and the splits.
--   
--   The input string will be split on every leftmost non-overlapping
--   occurence of the pattern <tt>sep</tt>. The output list will contain
--   the parsed result of input string sections which match the
--   <tt>sep</tt> pattern in <a>Right</a>, and non-matching sections in
--   <a>Left</a>.
--   
--   <a>splitCap</a> depends on <a>sepCap</a>, see <a>sepCap</a> for more
--   details.
--   
--   <h4>Access the matched section of text</h4>
--   
--   If you want to capture the matched strings, then combine the pattern
--   parser <tt>sep</tt> with <a>match</a>.
--   
--   With the matched strings, we can reconstruct the input string. For all
--   <tt>input</tt>, <tt>sep</tt>, if
--   
--   <pre>
--   let output = splitCap (<a>match</a> sep) input
--   </pre>
--   
--   then
--   
--   <pre>
--   input == <a>mconcat</a> (<a>second</a> <a>fst</a> <a>&lt;$&gt;</a> output)
--   </pre>
splitCap :: (Ord e, Stream s, Tokens s ~ s) => Parsec e s a -> s -> [Either s a]

-- | <h3>Split on and capture all patterns</h3>
--   
--   Monad transformer version of <a>splitCap</a>.
--   
--   The parser <tt>sep</tt> will run in the underlying monad context.
splitCapT :: (Ord e, Stream s, Tokens s ~ s, Monad m) => ParsecT e s m a -> s -> m [Either s a]

-- | <h3>Stream editor</h3>
--   
--   Also known as “find-and-replace”, or “match-and-substitute”. Finds all
--   non-overlapping sections of the stream which match the pattern
--   <tt>sep</tt>, and replaces them with the result of the <tt>editor</tt>
--   function.
--   
--   <h4>Access the matched section of text in the <tt>editor</tt></h4>
--   
--   If you want access to the matched string in the <tt>editor</tt>
--   function, then combine the pattern parser <tt>sep</tt> with
--   <a>match</a>. This will effectively change the type of the
--   <tt>editor</tt> function to <tt>(s,a) -&gt; s</tt>.
--   
--   This allows us to write an <tt>editor</tt> function which can choose
--   to not edit the match and just leave it as it is. If the
--   <tt>editor</tt> function returns the first item in the tuple, then
--   <tt>streamEdit</tt> will not change the matched string.
--   
--   So, for all <tt>sep</tt>:
--   
--   <pre>
--   streamEdit (<a>match</a> sep) <a>fst</a> ≡ <a>id</a>
--   </pre>
streamEdit :: (Ord e, Stream s, Monoid s, Tokens s ~ s) => Parsec e s a -> (a -> s) -> s -> s

-- | <h3>Stream editor</h3>
--   
--   Monad transformer version of <a>streamEdit</a>.
--   
--   Both the parser <tt>sep</tt> and the <tt>editor</tt> function will run
--   in the underlying monad context.
--   
--   If you want to do <a>IO</a> operations in the <tt>editor</tt> function
--   or the parser <tt>sep</tt>, then run this in <a>IO</a>.
--   
--   If you want the <tt>editor</tt> function or the parser <tt>sep</tt> to
--   remember some state, then run this in a stateful monad.
streamEditT :: (Ord e, Stream s, Monad m, Monoid s, Tokens s ~ s) => ParsecT e s m a -> (a -> m s) -> s -> m s

-- | <h3>Specialized <a>manyTill_</a></h3>
--   
--   Parser combinator to consume input until the <tt>sep</tt> pattern
--   matches, equivalent to <tt><a>manyTill_</a> <a>anySingle</a> sep</tt>.
--   On success, returns the prefix before the pattern match and the parsed
--   match.
--   
--   <tt>sep</tt> may be a zero-width parser, it may succeed without
--   consuming any input.
--   
--   This combinator will produce a parser which acts like
--   <a>takeWhileP</a> but is predicated beyond more than just the next one
--   token. <a>anyTill</a> is also like <a>takeWhileP</a> in that it will
--   be “fast” when applied to an input stream type <tt>s</tt> for which
--   there are specialization re-write rules.
anyTill :: MonadParsec e s m => m a -> m (Tokens s, a)

-- | <h3>Separate and capture</h3>
--   
--   Parser combinator to find all of the leftmost non-overlapping
--   occurrences of the pattern parser <tt>sep</tt> in a text stream. The
--   <a>sepCap</a> parser will always consume its entire input and can
--   never fail.
--   
--   <tt>sepCap</tt> is similar to the <tt>sep*</tt> family of parser
--   combinators found in <a>parser-combinators</a> and <a>parsers</a>, but
--   it returns the parsed result of the <tt>sep</tt> parser instead of
--   throwing it away.
--   
--   <h4>Output</h4>
--   
--   The input stream is separated and output into a list of sections:
--   
--   <ul>
--   <li>Sections which can parsed by the pattern <tt>sep</tt> will be
--   parsed and captured as <a>Right</a>.</li>
--   <li>Non-matching sections of the stream will be captured in
--   <a>Left</a>.</li>
--   </ul>
--   
--   The output list also has these properties:
--   
--   <ul>
--   <li>If the input is <tt>""</tt> then the output list will be
--   <tt>[]</tt>.</li>
--   <li>If there are no pattern matches, then the entire input stream will
--   be returned as one non-matching <a>Left</a> section.</li>
--   <li>The output list will not contain two consecutive <a>Left</a>
--   sections.</li>
--   </ul>
--   
--   <h4>Zero-width matches forbidden</h4>
--   
--   If the pattern matching parser <tt>sep</tt> would succeed without
--   consuming any input then <a>sepCap</a> will force it to fail. If we
--   allow <tt>sep</tt> to match a zero-width pattern, then it can match
--   the same zero-width pattern again at the same position on the next
--   iteration, which would result in an infinite number of overlapping
--   pattern matches.
sepCap :: MonadParsec e s m => m a -> m [Either (Tokens s) a]

-- | <h3>Find all occurences</h3>
--   
--   Parser combinator for finding all occurences of a pattern in a stream.
--   
--   Will call <a>sepCap</a> with the <a>match</a> combinator and return
--   the text which matched the pattern parser <tt>sep</tt> in the
--   <a>Right</a> sections.
--   
--   Definition:
--   
--   <pre>
--   findAll sep = (fmap.fmap) (<a>second</a> fst) $ <a>sepCap</a> (<a>match</a> sep)
--   </pre>

-- | <i>Deprecated: replace with `findAll sep = (fmap.fmap) (second fst) $
--   sepCap (match sep)`</i>
findAll :: MonadParsec e s m => m a -> m [Either (Tokens s) (Tokens s)]

-- | <h3>Find all occurences, parse and capture pattern matches</h3>
--   
--   Parser combinator for finding all occurences of a pattern in a stream.
--   
--   Will call <a>sepCap</a> with the <a>match</a> combinator so that the
--   text which matched the pattern parser <tt>sep</tt> will be returned in
--   the <a>Right</a> sections, along with the result of the parse of
--   <tt>sep</tt>.
--   
--   Definition:
--   
--   <pre>
--   findAllCap sep = <a>sepCap</a> (<a>match</a> sep)
--   </pre>

-- | <i>Deprecated: replace with `findAllCap sep = sepCap (match sep)`</i>
findAllCap :: MonadParsec e s m => m a -> m [Either (Tokens s) (Tokens s, a)]
