Break on and capture one pattern

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 breakCap function is like takeWhile, but can be predicated beyond more than just the next one token. It's also like breakOn, but the needle can be a pattern instead of a constant string.

Be careful not to look too far ahead; if the sep parser looks to the end of the input then breakCap could be O(n²).

The pattern parser sep may match a zero-width pattern (a pattern which consumes no parser input on success).

Output

• Nothing when no pattern match was found.
• Just (prefix, parse_result, suffix) for the result of parsing the pattern match, and the prefix string before and the suffix string after the pattern match. prefix and suffix may be zero-length strings.

Access the matched section of text

If you want to capture the matched string, then combine the pattern parser sep with match.

With the matched string, we can reconstruct the input string. For all input, sep, if

let (Just (prefix, (infix, _), suffix)) = breakCap (match sep) input

then

input == prefix <> infix <> suffix

Split on and capture all patterns

Find all occurences of the pattern sep, 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 sep. The output list will contain the parsed result of input string sections which match the sep pattern in Right, and non-matching sections in Left.

splitCap depends on sepCap, see sepCap for more details.

Access the matched section of text

If you want to capture the matched strings, then combine the pattern parser sep with match.

With the matched strings, we can reconstruct the input string. For all input, sep, if

let output = splitCap (match sep) input

then

input == mconcat (second fst <$> output)

Stream editor

Also known as “find-and-replace”, or “match-and-substitute”. Finds all non-overlapping sections of the stream which match the pattern sep, and replaces them with the result of the editor function.

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 returns the first item in the tuple, then streamEdit will not change the matched string.

So, for all sep:

streamEdit (match sep) fst ≡ id

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.

Specialized manyTill_

Parser combinator to consume input until the sep pattern matches, equivalent to manyTill_ anySingle sep. On success, returns the prefix before the pattern match and the parsed match.

sep may be a zero-width parser, it may succeed without consuming any input.

This combinator will produce a parser which acts like takeWhileP but is predicated beyond more than just the next one token. anyTill is also like takeWhileP in that it will be “fast” when applied to an input stream type s for which there are specialization re-write rules.

Separate and capture

Parser combinator to find all of the leftmost non-overlapping occurrences of the pattern parser sep in a text stream. The sepCap parser will always consume its entire input and can never fail.

sepCap is similar to the sep* family of parser combinators found in parser-combinators and parsers, but it returns the parsed result of the sep parser instead of throwing it away.

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.

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)

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)