Text.RE.Replace

The Replacing Tutorial

This API module covers the specialised regex tools for doing general editing on text, including the internal details of the Matches and Match types and the associated functions for extracting captures and applying functions to them to transform the subject text.

See the tutorials at http://re-tutorial-replacing.regex.uk

replaceAll

replaceAll :: Replace a => a -> Matches a -> a

replace all with a template, $0 for whole text, $1 for first capture, etc.

replaceAllCaptures :: Replace a => REContext -> (Match a -> RELocation -> Capture a -> Maybe a) -> Matches a -> a

substitutes using a function that takes the full Match context and returns the same replacement text as the _phi_phi context.

replaceAllCaptures_ :: Extract a => ReplaceMethods a -> REContext -> (Match a -> RELocation -> Capture a -> Maybe a) -> Matches a -> a

replaceAllCaptures_ is like like replaceAllCaptures but takes the Replace methods through the ReplaceMethods argument

replaceAllCapturesM :: (Extract a, Monad m) => ReplaceMethods a -> REContext -> (Match a -> RELocation -> Capture a -> m (Maybe a)) -> Matches a -> m a

replaceAllCapturesM is just a monadically generalised version of replaceAllCaptures_

replace

replace :: Replace a => a -> Match a -> a

replaceCaptures :: Replace a => REContext -> (Match a -> RELocation -> Capture a -> Maybe a) -> Match a -> a

substitutes using a function that takes the full Match context and returns the same replacement text as the _phi_phi context.

replaceCaptures_ :: Extract a => ReplaceMethods a -> REContext -> (Match a -> RELocation -> Capture a -> Maybe a) -> Match a -> a

replaceCaptures_ is like replaceCaptures but takes the Replace methods through the ReplaceMethods argument

replaceCapturesM :: (Monad m, Extract a) => ReplaceMethods a -> REContext -> (Match a -> RELocation -> Capture a -> m (Maybe a)) -> Match a -> m a

replaceCapturesM is just a monadically generalised version of replaceCaptures_

REContext and RELocation

data REContext

REContext specifies which contexts the substitutions should be applied

Constructors

TOP

substitutions should be applied to the top-level only, the text that matched the whole RE

SUB

substitutions should only be applied to the text captured by bracketed sub-REs

ALL

the substitution function should be applied to all captures, the top level and the sub-expression captures

Instances

Show REContext

Methods

showsPrec :: Int -> REContext -> ShowS

show :: REContext -> String

showList :: [REContext] -> ShowS

data RELocation

the RELocation information passed into the substitution function specifies which sub-expression is being substituted

Constructors

RELocation

Fields

• locationMatch :: Int

  the zero-based, i-th string to be matched, when matching all strings, zero when only the first string is being matched

• locationCapture :: CaptureOrdinal

  0, when matching the top-level string matched by the whole RE, 1 for the top-most, left-most redex captured by bracketed sub-REs, etc.

Instances

Show RELocation

Methods

showsPrec :: Int -> RELocation -> ShowS

show :: RELocation -> String

showList :: [RELocation] -> ShowS

isTopLocation :: RELocation -> Bool

True iff the location references a complete match (i.e., not a bracketed capture)

Matches

data Matches a

the result of matching a RE against a text (with *=~), retaining the text that was matched against

Constructors

Matches

Fields

• matchesSource :: !a

  the source text being matched

• allMatches :: ![Match a]

  all Match instances found, left to right

Instances

Functor Matches

Methods

fmap :: (a -> b) -> Matches a -> Matches b

(<$) :: a -> Matches b -> Matches a

(RegexContext regex source [MatchText source], RegexLike regex source) => RegexContext regex source (Matches source)

this instance hooks Matches into regex-base: regex consumers need not worry about any of this

Methods

match :: regex -> source -> Matches source

matchM :: Monad m => regex -> source -> m (Matches source)

Eq a => Eq (Matches a)

Methods

(==) :: Matches a -> Matches a -> Bool

(/=) :: Matches a -> Matches a -> Bool

Show a => Show (Matches a)

Methods

showsPrec :: Int -> Matches a -> ShowS

show :: Matches a -> String

showList :: [Matches a] -> ShowS

anyMatches :: Matches a -> Bool

tests whether the RE matched the source text at all

countMatches :: Matches a -> Int

count the matches

matches :: Matches a -> [a]

list the texts that Matched

mainCaptures :: Matches a -> [Capture a]

extract the main capture from each match

Match

data Match a

the result of matching a RE to a text once (with ?=~), retaining the text that was matched against

Constructors

Match

Fields

• matchSource :: !a

  the whole source text

• captureNames :: !CaptureNames

  the RE's capture names

• matchArray :: !(Array CaptureOrdinal (Capture a))
  1. .n-1 captures, starting with the text matched by the whole RE

Instances

Functor Match

Methods

fmap :: (a -> b) -> Match a -> Match b

(<$) :: a -> Match b -> Match a

(RegexContext regex source (AllTextSubmatches (Array Int) (source, (Int, Int))), RegexLike regex source) => RegexContext regex source (Match source)

this instance hooks Match into regex-base: regex consumers need not worry about any of this

Methods

match :: regex -> source -> Match source

matchM :: Monad m => regex -> source -> m (Match source)

Eq a => Eq (Match a)

Methods

(==) :: Match a -> Match a -> Bool

(/=) :: Match a -> Match a -> Bool

Show a => Show (Match a)

Methods

showsPrec :: Int -> Match a -> ShowS

show :: Match a -> String

showList :: [Match a] -> ShowS

noMatch :: a -> Match a

Construct a Match that does not match anything.

emptyMatchArray :: Array CaptureOrdinal (Capture a)

an empty array of Capture

matched :: Match a -> Bool

tests whether the RE matched the source text at all

matchedText :: Match a -> Maybe a

yields the text matched by the RE, Nothing if no match

matchCapture :: Match a -> Maybe (Capture a)

the top-level capture if the source text matched the RE, Nothing otherwise

matchCaptures :: Match a -> Maybe (Capture a, [Capture a])

the main top-level capture (capture '0'') and the sub captures if the text matched the RE, Nothing otherwise

(!$$) :: Match a -> CaptureID -> a infixl 9

an alternative for captureText

captureText :: CaptureID -> Match a -> a

look up the text of the nth capture, 0 being the match of the whole RE against the source text, 1, the first bracketed sub-expression to be matched and so on

(!$$?) :: Match a -> CaptureID -> Maybe a

an alternative for captureTextMaybe

captureTextMaybe :: CaptureID -> Match a -> Maybe a

look up the text of the nth capture (0 being the match of the whole), returning Nothing if the Match doesn't contain the capture

(!$) :: Match a -> CaptureID -> Capture a infixl 9

an alternative for capture

capture :: CaptureID -> Match a -> Capture a

look up the nth capture, 0 being the match of the whole RE against the source text, 1, the first bracketed sub-expression to be matched and so on

(!$?) :: Match a -> CaptureID -> Maybe (Capture a)

an alternative for capture captureMaybe

captureMaybe :: CaptureID -> Match a -> Maybe (Capture a)

look up the nth capture, 0 being the match of the whole RE against the source text, 1, the first bracketed sub-expression to be matched and so on, returning Nothing if there is no such capture, or if the capture failed to capture anything (being in a failed alternate)

convertMatchText :: source -> MatchText source -> Match source

convert a regex-base native MatchText into a regex Match type

Capture

data Capture a

the matching of a single sub-expression against part of the source text

Constructors

Capture

Fields

• captureSource :: !a

  the whole text that was searched

• capturedText :: !a

  the text that was matched

• captureOffset :: !Int

  the number of characters preceding the match with -1 used if no text was captured by the RE (not even the empty string)

• captureLength :: !Int

  the number of chacter in the captured sub-string

Instances

Functor Capture

Methods

fmap :: (a -> b) -> Capture a -> Capture b

(<$) :: a -> Capture b -> Capture a

Eq a => Eq (Capture a)

Methods

(==) :: Capture a -> Capture a -> Bool

(/=) :: Capture a -> Capture a -> Bool

Show a => Show (Capture a)

Methods

showsPrec :: Int -> Capture a -> ShowS

show :: Capture a -> String

showList :: [Capture a] -> ShowS

hasCaptured :: Capture a -> Bool

test if the capture has matched any text

capturePrefix :: Extract a => Capture a -> a

returns the text preceding the match

captureSuffix :: Extract a => Capture a -> a

returns the text after the match

CaptureID

data CaptureID

CaptureID identifies captures, either by number (e.g., [cp|1|]) or name (e.g., [cp|foo|]).

Constructors

IsCaptureOrdinal CaptureOrdinal

IsCaptureName CaptureName

Instances

Eq CaptureID

Methods

(==) :: CaptureID -> CaptureID -> Bool

(/=) :: CaptureID -> CaptureID -> Bool

Ord CaptureID

Methods

compare :: CaptureID -> CaptureID -> Ordering

(<) :: CaptureID -> CaptureID -> Bool

(<=) :: CaptureID -> CaptureID -> Bool

(>) :: CaptureID -> CaptureID -> Bool

(>=) :: CaptureID -> CaptureID -> Bool

max :: CaptureID -> CaptureID -> CaptureID

min :: CaptureID -> CaptureID -> CaptureID

Show CaptureID

Methods

showsPrec :: Int -> CaptureID -> ShowS

show :: CaptureID -> String

showList :: [CaptureID] -> ShowS

type CaptureNames = HashMap CaptureName CaptureOrdinal

the dictionary for named captures stored in compiled regular expressions associates

noCaptureNames :: CaptureNames

an empty CaptureNames dictionary

newtype CaptureName

a CaptureName is just the text of the name

Constructors

CaptureName

Fields

• getCaptureName :: Text

Instances

Eq CaptureName

Methods

(==) :: CaptureName -> CaptureName -> Bool

(/=) :: CaptureName -> CaptureName -> Bool

Ord CaptureName

Methods

compare :: CaptureName -> CaptureName -> Ordering

(<) :: CaptureName -> CaptureName -> Bool

(<=) :: CaptureName -> CaptureName -> Bool

(>) :: CaptureName -> CaptureName -> Bool

(>=) :: CaptureName -> CaptureName -> Bool

max :: CaptureName -> CaptureName -> CaptureName

min :: CaptureName -> CaptureName -> CaptureName

Show CaptureName

Methods

showsPrec :: Int -> CaptureName -> ShowS

show :: CaptureName -> String

showList :: [CaptureName] -> ShowS

Hashable CaptureName

Methods

hashWithSalt :: Int -> CaptureName -> Int

hash :: CaptureName -> Int

newtype CaptureOrdinal

a CaptureOrdinal is just the number of the capture, starting with 0 for the whole of the text matched, then in leftmost, outermost

Constructors

CaptureOrdinal

Fields

• getCaptureOrdinal :: Int

Instances

Enum CaptureOrdinal

Methods

succ :: CaptureOrdinal -> CaptureOrdinal

pred :: CaptureOrdinal -> CaptureOrdinal

toEnum :: Int -> CaptureOrdinal

fromEnum :: CaptureOrdinal -> Int

enumFrom :: CaptureOrdinal -> [CaptureOrdinal]

enumFromThen :: CaptureOrdinal -> CaptureOrdinal -> [CaptureOrdinal]

enumFromTo :: CaptureOrdinal -> CaptureOrdinal -> [CaptureOrdinal]

enumFromThenTo :: CaptureOrdinal -> CaptureOrdinal -> CaptureOrdinal -> [CaptureOrdinal]

Eq CaptureOrdinal

Methods

(==) :: CaptureOrdinal -> CaptureOrdinal -> Bool

(/=) :: CaptureOrdinal -> CaptureOrdinal -> Bool

Num CaptureOrdinal

Methods

(+) :: CaptureOrdinal -> CaptureOrdinal -> CaptureOrdinal

(-) :: CaptureOrdinal -> CaptureOrdinal -> CaptureOrdinal

(*) :: CaptureOrdinal -> CaptureOrdinal -> CaptureOrdinal

negate :: CaptureOrdinal -> CaptureOrdinal

abs :: CaptureOrdinal -> CaptureOrdinal

signum :: CaptureOrdinal -> CaptureOrdinal

fromInteger :: Integer -> CaptureOrdinal

Ord CaptureOrdinal

Methods

compare :: CaptureOrdinal -> CaptureOrdinal -> Ordering

(<) :: CaptureOrdinal -> CaptureOrdinal -> Bool

(<=) :: CaptureOrdinal -> CaptureOrdinal -> Bool

(>) :: CaptureOrdinal -> CaptureOrdinal -> Bool

(>=) :: CaptureOrdinal -> CaptureOrdinal -> Bool

max :: CaptureOrdinal -> CaptureOrdinal -> CaptureOrdinal

min :: CaptureOrdinal -> CaptureOrdinal -> CaptureOrdinal

Show CaptureOrdinal

Methods

showsPrec :: Int -> CaptureOrdinal -> ShowS

show :: CaptureOrdinal -> String

showList :: [CaptureOrdinal] -> ShowS

Ix CaptureOrdinal

Methods

range :: (CaptureOrdinal, CaptureOrdinal) -> [CaptureOrdinal]

index :: (CaptureOrdinal, CaptureOrdinal) -> CaptureOrdinal -> Int

unsafeIndex :: (CaptureOrdinal, CaptureOrdinal) -> CaptureOrdinal -> Int

inRange :: (CaptureOrdinal, CaptureOrdinal) -> CaptureOrdinal -> Bool

rangeSize :: (CaptureOrdinal, CaptureOrdinal) -> Int

unsafeRangeSize :: (CaptureOrdinal, CaptureOrdinal) -> Int

findCaptureID :: CaptureID -> CaptureNames -> Either String CaptureOrdinal

look up a CaptureID in the CaptureNames dictionary

Replace and ReplaceMethods

class (Show a, Eq a, Ord a, Extract a, Monoid a) => Replace a where

Replace provides the missing needed to replace the matched text in a Replace a => Match a.

Minimal complete definition

lengthR, packR, unpackR, linesR, unlinesR, parseTemplateR

Methods

lengthR :: a -> Int

length function for a

packR :: String -> a

inject String into a

unpackR :: a -> String

project a onto a String

textifyR :: a -> Text

inject into Text

detextifyR :: Text -> a

project Text onto a

linesR :: a -> [a]

split into lines

unlinesR :: [a] -> a

concatenate a list of lines

appendNewlineR :: a -> a

append a newline

substR :: (a -> a) -> Capture a -> a

apply a substitution function to a Capture

parseTemplateR :: a -> Match a -> RELocation -> Capture a -> Maybe a

convert a template containing $0, $1, etc., in the first argument, into a phi replacement function for use with replaceAllCaptures and replaceCaptures

Instances

Replace ByteString

Methods

lengthR :: ByteString -> Int

packR :: String -> ByteString

unpackR :: ByteString -> String

textifyR :: ByteString -> Text

detextifyR :: Text -> ByteString

linesR :: ByteString -> [ByteString]

unlinesR :: [ByteString] -> ByteString

appendNewlineR :: ByteString -> ByteString

substR :: (ByteString -> ByteString) -> Capture ByteString -> ByteString

parseTemplateR :: ByteString -> Match ByteString -> RELocation -> Capture ByteString -> Maybe ByteString

Replace ByteString

Methods

lengthR :: ByteString -> Int

packR :: String -> ByteString

unpackR :: ByteString -> String

textifyR :: ByteString -> Text

detextifyR :: Text -> ByteString

linesR :: ByteString -> [ByteString]

unlinesR :: [ByteString] -> ByteString

appendNewlineR :: ByteString -> ByteString

substR :: (ByteString -> ByteString) -> Capture ByteString -> ByteString

parseTemplateR :: ByteString -> Match ByteString -> RELocation -> Capture ByteString -> Maybe ByteString

Replace Text

Methods

lengthR :: Text -> Int

packR :: String -> Text

unpackR :: Text -> String

textifyR :: Text -> Text

detextifyR :: Text -> Text

linesR :: Text -> [Text]

unlinesR :: [Text] -> Text

appendNewlineR :: Text -> Text

substR :: (Text -> Text) -> Capture Text -> Text

parseTemplateR :: Text -> Match Text -> RELocation -> Capture Text -> Maybe Text

Replace Text

Methods

lengthR :: Text -> Int

packR :: String -> Text

unpackR :: Text -> String

textifyR :: Text -> Text

detextifyR :: Text -> Text

linesR :: Text -> [Text]

unlinesR :: [Text] -> Text

appendNewlineR :: Text -> Text

substR :: (Text -> Text) -> Capture Text -> Text

parseTemplateR :: Text -> Match Text -> RELocation -> Capture Text -> Maybe Text

Replace [Char]

Methods

lengthR :: [Char] -> Int

packR :: String -> [Char]

unpackR :: [Char] -> String

textifyR :: [Char] -> Text

detextifyR :: Text -> [Char]

linesR :: [Char] -> [[Char]]

unlinesR :: [[Char]] -> [Char]

appendNewlineR :: [Char] -> [Char]

substR :: ([Char] -> [Char]) -> Capture [Char] -> [Char]

parseTemplateR :: [Char] -> Match [Char] -> RELocation -> Capture [Char] -> Maybe [Char]

Replace (Seq Char)

Methods

lengthR :: Seq Char -> Int

packR :: String -> Seq Char

unpackR :: Seq Char -> String

textifyR :: Seq Char -> Text

detextifyR :: Text -> Seq Char

linesR :: Seq Char -> [Seq Char]

unlinesR :: [Seq Char] -> Seq Char

appendNewlineR :: Seq Char -> Seq Char

substR :: (Seq Char -> Seq Char) -> Capture (Seq Char) -> Seq Char

parseTemplateR :: Seq Char -> Match (Seq Char) -> RELocation -> Capture (Seq Char) -> Maybe (Seq Char)

data ReplaceMethods a

a selction of the Replace methods can be encapsulated with ReplaceMethods for the higher-order replacement functions

Constructors

ReplaceMethods

Fields

• methodLength :: a -> Int
• methodSubst :: (a -> a) -> Capture a -> a

replaceMethods :: Replace a => ReplaceMethods a

replaceMethods encapsulates ReplaceMethods a from a Replace a context