Text.RE

The Tutorial

We have a regex tutorial at http://tutorial.regex.uk. These API docs are mainly for reference.

How to use this library

This module won't provide any operators to match a regular expression against text as it merely provides the toolkit for working with the output of the match operators. You probably won't import it directly but import one of the modules that provides the match operators, which will in tuen re-export this module.

The module that you choose to import will depend upon two factors:

• Which flavour of regular expression do you want to use? If you want Posix flavour REs then you want the TDFA modules, otherwise its PCRE for Perl-style REs.
• What type of text do you want to match: (slow) Strings, ByteString, ByteString.Lazy, Text, Text.Lazy or the anachronistic Seq Char or indeed a good old-fashioned polymorphic operators?

While we aim to provide all combinations of these choices, some of them are currently not available. In the regex package we have:

• Text.RE.TDFA
• Text.RE.TDFA.ByteString
• Text.RE.TDFA.ByteString.Lazy
• Text.RE.TDFA.RE
• Text.RE.TDFA.Sequence
• Text.RE.TDFA.String
• Text.RE.TDFA.Text
• Text.RE.TDFA.Text.Lazy

The PCRE modules are contained in the separate regex-with-pcre package:

• Text.RE.PCRE
• Text.RE.PCRE.ByteString
• Text.RE.PCRE.ByteString.Lazy
• Text.RE.PCRE.RE
• Text.RE.PCRE.Sequence
• Text.RE.PCRE.String

The Match Operators

The traditional =~ and =~~ operators are exported by the regex, but we recommend that you use the two new operators, especially if you are not familiar with the old operators. We have:

• txt ?=~ re searches for a single match yielding a value of type Match a where a is the type of the text you are searching.
• txt *=~ re searches for all non-overlapping matches in txt, returning a value of type Matches a.

See the sections below for more information on these Matches and Match result types.

Matches, Match & Capture

data Matches a

the result type to use when every match is needed, not just the first match of the RE against the source

Constructors

Matches

Fields

• matchesSource :: !a

  the source text being matched

• allMatches :: ![Match a]

  all captures 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)

for matching all REs against the source text

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

data Match a

the result of matching a RE to a text once, listing the text that was matched and the named captures in the RE and all of the substrings matched, with the text captured by the whole RE; a complete failure to match will be represented with an empty array (with bounds (0,-1))

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)

for matching just the first RE against the source text

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

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

noMatch :: a -> Match a

Construct a Match that does not match anything.

Matches functions

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 Matches

mainCaptures :: Matches a -> [Capture a]

extract the main capture from each match

Match functions

matched :: Match a -> Bool

tests whether the RE matched the source text at all

matchedText :: Match a -> Maybe a

tests whether the RE matched the source text at all

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 top-level capture 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)

Capture functions

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

Options

data SimpleRegexOptions

Constructors

MultilineSensitive

MultilineInsensitive

BlockSensitive

BlockInsensitive

Instances

Bounded SimpleRegexOptions

Methods

minBound :: SimpleRegexOptions

maxBound :: SimpleRegexOptions

Enum SimpleRegexOptions

Methods

succ :: SimpleRegexOptions -> SimpleRegexOptions

pred :: SimpleRegexOptions -> SimpleRegexOptions

toEnum :: Int -> SimpleRegexOptions

fromEnum :: SimpleRegexOptions -> Int

enumFrom :: SimpleRegexOptions -> [SimpleRegexOptions]

enumFromThen :: SimpleRegexOptions -> SimpleRegexOptions -> [SimpleRegexOptions]

enumFromTo :: SimpleRegexOptions -> SimpleRegexOptions -> [SimpleRegexOptions]

enumFromThenTo :: SimpleRegexOptions -> SimpleRegexOptions -> SimpleRegexOptions -> [SimpleRegexOptions]

Eq SimpleRegexOptions

Methods

(==) :: SimpleRegexOptions -> SimpleRegexOptions -> Bool

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

Ord SimpleRegexOptions

Methods

compare :: SimpleRegexOptions -> SimpleRegexOptions -> Ordering

(<) :: SimpleRegexOptions -> SimpleRegexOptions -> Bool

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

(>) :: SimpleRegexOptions -> SimpleRegexOptions -> Bool

(>=) :: SimpleRegexOptions -> SimpleRegexOptions -> Bool

max :: SimpleRegexOptions -> SimpleRegexOptions -> SimpleRegexOptions

min :: SimpleRegexOptions -> SimpleRegexOptions -> SimpleRegexOptions

Show SimpleRegexOptions

Methods

showsPrec :: Int -> SimpleRegexOptions -> ShowS

show :: SimpleRegexOptions -> String

showList :: [SimpleRegexOptions] -> ShowS

Lift SimpleRegexOptions

Methods

lift :: SimpleRegexOptions -> Q Exp

CaptureID

data CaptureID

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

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

Replace

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

Replace provides the missing methods needed to replace the matched text; lengthE is the minimum implementation

Minimal complete definition

lengthE, packE, unpackE, linesE, unlinesE, parseTemplateE

Methods

lengthE :: a -> Int

length function for a

packE :: String -> a

inject String into a

unpackE :: a -> String

project a onto a String

textifyE :: a -> Text

inject into Text

detextifyE :: Text -> a

project Text onto a

linesE :: a -> [a]

split into lines

unlinesE :: [a] -> a

concatenate a list of lines

appendNewlineE :: a -> a

append a newline

substE :: (a -> a) -> Capture a -> a

apply a substitution function to a Capture

parseTemplateE :: a -> Match a -> Location -> 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

lengthE :: ByteString -> Int

packE :: String -> ByteString

unpackE :: ByteString -> String

textifyE :: ByteString -> Text

detextifyE :: Text -> ByteString

linesE :: ByteString -> [ByteString]

unlinesE :: [ByteString] -> ByteString

appendNewlineE :: ByteString -> ByteString

substE :: (ByteString -> ByteString) -> Capture ByteString -> ByteString

parseTemplateE :: ByteString -> Match ByteString -> Location -> Capture ByteString -> Maybe ByteString

Replace ByteString

Methods

lengthE :: ByteString -> Int

packE :: String -> ByteString

unpackE :: ByteString -> String

textifyE :: ByteString -> Text

detextifyE :: Text -> ByteString

linesE :: ByteString -> [ByteString]

unlinesE :: [ByteString] -> ByteString

appendNewlineE :: ByteString -> ByteString

substE :: (ByteString -> ByteString) -> Capture ByteString -> ByteString

parseTemplateE :: ByteString -> Match ByteString -> Location -> Capture ByteString -> Maybe ByteString

Replace Text

Methods

lengthE :: Text -> Int

packE :: String -> Text

unpackE :: Text -> String

textifyE :: Text -> Text

detextifyE :: Text -> Text

linesE :: Text -> [Text]

unlinesE :: [Text] -> Text

appendNewlineE :: Text -> Text

substE :: (Text -> Text) -> Capture Text -> Text

parseTemplateE :: Text -> Match Text -> Location -> Capture Text -> Maybe Text

Replace Text

Methods

lengthE :: Text -> Int

packE :: String -> Text

unpackE :: Text -> String

textifyE :: Text -> Text

detextifyE :: Text -> Text

linesE :: Text -> [Text]

unlinesE :: [Text] -> Text

appendNewlineE :: Text -> Text

substE :: (Text -> Text) -> Capture Text -> Text

parseTemplateE :: Text -> Match Text -> Location -> Capture Text -> Maybe Text

Replace [Char]

Methods

lengthE :: [Char] -> Int

packE :: String -> [Char]

unpackE :: [Char] -> String

textifyE :: [Char] -> Text

detextifyE :: Text -> [Char]

linesE :: [Char] -> [[Char]]

unlinesE :: [[Char]] -> [Char]

appendNewlineE :: [Char] -> [Char]

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

parseTemplateE :: [Char] -> Match [Char] -> Location -> Capture [Char] -> Maybe [Char]

Replace (Seq Char)

Methods

lengthE :: Seq Char -> Int

packE :: String -> Seq Char

unpackE :: Seq Char -> String

textifyE :: Seq Char -> Text

detextifyE :: Text -> Seq Char

linesE :: Seq Char -> [Seq Char]

unlinesE :: [Seq Char] -> Seq Char

appendNewlineE :: Seq Char -> Seq Char

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

parseTemplateE :: Seq Char -> Match (Seq Char) -> Location -> 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

data Context

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

Methods

showsPrec :: Int -> Context -> ShowS

show :: Context -> String

showList :: [Context] -> ShowS

data Location

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

Constructors

Location

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 Location

Methods

showsPrec :: Int -> Location -> ShowS

show :: Location -> String

showList :: [Location] -> ShowS

isTopLocation :: Location -> Bool

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

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

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

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

replaceAllCaptures :: Replace a => Context -> (Match a -> Location -> 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 -> Context -> (Match a -> Location -> 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 -> Context -> (Match a -> Location -> Capture a -> m (Maybe a)) -> Matches a -> m a

replaceAllCapturesM is just a monadically generalised version of replaceAllCaptures_

replaceCaptures :: Replace a => Context -> (Match a -> Location -> 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 -> Context -> (Match a -> Location -> 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 -> Context -> (Match a -> Location -> Capture a -> m (Maybe a)) -> Match a -> m a

replaceCapturesM is just a monadically generalised version of replaceCaptures_

expandMacros :: (r -> String) -> Macros r -> String -> String

expand all of the @{..} macros in the RE in the argument String according to the Macros argument, preprocessing the RE String according to the Mode argument (used internally)

expandMacros' :: (MacroID -> Maybe String) -> String -> String

expand the @{..} macos in the argument string using the given function