-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Find, replace, and edit text patterns with Megaparsec parsers
--
-- Find text patterns, and also edit or replace the found patterns. Use
-- Megaparsec monadic parsers instead of regular expressions for pattern
-- matching.
@package replace-megaparsec
@version 1.2.0.0
-- | This internal module is for ByteString specializations.
--
-- The functions in this module are supposed to be chosen automatically
-- by rewrite rules in the Replace.Megaparsec module, so you
-- should never need to import this module.
module Replace.Megaparsec.Internal.ByteString
sepCapByteString :: forall e s m a. (MonadParsec e s m, s ~ ByteString) => m a -> m [Either (Tokens s) a]
-- | This internal module is for Text specializations.
--
-- The functions in this module are supposed to be chosen automatically
-- by rewrite rules in the Replace.Megaparsec module, so you
-- should never need to import this module.
module Replace.Megaparsec.Internal.Text
sepCapText :: forall e s m a. (MonadParsec e s m, s ~ Text) => m a -> m [Either (Tokens s) a]
-- | Replace.Megaparsec is for finding text patterns, and also
-- editing and replacing the found patterns. This activity is
-- traditionally done with regular expressions, but
-- Replace.Megaparsec uses Text.Megaparsec parsers instead
-- for the pattern matching.
--
-- Replace.Megaparsec can be used in the same sort of “pattern
-- capture” or “find all” situations in which one would use Python
-- re.findall, or Perl m//, or Unix grep.
--
-- Replace.Megaparsec can be used in the same sort of “stream
-- editing” or “search-and-replace” situations in which one would use
-- Python re.sub, or Perl s///, or Unix sed, or
-- awk.
--
-- See the replace-megaparsec package README for usage examples.
module Replace.Megaparsec
-- | Separate and capture
--
-- Parser combinator to find all of the non-overlapping ocurrences of the
-- pattern sep in a text stream. Separate the stream into
-- sections:
--
--
-- - sections which can parsed by the pattern sep will be
-- captured as matching sections in Right
-- - non-matching sections of the stream will be captured in
-- Left.
--
--
-- This parser will always consume its entire input and can never fail.
-- If there are no pattern matches, then the entire input stream will be
-- returned as a non-matching Left section.
--
-- The pattern matching parser sep will not be allowed to
-- succeed without consuming any input. If we allow the parser 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. So, for example,
-- the pattern many digitChar, which can match zero occurences
-- of a digit, will be treated by sepCap as some
-- digitChar, and required to match at least one digit.
--
-- This sepCap parser combinator is the basis for all of the
-- other features of this module. It is similar to the sep*
-- family of functions found in parser-combinators and
-- parsers but, importantly, it returns the parsed result of the
-- sep parser instead of throwing it away.
sepCap :: forall e s m a. MonadParsec e s m => m a -> m [Either (Tokens s) a]
-- | Find all occurences
--
-- Parser combinator for finding all occurences of a pattern in a stream.
--
-- Will call sepCap with the match combinator and return
-- the text which matched the pattern parser sep in the
-- Right sections.
--
-- Definition:
--
--
-- findAll sep = (fmap.fmap) (second fst) $ sepCap (match sep)
--
findAll :: MonadParsec e s m => m a -> m [Either (Tokens s) (Tokens s)]
-- | Find all occurences, parse and capture pattern matches
--
-- Parser combinator for finding all occurences of a pattern in a stream.
--
-- Will call sepCap with the match combinator so that the
-- text which matched the pattern parser sep will be returned in
-- the Right sections, along with the result of the parse of
-- sep.
--
-- Definition:
--
--
-- findAllCap sep = sepCap (match sep)
--
findAllCap :: MonadParsec e s m => m a -> m [Either (Tokens s) (Tokens s, a)]
-- | Stream editor
--
-- Also known as “find-and-replace”, or “match-and-substitute”. Finds all
-- of the sections of the stream which match the pattern sep,
-- and replaces them with the result of the editor function.
--
-- This function is not a “parser combinator,” it is a “way to run a
-- parser”, like parse or runParserT.
--
-- Access the matched section of text in the editor
--
-- If you want access to the matched string in the editor
-- function, then combine the pattern parser sep with
-- match. This will effectively change the type of the
-- editor function to (s,a) -> s.
--
-- This allows us to write an editor function which can choose
-- to not edit the match and just leave it as it is. If the
-- editor function always returns the first item in the tuple,
-- then streamEdit changes nothing.
--
-- So, for all sep:
--
--
-- streamEdit (match sep) fst ≡ id
--
--
-- Type constraints
--
-- The type of the stream of text that is input must be Stream s
-- such that Tokens s ~ s, because we want to output the same
-- type of stream that was input. That requirement is satisfied for all
-- the Stream instances included with Text.Megaparsec:
-- Data.Text, Data.Text.Lazy, Data.Bytestring,
-- Data.Bytestring.Lazy, and Data.String.
--
-- We need the Monoid s instance so that we can mconcat
-- the output stream.
--
-- We need Typeable s and Show s for throw. In
-- theory this function should never throw an exception, because it only
-- throws when the sepCap parser fails, and the sepCap
-- parser can never fail. If this function ever throws, please report
-- that as a bug.
streamEdit :: forall s a. (Stream s, Monoid s, Tokens s ~ s, Show s, Show (Token s), Typeable s) => Parsec Void s a -> (a -> s) -> s -> s
-- | Stream editor transformer
--
-- Monad transformer version of streamEdit.
--
-- Both the parser sep and the editor function run in
-- the underlying monad context.
--
-- If you want to do IO operations in the editor function
-- or the parser sep, then run this in IO.
--
-- If you want the editor function or the parser sep to
-- remember some state, then run this in a stateful monad.
streamEditT :: forall s m a. (Stream s, Monad m, Monoid s, Tokens s ~ s, Show s, Show (Token s), Typeable s) => ParsecT Void s m a -> (a -> m s) -> s -> m s