Text.RE.Replace · regex-1.1.0.2

The Replacing Tutorial

0 declarations

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

4 declarations

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

4 declarations

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

3 declarations

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

5 declarations

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

16 declarations

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

4 declarations

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

6 declarations

datadata CaptureID

#

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

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

3 declarations

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