replace-megaparsec-1.4.5.0: Find, replace, and split string patterns with Megaparsec parsers (instead of regex)

Replace.Megaparsec

Contents

Description

Replace.Megaparsec is for finding text patterns, and also replacing or splitting on 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.

Replace.Megaparsec can be used in the same sort of “string splitting” situations in which one would use Python re.split or Perl split.

See the replace-megaparsec package README for usage examples.

## Type constraints

### output stream type Tokens s = input stream type s

All functions in the Running Parser section require the type of the stream of text that is input to 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:

### Custom error type e should be Void

Megaparsec parsers have a custom error data component e. When writing parsers to be used by this module, the custom error type e should usually be Void, 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.

## Special fast input types

Functions in this module will be “fast” when the input stream type s is:

We mean “fast” in the same sense as MonadParsec: 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.

Synopsis

# Running parser

Functions in this section are ways to run parsers (like runParser). They take as arguments a sep parser and some input, run the parser on the input, and return a result.

Arguments

 :: forall e s a. (Ord e, Stream s, Tokens s ~ s) => Parsec e s a The pattern matching parser sep -> s The input stream of text -> Maybe (s, a, s) Maybe (prefix, parse_result, suffix)

### 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


Arguments

 :: forall m e s a. (Ord e, Stream s, Tokens s ~ s, Monad m) => ParsecT e s m a The pattern matching parser sep -> s The input stream of text -> m (Maybe (s, a, s)) Maybe (prefix, parse_result, suffix)

### Break on and capture one pattern

Monad transformer version of breakCap.

The parser sep will run in the underlying monad context.

Arguments

 :: forall e s a. (Ord e, Stream s, Tokens s ~ s) => Parsec e s a The pattern matching parser sep -> s The input stream of text -> [Either s a] List of matching and non-matching input sections.

### 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

### 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)


Arguments

 :: MonadParsec e s m => m a The pattern matching parser sep -> m [Either (Tokens s) (Tokens s, a)] parser

Deprecated: replace with findAllCap sep = 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)