Text.RE

The Tutorial

We have a regex tutorial at http://tutorial.regex.uk.

How to use this library

This module just provides a brief overview of the regex package. You will need to import one of the API modules of which there is a choice which will depend upon two factors:

• Which flavour of regular expression do you want to use? If you need Posix flavour REs then you will 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 some 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.ByteString
• Text.RE.TDFA.ByteString.Lazy
• Text.RE.ZeInternals.TDFA
• Text.RE.TDFA.Sequence
• Text.RE.TDFA.String
• Text.RE.TDFA.Text
• Text.RE.TDFA.Text.Lazy
• Text.RE.TDFA

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

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

Further Use

For more specialist applications we have the following:

• Text.RE.REOptions for specifying back-end specific options;
• Text.RE.Replace for the full replace toolkit;
• Text.RE.TestBench for building up, testing and doumenting; macro environments for use in REs;
• Text.RE.Tools for an AWK-like text-processing toolkit.

The regex Foundational Types

Matches

data Matches a

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

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

matchesSource :: Matches a -> a

the source text being matched

allMatches :: Matches a -> [Match a]

all Match instances found, left to right

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

Match

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

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

matchSource :: Match a -> a

the whole source text

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