Text.RE

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

• Text.RE.PCRE
• Text.RE.PCRE.ByteString
• Text.RE.PCRE.ByteString.Lazy
• Text.RE.PCRE.RE
• Text.RE.PCRE.Sequence
• Text.RE.PCRE.String
• 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 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

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

for matching all REs against the source text

Eq a => Eq (Matches a)

Show a => Show (Matches a)

Typeable (* -> *) Matches

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

(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

Eq a => Eq (Match a)

Show a => Show (Match a)

Typeable (* -> *) Match

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

Eq a => Eq (Capture a)

Show a => Show (Capture a)

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]

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

IsRegex

class Replace s => IsRegex re s where

Methods

matchOnce :: re -> s -> Match s

matchMany :: re -> s -> Matches s

regexSource :: re -> String

Instances

IsRegex RE String

IsRegex RE ByteString

IsRegex RE ByteString

IsRegex RE Text

IsRegex RE Text

IsRegex RE (Seq Char)

Options

data Options_ r c e

Constructors

Options

Fields

optionsMacs :: !(Macros r)

optionsComp :: !c

optionsExec :: !e

Instances

IsOption Options RE CompOption ExecOption

(Show r, Show c, Show e) => Show (Options_ r c e)

class IsOption o r c e | e -> r, c -> e, e -> c, r -> c, c -> r, r -> e where

Methods

makeOptions :: o -> Options_ r c e

Instances

IsOption () RE CompOption ExecOption

IsOption SimpleRegexOptions RE CompOption ExecOption

IsOption ExecOption RE CompOption ExecOption

IsOption CompOption RE CompOption ExecOption

IsOption Options RE CompOption ExecOption

IsOption (Macros RE) RE CompOption ExecOption

newtype MacroID

Constructors

MacroID

Fields

getMacroID :: String

Instances

Eq MacroID

Ord MacroID

Show MacroID

IsString MacroID

Hashable MacroID

IsOption (Macros RE) RE CompOption ExecOption

type Macros r = HashMap MacroID r

emptyMacros :: Macros r

data SimpleRegexOptions

Constructors

MultilineSensitive

MultilineInsensitive

BlockSensitive

BlockInsensitive

Instances

Bounded SimpleRegexOptions

Enum SimpleRegexOptions

Eq SimpleRegexOptions

Ord SimpleRegexOptions

Show SimpleRegexOptions

Lift SimpleRegexOptions

IsOption SimpleRegexOptions RE CompOption ExecOption

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

Ord CaptureID

Show CaptureID

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

Ord CaptureName

Show CaptureName

Hashable CaptureName

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

Eq CaptureOrdinal

Num CaptureOrdinal

Ord CaptureOrdinal

Show CaptureOrdinal

Ix CaptureOrdinal

findCaptureID :: CaptureID -> CaptureNames -> Int

look up a CaptureID in the CaptureNames dictionary

Edit

data Edits m re s

Constructors

Select [(re, Edit m s)]

Pipe [(re, Edit m s)]

data Edit m s

Constructors

Template s

Function Context (LineNo -> Match s -> Location -> Capture s -> m (Maybe s))

LineEdit (LineNo -> Matches s -> m (LineEdit s))

data LineEdit s

Constructors

NoEdit

ReplaceWith s

Delete

Instances

Show s => Show (LineEdit s)

applyEdits :: (IsRegex re s, Monad m, Functor m) => LineNo -> Edits m re s -> s -> m s

applyEdit :: (IsRegex re s, Monad m, Functor m) => (s -> s) -> LineNo -> re -> Edit m s -> s -> m (Maybe s)

applyLineEdit :: Monoid s => (s -> s) -> LineEdit s -> Maybe s

LineNo

newtype LineNo

Constructors

ZeroBasedLineNo

Fields

getZeroBasedLineNo :: Int

Instances

Enum LineNo

Show LineNo

firstLine :: LineNo

getLineNo :: LineNo -> Int

lineNo :: Int -> LineNo

Parsers

parseInteger :: Replace a => a -> Maybe Int

parseHex :: Replace a => a -> Maybe Int

parseDouble :: Replace a => a -> Maybe Double

parseString :: Replace a => a -> Maybe Text

parseSimpleString :: Replace a => a -> Maybe Text

parseDate :: Replace a => a -> Maybe Day

parseSlashesDate :: Replace a => a -> Maybe Day

parseTimeOfDay :: Replace a => a -> Maybe TimeOfDay

parseTimeZone :: Replace a => a -> Maybe TimeZone

parseDateTime :: Replace a => a -> Maybe UTCTime

parseDateTime8601 :: Replace a => a -> Maybe UTCTime

parseDateTimeCLF :: Replace a => a -> Maybe UTCTime

parseShortMonth :: Replace a => a -> Maybe Int

shortMonthArray :: Array Int Text

type IPV4Address = (Word8, Word8, Word8, Word8)

parseIPv4Address :: Replace a => a -> Maybe IPV4Address

data Severity

Constructors

Emerg

Alert

Crit

Err

Warning

Notice

Info

Debug

Instances

Bounded Severity

Enum Severity

Eq Severity

Ord Severity

Show Severity

parseSeverity :: Replace a => a -> Maybe Severity

severityKeywords :: Severity -> (Text, [Text])

Replace

class (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, 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

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

Replace ByteString

Replace Text

Replace Text

Replace [Char]

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

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

isTopLocation :: Location -> Bool

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

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

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

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

Tools

Grep

data Line

Constructors

Line

Fields

getLineNumber :: LineNo

getLineMatches :: Matches ByteString

Instances

Show Line

grep :: IsRegex re ByteString => re -> FilePath -> IO ()

grepLines :: IsRegex re ByteString => re -> FilePath -> IO [Line]

type GrepScript re s t = [(re, LineNo -> Matches s -> Maybe t)]

grepScript :: IsRegex re s => GrepScript re s t -> [s] -> [t]

linesMatched :: [Line] -> [Line]

Lex

alex :: IsRegex re s => [(re, Match s -> Maybe t)] -> t -> s -> [t]

alex' :: Replace s => (re -> s -> Match s) -> [(re, Match s -> Maybe t)] -> t -> s -> [t]

Sed

type SedScript re = Edits IO re ByteString

sed :: IsRegex re ByteString => SedScript re -> FilePath -> FilePath -> IO ()

sed' :: (IsRegex re ByteString, Monad m, Functor m) => Edits m re ByteString -> ByteString -> m ByteString