Text.RE.TDFA

Tutorial

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

About this Module

This module provides access to the back end through polymorphic functions that operate over all of the String/Text/ByteString types supported by the back end. The module also provides all of the specialised back-end functionality that will not be needed by most regex clients. If you don't need this generality then you might want to consider using one of the simpler modules that have been specialised for each of these types:

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

The Matches and Match Operators

(*=~) :: IsRegex RE s => s -> RE -> Matches s

find all the matches in the argument text; e.g., to count the number of naturals in s:

countMatches $ s *=~ [re|[0-9]+|]

(?=~) :: IsRegex RE s => s -> RE -> Match s

find the first match in the argument text; e.g., to test if there is a natural number in the input text:

matched $ s ?=~ [re|[0-9]+|]

The SearchReplace Operators

(*=~/) :: IsRegex RE s => s -> SearchReplace RE s -> s

search and replace all matches in the argument text; e.g., this section will convert every YYYY-MM-DD format date in its argument text into a DD/MM/YYYY date:

(*=~/ [ed|${y}([0-9]{4})-0*${m}([0-9]{2})-0*${d}([0-9]{2})///${d}/${m}/${y}|])

(?=~/) :: IsRegex RE s => s -> SearchReplace RE s -> s

search and replace the first occurrence only

The Matches Type

data Matches a

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

Instances

Functor Matches

Defined in Text.RE.ZeInternals.Types.Matches

Methods

fmap :: (a -> b) -> Matches a -> Matches b

(<$) :: a -> Matches b -> Matches a

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

this instance hooks Matches into regex-base: regex consumers need not worry about any of this

Defined in Text.RE.ZeInternals.Types.Matches

Methods

match :: regex -> source -> Matches source

matchM :: MonadFail m => regex -> source -> m (Matches source)

Eq a => Eq (Matches a)

Defined in Text.RE.ZeInternals.Types.Matches

Methods

(==) :: Matches a -> Matches a -> Bool

(/=) :: Matches a -> Matches a -> Bool

Show a => Show (Matches a)

Defined in Text.RE.ZeInternals.Types.Matches

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 texts that Matched

The Match Type

data Match a

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

Instances

Functor Match

Defined in Text.RE.ZeInternals.Types.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, RegexFix regex source) => RegexContext regex source (Match source)

this instance hooks Match into regex-base: regex consumers need not worry about any of this

Defined in Text.RE.ZeInternals.Types.Match

Methods

match :: regex -> source -> Match source

matchM :: MonadFail m => regex -> source -> m (Match source)

Eq a => Eq (Match a)

Defined in Text.RE.ZeInternals.Types.Match

Methods

(==) :: Match a -> Match a -> Bool

(/=) :: Match a -> Match a -> Bool

Show a => Show (Match a)

Defined in Text.RE.ZeInternals.Types.Match

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

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

The Macros and Parsers

There are a number of RE macros and corresponding Haskell parsers for parsing the matched text into appropriate Haskell types. See the Macros Tables for details.

module Text.RE.TestBench.Parsers

The RE Type

data RE

the RE type for this back end representing a well-formed, compiled RE

Instances

IsOption REOptions

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: REOptions -> REOptions

IsRegex RE String

Defined in Text.RE.TDFA.String

Methods

matchOnce :: RE -> String -> Match String

matchMany :: RE -> String -> Matches String

makeRegex :: (Functor m, Monad m, MonadFail m) => String -> m RE

makeRegexWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> String -> m RE

makeSearchReplace :: (Functor m, Monad m, MonadFail m, IsRegex RE String) => String -> String -> m (SearchReplace RE String)

makeSearchReplaceWith :: (Functor m, Monad m, MonadFail m, IsRegex RE String) => SimpleREOptions -> String -> String -> m (SearchReplace RE String)

makeEscaped :: (Functor m, Monad m, MonadFail m) => (String -> String) -> String -> m RE

makeEscapedWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> (String -> String) -> String -> m RE

regexSource :: RE -> String

IsRegex RE ByteString

Defined in Text.RE.TDFA.ByteString.Lazy

Methods

matchOnce :: RE -> ByteString -> Match ByteString

matchMany :: RE -> ByteString -> Matches ByteString

makeRegex :: (Functor m, Monad m, MonadFail m) => ByteString -> m RE

makeRegexWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> ByteString -> m RE

makeSearchReplace :: (Functor m, Monad m, MonadFail m, IsRegex RE ByteString) => ByteString -> ByteString -> m (SearchReplace RE ByteString)

makeSearchReplaceWith :: (Functor m, Monad m, MonadFail m, IsRegex RE ByteString) => SimpleREOptions -> ByteString -> ByteString -> m (SearchReplace RE ByteString)

makeEscaped :: (Functor m, Monad m, MonadFail m) => (ByteString -> ByteString) -> ByteString -> m RE

makeEscapedWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> (ByteString -> ByteString) -> ByteString -> m RE

regexSource :: RE -> ByteString

IsRegex RE ByteString

Defined in Text.RE.TDFA.ByteString

Methods

matchOnce :: RE -> ByteString -> Match ByteString

matchMany :: RE -> ByteString -> Matches ByteString

makeRegex :: (Functor m, Monad m, MonadFail m) => ByteString -> m RE

makeRegexWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> ByteString -> m RE

makeSearchReplace :: (Functor m, Monad m, MonadFail m, IsRegex RE ByteString) => ByteString -> ByteString -> m (SearchReplace RE ByteString)

makeSearchReplaceWith :: (Functor m, Monad m, MonadFail m, IsRegex RE ByteString) => SimpleREOptions -> ByteString -> ByteString -> m (SearchReplace RE ByteString)

makeEscaped :: (Functor m, Monad m, MonadFail m) => (ByteString -> ByteString) -> ByteString -> m RE

makeEscapedWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> (ByteString -> ByteString) -> ByteString -> m RE

regexSource :: RE -> ByteString

IsRegex RE Text

Defined in Text.RE.TDFA.Text.Lazy

Methods

matchOnce :: RE -> Text -> Match Text

matchMany :: RE -> Text -> Matches Text

makeRegex :: (Functor m, Monad m, MonadFail m) => Text -> m RE

makeRegexWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> Text -> m RE

makeSearchReplace :: (Functor m, Monad m, MonadFail m, IsRegex RE Text) => Text -> Text -> m (SearchReplace RE Text)

makeSearchReplaceWith :: (Functor m, Monad m, MonadFail m, IsRegex RE Text) => SimpleREOptions -> Text -> Text -> m (SearchReplace RE Text)

makeEscaped :: (Functor m, Monad m, MonadFail m) => (Text -> Text) -> Text -> m RE

makeEscapedWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> (Text -> Text) -> Text -> m RE

regexSource :: RE -> Text

IsRegex RE Text

Defined in Text.RE.TDFA.Text

Methods

matchOnce :: RE -> Text -> Match Text

matchMany :: RE -> Text -> Matches Text

makeRegex :: (Functor m, Monad m, MonadFail m) => Text -> m RE

makeRegexWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> Text -> m RE

makeSearchReplace :: (Functor m, Monad m, MonadFail m, IsRegex RE Text) => Text -> Text -> m (SearchReplace RE Text)

makeSearchReplaceWith :: (Functor m, Monad m, MonadFail m, IsRegex RE Text) => SimpleREOptions -> Text -> Text -> m (SearchReplace RE Text)

makeEscaped :: (Functor m, Monad m, MonadFail m) => (Text -> Text) -> Text -> m RE

makeEscapedWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> (Text -> Text) -> Text -> m RE

regexSource :: RE -> Text

IsRegex RE (Seq Char)

Defined in Text.RE.TDFA.Sequence

Methods

matchOnce :: RE -> Seq Char -> Match (Seq Char)

matchMany :: RE -> Seq Char -> Matches (Seq Char)

makeRegex :: (Functor m, Monad m, MonadFail m) => Seq Char -> m RE

makeRegexWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> Seq Char -> m RE

makeSearchReplace :: (Functor m, Monad m, MonadFail m, IsRegex RE (Seq Char)) => Seq Char -> Seq Char -> m (SearchReplace RE (Seq Char))

makeSearchReplaceWith :: (Functor m, Monad m, MonadFail m, IsRegex RE (Seq Char)) => SimpleREOptions -> Seq Char -> Seq Char -> m (SearchReplace RE (Seq Char))

makeEscaped :: (Functor m, Monad m, MonadFail m) => (Seq Char -> Seq Char) -> Seq Char -> m RE

makeEscapedWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> (Seq Char -> Seq Char) -> Seq Char -> m RE

regexSource :: RE -> Seq Char

IsOption (Macros RE)

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: Macros RE -> REOptions

regexType :: RegexType

some functions in the Text.RE.TestBench need the back end to be passed dynamically as a RegexType parameters: use regexType for this

reOptions :: RE -> REOptions

extract the REOptions from the RE

reSource :: RE -> String

extract the RE source string from the RE

reCaptureNames :: RE -> CaptureNames

extract the CaptureNames from the RE

reRegex :: RE -> Regex

extract the back end compiled Regex type from the RE

Options

You can specify different compilation options by appending a to the name of an [re| ... |] or [ed| ... /// ... |] quasi quoter to select the corresponding compilation option. For example, the section,

(?=~/ [edBlockInsensitive|foo$///bar|])

will replace a foo suffix of the argument text, of any capitalisation, with a (lower case) bar. If you need to specify the options dynamically, use the [re_| ... |] and [ed_| ... /// ... |] quasi quoters, which generate functions that take an IsOption option (e.g., a SimpleReOptions value) and yields a RE or SearchReplace as appropriate. For example if you have a SimpleReOptions value in sro then

(?=~/ [ed_|foo$///bar|] sro)

will compile the foo$ RE according to the value of sro. For more on specifying RE options see Text.RE.REOptions.

data SimpleREOptions

the default API uses these simple, universal RE options, which get auto-converted into the appropriate back-end REOptions_

Constructors

MultilineSensitive

case-sensitive with ^ and $ matching the start and end of a line

MultilineInsensitive

case-insensitive with ^ and $ matsh the start and end of a line

BlockSensitive

case-sensitive with ^ and $ matching the start and end of the input text

BlockInsensitive

case-insensitive with ^ and $ matching the start and end of the input text

Instances

Bounded SimpleREOptions

Defined in Text.RE.REOptions

Methods

minBound :: SimpleREOptions

maxBound :: SimpleREOptions

Enum SimpleREOptions

Defined in Text.RE.REOptions

Methods

succ :: SimpleREOptions -> SimpleREOptions

pred :: SimpleREOptions -> SimpleREOptions

toEnum :: Int -> SimpleREOptions

fromEnum :: SimpleREOptions -> Int

enumFrom :: SimpleREOptions -> [SimpleREOptions]

enumFromThen :: SimpleREOptions -> SimpleREOptions -> [SimpleREOptions]

enumFromTo :: SimpleREOptions -> SimpleREOptions -> [SimpleREOptions]

enumFromThenTo :: SimpleREOptions -> SimpleREOptions -> SimpleREOptions -> [SimpleREOptions]

Eq SimpleREOptions

Defined in Text.RE.REOptions

Methods

(==) :: SimpleREOptions -> SimpleREOptions -> Bool

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

Ord SimpleREOptions

Defined in Text.RE.REOptions

Methods

compare :: SimpleREOptions -> SimpleREOptions -> Ordering

(<) :: SimpleREOptions -> SimpleREOptions -> Bool

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

(>) :: SimpleREOptions -> SimpleREOptions -> Bool

(>=) :: SimpleREOptions -> SimpleREOptions -> Bool

max :: SimpleREOptions -> SimpleREOptions -> SimpleREOptions

min :: SimpleREOptions -> SimpleREOptions -> SimpleREOptions

Show SimpleREOptions

Defined in Text.RE.REOptions

Methods

showsPrec :: Int -> SimpleREOptions -> ShowS

show :: SimpleREOptions -> String

showList :: [SimpleREOptions] -> ShowS

IsOption SimpleREOptions

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: SimpleREOptions -> REOptions

Lift SimpleREOptions

we need to use this in the quasi quoters to specify SimpleREOptions selected by the quasi quoter

Defined in Text.RE.REOptions

Methods

lift :: SimpleREOptions -> Q Exp

liftTyped :: SimpleREOptions -> Q (TExp SimpleREOptions)

class IsOption o where

a number of types can be used to encode REOptions_, each of which is made a member of this class

Methods

makeREOptions :: o -> REOptions

convert the o type into an REOptions

Instances

IsOption ()

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: () -> REOptions

IsOption CompOption

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: CompOption -> REOptions

IsOption ExecOption

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: ExecOption -> REOptions

IsOption SimpleREOptions

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: SimpleREOptions -> REOptions

IsOption REOptions

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: REOptions -> REOptions

IsOption (Macros RE)

Defined in Text.RE.ZeInternals.TDFA

Methods

makeREOptions :: Macros RE -> REOptions

type REOptions = REOptions_ RE CompOption ExecOption

and the REOptions for this back end (see Text.RE.REOptions for details)

defaultREOptions :: REOptions

the default REOptions

noPreludeREOptions :: REOptions

the default REOptions but with no RE macros defined

unpackSimpleREOptions :: SimpleREOptions -> REOptions

convert a universal SimpleReOptions into the REOptions used by this back end

Compiling and Escaping REs

data SearchReplace re s

contains a compiled RE and replacement template

Constructors

SearchReplace

Fields

• getSearch :: !re

  the RE to match a string to replace

• getTemplate :: !s

  the replacement template with ${cap} used to identify a capture (by number or name if one was given) and $$ being used to escape a single $

Instances

Functor (SearchReplace re)

Defined in Text.RE.ZeInternals.Types.SearchReplace

Methods

fmap :: (a -> b) -> SearchReplace re a -> SearchReplace re b

(<$) :: a -> SearchReplace re b -> SearchReplace re a

(Show re, Show s) => Show (SearchReplace re s)

Defined in Text.RE.ZeInternals.Types.SearchReplace

Methods

showsPrec :: Int -> SearchReplace re s -> ShowS

show :: SearchReplace re s -> String

showList :: [SearchReplace re s] -> ShowS

compileRegex :: (Functor m, Monad m, MonadFail m) => String -> m RE

compile a String into a RE with the default options, generating an error if the RE is not well formed

compileRegexWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> String -> m RE

compile a String into a RE using the given SimpleREOptions, generating an error if the RE is not well formed

compileRegexWithOptions :: (IsOption o, Functor m, Monad m, MonadFail m) => o -> String -> m RE

compile a String into a RE using the given SimpleREOptions, generating an error if the RE is not well formed

compileSearchReplace :: (Monad m, MonadFail m, Functor m, IsRegex RE s) => String -> String -> m (SearchReplace RE s)

compile a SearchReplace template generating errors if the RE or the template are not well formed, all capture references being checked

compileSearchReplaceWith :: (Monad m, MonadFail m, Functor m, IsRegex RE s) => SimpleREOptions -> String -> String -> m (SearchReplace RE s)

compile a SearchReplace template, with simple options, generating errors if the RE or the template are not well formed, all capture references being checked

compileSearchReplaceWithOptions :: (Monad m, MonadFail m, Functor m, IsRegex RE s) => REOptions -> String -> String -> m (SearchReplace RE s)

compile a SearchReplace template, with general options, generating errors if the RE or the template are not well formed, all capture references being checked

escape :: (Functor m, Monad m, MonadFail m) => (String -> String) -> String -> m RE

convert a string into a RE that matches that string, and apply it to an argument continuation function to make up the RE string to be compiled; e.g., to compile a RE that will only match the string:

maybe undefined id . escape (("^"++) . (++"$"))

escapeWith :: (Functor m, Monad m, MonadFail m) => SimpleREOptions -> (String -> String) -> String -> m RE

a variant of escape where the SimpleREOptions are specified

escapeWithOptions :: (IsOption o, Functor m, Monad m, MonadFail m) => o -> (String -> String) -> String -> m RE

a variant of escapeWith that allows an IsOption RE option to be specified

escapeREString :: String -> String

Convert a string into a regular expression that will match that string

The Classic regex-base Match Operators

(=~) :: (RegexContext Regex s a, RegexMaker Regex CompOption ExecOption s) => s -> RE -> a

the regex-base polymorphic match operator

(=~~) :: (Monad m, MonadFail m, RegexContext Regex s a, RegexMaker Regex CompOption ExecOption s) => s -> RE -> m a

the regex-base monadic, polymorphic match operator

The re Quasi Quoters

The [re|.*|] quasi quoters, with variants for specifying different options to the RE compiler (see Text.RE.REOptions), and the specialised back-end types and functions.

re :: QuasiQuoter

[re| ... |], is equivalent to [reMultilineSensitive| ... |], compiling a case-sensitive, multi-line RE

reMultilineSensitive :: QuasiQuoter

[reMultilineSensitive| ... |], compiles a case-sensitive, multi-line RE

reMultilineInsensitive :: QuasiQuoter

[reMultilineInsensitive| ... |], compiles a case-insensitive, multi-line RE

reBlockSensitive :: QuasiQuoter

[reMultilineInsensitive| ... |], compiles a case-sensitive, non-multi-line RE

reBlockInsensitive :: QuasiQuoter

[reMultilineInsensitive| ... |], compiles a case-insensitive, non-multi-line RE

reMS :: QuasiQuoter

[reMS| ... |] is a shorthand for [reMultilineSensitive| ... |]

reMI :: QuasiQuoter

[reMI| ... |] is a shorthand for [reMultilineInsensitive| ... |]

reBS :: QuasiQuoter

[reBS| ... |] is a shorthand for [reBlockSensitive| ... |]

reBI :: QuasiQuoter

[reBI| ... |] is a shorthand for [reBlockInsensitive| ... |]

re_ :: QuasiQuoter

[re_| ... |] compiles a RE to produce a function that takes the RE options (e.g., a SimpleREOptions value) and yields the RE compiled with those options. For example,

countMatches $ s *=~ [re_|[0-9a-f]+|] MultilineInsensitive

counts the number of hexadecimal digit strings in s, allowing for upper- or lower-case hex digits (which is entirely equivalent in this example to just using [reMultilineInsensitive|[0-9a-f]+|]).

The Ed Quasi Quoters

The -- | the [ed| ... /// ... |] quasi quoters; for example,

[ed|${y}([0-9]{4})-0*${m}([0-9]{2})-0*${d}([0-9]{2})///${d}/${m}/${y}|])

represents a SearchReplace that will convert a YYYY-MM-DD format date into a DD/MM/YYYY format date.

The only difference between these quasi quoters is the RE options that are set, using the same conventions as the [re| ... |] quasi quoters.

ed :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

edMultilineSensitive :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

edMultilineInsensitive :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

edBlockSensitive :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

edBlockInsensitive :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

edMS :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

edMI :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

edBS :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

edBI :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

ed_ :: QuasiQuoter

the [ed| ... /// ... |] quasi quoters

The cp Quasi Quoters

cp :: QuasiQuoter

quasi quoter for CaptureID: [cp|0|], [cp|0|], etc., indexing captures by classic positional numbers, and [cp|foo|], etc., referencing a named capture [re| ... ${foo}( ... ) ... |].

RE Macros Standard Environment

prelude :: Macros RE

the standard table of Macros used to compile REs (which can be extended or replace: see Text.RE.TestBench)

preludeEnv :: MacroEnv

the standard MacroEnv for this back end (see Text.RE.TestBench)

preludeTestsFailing :: [MacroID]

the macros in the standard environment that are failing their tests (checked by the test suite to be empty)

preludeTable :: String

a table the standard macros in markdown format

preludeSummary :: PreludeMacro -> String

a summary of the macros in the standard environment for this back end in plain text

preludeSources :: String

a listing of the RE text for each macro in the standard environment with all macros expanded to normal form

preludeSource :: PreludeMacro -> String

the prelude source of a given macro in the standard environment

IsRegex

The IsRegex class is used to abstract over the different regex back ends and the text types they work with -- see Text.RE.Tools.IsRegex for details.

module Text.RE.Tools.IsRegex

The IsRegex Instances

These module exports merely provide the IsRegex instances.