-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Stream edit, find-and-replace with Attoparsec parsers
--
-- Stream editing and find-and-replace with Attoparsec monadic parsers.
@package replace-attoparsec
@version 1.0.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. 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 digit, which can match zero occurences of a
-- digit, will be treated by sepCap as many1 digit, 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 :: 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 always returns the first item in the tuple,
-- then streamEdit changes nothing.
--
-- 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
-- | Get the Parser ’s current offset position in the stream.
--
-- “… you know you're in an uncomfortable state of sin :-)” — bos
getOffset :: Parser Int
-- | 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. 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 digit, which can match zero occurences of a
-- digit, will be treated by sepCap as many1 digit, 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 :: 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 always returns the first item in the tuple,
-- then streamEdit changes nothing.
--
-- 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
-- | Get the Parser ’s current offset position in the stream.
--
-- “… you know you're in an uncomfortable state of sin :-)” — bos
getOffset :: Parser Int