Skip to content

HORIZON HASKELL Docs lts/ghc-9.14.x7a6c33e2026-10-12Search packagesCtrl K

Theme: |

GHC 9.14.1 · lts/ghc-9.14.x · 7a6c33e · 2026-10-12

Moduleregex-1.1.0.2Haskell2010

Text.RE.Replace

Contents

The Replacing Tutorial
replaceAll
replace
REContext and RELocation
Matches
Match
Capture
CaptureID
Replace and ReplaceMethods

Synopsis

Packageregex-1.1.0.2
Exports45
LanguageHaskell2010
LicenceBSD-3-Clause
SourceReplace.lhs

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

valuereplaceAll :: Replace a => a -> Matches a -> a

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

valuereplaceAllCaptures

:: 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.

valuereplaceAllCaptures_

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

valuereplaceAllCapturesM

:: (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

valuereplace :: Replace a => a -> Match a -> a

valuereplaceCaptures

:: 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.

valuereplaceCaptures_

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

valuereplaceCapturesM

:: (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

datadata 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

Instances1Show

Show REContextDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Replace

datadata RELocation

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

Constructors

RELocation
- 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.

Instances1Show

Show RELocationDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Replace

valueisTopLocation :: RELocation -> Bool

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

Matches

datadata Matches a

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

Constructors

Matches
- matchesSource :: !a
  the source text being matched
- allMatches :: ![Match a]
  all Match instances found, left to right

Instances4Functor, RegexContext, Eq, Show

Functor MatchesDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Matches
(RegexContext regex source [MatchText source], RegexLike regex source, RegexFix regex source) => RegexContext regex source (Matches source)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Matches
this instance hooks Matches into regex-base: regex consumers need not worry about any of this
Eq a => Eq (Matches a)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Matches
Show a => Show (Matches a)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Matches

valueanyMatches :: Matches a -> Bool

tests whether the RE matched the source text at all

valuecountMatches :: Matches a -> Int

count the matches

valuematches :: Matches a -> [a]

list the texts that Matched

valuemainCaptures :: Matches a -> [Capture a]

extract the main capture from each match

Match

datadata Match a

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

Constructors

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

Instances4Functor, RegexContext, Eq, Show

Functor MatchDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Match
(RegexContext regex source (AllTextSubmatches (Array Int) (source, (Int, Int))), RegexLike regex source, RegexFix regex source) => RegexContext regex source (Match source)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Match
this instance hooks Match into regex-base: regex consumers need not worry about any of this
Eq a => Eq (Match a)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Match
Show a => Show (Match a)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Match

valuenoMatch :: a -> Match a

Construct a Match that does not match anything.

valueemptyMatchArray :: Array CaptureOrdinal (Capture a)

an empty array of Capture

valuematched :: Match a -> Bool

tests whether the RE matched the source text at all

valuematchedText :: Match a -> Maybe a

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

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

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

valuematchCaptures :: 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

value(!$$) :: Match a -> CaptureID -> a

an alternative for captureText

valuecaptureText :: 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

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

an alternative for captureTextMaybe

valuecaptureTextMaybe :: 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

value(!$) :: Match a -> CaptureID -> Capture a

an alternative for capture

valuecapture :: 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

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

an alternative for capture captureMaybe

valuecaptureMaybe :: 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)

valueconvertMatchText

:: RegexFix regex source
=> regex
-> source
-> MatchText source
-> Match source

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

Capture

datadata Capture a

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

Constructors

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

Instances3Functor, Eq, Show

Functor CaptureDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Capture
Eq a => Eq (Capture a)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Capture
Show a => Show (Capture a)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.Capture

valuehasCaptured :: Capture a -> Bool

test if the capture has matched any text

valuecapturePrefix :: Extract a => Capture a -> a

returns the text preceding the match

valuecaptureSuffix :: Extract a => Capture a -> a

returns the text after the match

CaptureID

datadata CaptureID

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

Constructors

IsCaptureOrdinal CaptureOrdinal
IsCaptureName CaptureName

Instances3Eq, Ord, Show

Eq CaptureIDDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Ord CaptureIDDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Show CaptureIDDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID

typetype CaptureNames = HashMap CaptureName CaptureOrdinal

the dictionary for named captures stored in compiled regular expressions associates

valuenoCaptureNames :: CaptureNames

an empty CaptureNames dictionary

newtypenewtype CaptureName

a CaptureName is just the text of the name

Constructors

CaptureName
- getCaptureName :: Text

Instances4Eq, Ord, Show, Hashable

Eq CaptureNameDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Ord CaptureNameDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Show CaptureNameDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Hashable CaptureNameDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID

newtypenewtype 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
- getCaptureOrdinal :: Int

Instances6Enum, Eq, Num, Ord, Show, Ix

Enum CaptureOrdinalDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Eq CaptureOrdinalDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Num CaptureOrdinalDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Ord CaptureOrdinalDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Show CaptureOrdinalDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID
Ix CaptureOrdinalDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Types.CaptureID

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

look up a CaptureID in the CaptureNames dictionary

Replace and ReplaceMethods

classclass (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.

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

Instances6Replace

Replace ByteStringDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Replace
Replace ByteStringDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Replace
Replace TextDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Replace
Replace TextDefined in regex-1.1.0.2 · Text.RE.ZeInternals.Replace
Replace (Seq Char)Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Replace
Replace [Char]Defined in regex-1.1.0.2 · Text.RE.ZeInternals.Replace

datadata ReplaceMethods a

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

Constructors

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

valuereplaceMethods :: Replace a => ReplaceMethods a

replaceMethods encapsulates ReplaceMethods a from a Replace a context