Module

Text.Parsing.Replace.String

Finding, splitting, and replacing Strings with Text.Parsing.Parser.String instead of Data.String.Regex.

Functions in this module are ways to run a parser on a String, like runParser or runParserT.

Note that these parser runners only accept the type String, not any instance of the StringLike class.

See the package README for usage examples.

#breakCap

breakCap :: forall a. Parser String a -> String -> Maybe (T3 String a String)

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.

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²).

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

#breakCapT

breakCapT :: forall m a. Monad m => MonadRec m => ParserT String m a -> String -> m (Maybe (T3 String a String))

Monad transformer version of breakCap. The sep parser will run in the monad context.

#splitCap

splitCap :: forall a. Parser String a -> String -> NonEmptyList (Either String a)

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.

Access the matched section of text

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

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

let output = splitCap (match sep) input

then

input == fold (either identity fst <$> output)

(This invariant might not hold if sep can succeed without consuming any input, like if sep is a lookAhead parser.)

#splitCapT

splitCapT :: forall m a. Monad m => MonadRec m => ParserT String m a -> String -> m (NonEmptyList (Either String a))

Monad transformer version of splitCap. The sep parser will run in the monad context. Not stack-safe.

#streamEdit

streamEdit :: forall a. Parser String a -> (a -> String) -> String -> String

Stream editor

Also known as “find-and-replace”, or “match-and-substitute”. Find all of the leftmost non-overlapping sections of the input string which match the pattern sep, and replace 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 (String /\ a) -> String.

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 ≡ identity

(This invariant might not hold if sep can succeed without consuming any input, like if sep is a lookAhead parser.)

#streamEditT

streamEditT :: forall m a. Monad m => MonadRec m => ParserT String m a -> (a -> m String) -> String -> m String

Monad transformer version of streamEdit. The sep parser and the editor function will both run in the monad context. Not stack-safe.

Re-exports from Text.Parsing.Replace.String.Combinator

#match

match :: forall m a. Monad m => ParserT String m a -> ParserT String m (Tuple String a)

The famous match combinator.

Return both the result of a parse and the portion of the input that was consumed while it was being parsed.

Note that this combinator only accepts the type String, not any instance of the StringLike class.

#anyTill

anyTill :: forall m a. Monad m => MonadRec m => ParserT String m a -> ParserT String m (Tuple String a)

Find the first place in the input where the phrase can parse. Returns both the parsed result and the unparsable input section consumed before the parse. Will fail if no section of the input is parseable. Will not consume input on failure. Stack-safe.

This combinator is equivalent to manyTill_ anyChar, but it will be faster because it returns a slice of the input String for the section preceding the match instead of a List Char.

Note that this combinator only accepts the type String, not any instance of the StringLike class.

Modules