-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Find, replace, and edit text patterns with Attoparsec parsers (instead of regex)
--
-- Find text patterns, and also edit or replace the found patterns. Use
-- Attoparsec monadic parsers instead of regular expressions for pattern
-- matching.
@package replace-attoparsec
@version 1.2.2.0
-- | Replace.Attoparsec is for finding text patterns, and also
-- editing and replacing the found patterns. This activity is
-- traditionally done with regular expressions, but
-- Replace.Attoparsec uses Data.Attoparsec parsers instead
-- for the pattern matching.
--
-- Replace.Attoparsec 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.Attoparsec 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-attoparsec package README for usage
-- examples.
module Replace.Attoparsec.ByteString
-- | Separate and capture
--
-- Parser combinator to find all of the non-overlapping ocurrences of the
-- pattern sep in a text stream. The sepCap parser will
-- always consume its entire input and can never fail.
--
-- Output
--
-- The input stream is separated and output into a list of sections:
--
--
-- - Sections which can parsed by the pattern sep will be
-- parsed and captured as Right
-- - Non-matching sections of the stream will be captured in
-- Left.
--
--
-- The output list also has these properties:
--
--
-- - If the input is "" then the output list will be
-- [].
-- - If there are no pattern matches, then the entire input stream will
-- be returned as one non-matching Left section.
-- - The output list will not contain two consecutive Left
-- sections.
--
--
-- Zero-width matches forbidden
--
-- If the pattern matching parser sep would succeed without
-- consuming any input then sepCap will force it to fail. If we
-- allow sep 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.
--
-- Notes
--
-- 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, like manyTill_.
sepCap :: Parser a -> Parser [Either ByteString 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 :: Parser a -> Parser [Either ByteString ByteString]
-- | 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 :: Parser a -> Parser [Either ByteString (ByteString, 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 parseOnly.
--
-- 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 (ByteString,a) -> ByteString.
--
-- 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 returns the first item in the tuple, then
-- streamEdit will not change the matched string.
--
-- So, for all sep:
--
--
-- streamEdit (match sep) fst ≡ id
--
streamEdit :: Parser a -> (a -> ByteString) -> ByteString -> ByteString
-- | Stream editor transformer
--
-- Monad transformer version of streamEdit.
--
-- The editor function will run in the underlying monad context.
--
-- If you want to do IO operations in the editor function
-- then run this in IO.
--
-- If you want the editor function to remember some state, then
-- run this in a stateful monad.
streamEditT :: Monad m => Parser a -> (a -> m ByteString) -> ByteString -> m ByteString
-- | Replace.Attoparsec is for finding text patterns, and also
-- editing and replacing the found patterns. This activity is
-- traditionally done with regular expressions, but
-- Replace.Attoparsec uses Data.Attoparsec parsers instead
-- for the pattern matching.
--
-- Replace.Attoparsec 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.Attoparsec 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-attoparsec package README for usage
-- examples.
module Replace.Attoparsec.Text
-- | Separate and capture
--
-- Parser combinator to find all of the non-overlapping ocurrences of the
-- pattern sep in a text stream. The sepCap parser will
-- always consume its entire input and can never fail.
--
-- Output
--
-- The input stream is separated and output into a list of sections:
--
--
-- - Sections which can parsed by the pattern sep will be
-- parsed and captured as Right
-- - Non-matching sections of the stream will be captured in
-- Left.
--
--
-- The output list also has these properties:
--
--
-- - If the input is "" then the output list will be
-- [].
-- - If there are no pattern matches, then the entire input stream will
-- be returned as one non-matching Left section.
-- - The output list will not contain two consecutive Left
-- sections.
--
--
-- Zero-width matches forbidden
--
-- If the pattern matching parser sep would succeed without
-- consuming any input then sepCap will force it to fail. If we
-- allow sep 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.
--
-- Notes
--
-- 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, like manyTill_.
sepCap :: Parser a -> Parser [Either Text 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 :: Parser a -> Parser [Either Text Text]
-- | 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 :: Parser a -> Parser [Either Text (Text, 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 parseOnly.
--
-- 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 (Text,a) -> Text.
--
-- 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 returns the first item in the tuple, then
-- streamEdit will not change the matched string.
--
-- So, for all sep:
--
--
-- streamEdit (match sep) fst ≡ id
--
streamEdit :: Parser a -> (a -> Text) -> Text -> Text
-- | Stream editor transformer
--
-- Monad transformer version of streamEdit.
--
-- The editor function will run in the underlying monad context.
--
-- If you want to do IO operations in the editor function
-- then run this in IO.
--
-- If you want the editor function to remember some state, then
-- run this in a stateful monad.
streamEditT :: Monad m => Parser a -> (a -> m Text) -> Text -> m Text