regex-tdfa-1.3.2.5: Pure Haskell Tagged DFA Backend for "Text.Regex" (regex-base)

Copyright | (c) Chris Kuklewicz 2007-2009
License | BSD-3-Clause
Maintainer | Andreas Abel
Stability | stable
Safe Haskell | None
Language | Haskell2010

Text.Regex.TDFA

Description

The Text.Regex.TDFA module provides a backend for regular expressions. It provides instances for the classes defined and documented in Text.Regex.Base and re-exported by this module. If you import this along with other backends then you should do so with qualified imports (with renaming for convenience).

This regex-tdfa package implements, correctly, POSIX extended regular expressions. It is highly unlikely that the `regex-posix` package on your operating system is correct, see http://www.haskell.org/haskellwiki/Regex_Posix for examples of your OS's bugs.

# Importing and using

Declare a dependency on the `regex-tdfa` library in your `.cabal` file:

    build-depends: regex-tdfa ^>= 1.3.2

In Haskell modules where you want to use regexes simply `import` this module:

    import Text.Regex.TDFA

# Basics

    >>> let emailRegex = "[a-zA-Z0-9+._-]+\\@[-a-zA-Z]+\\.[a-z]+"
    >>> "my email is first-name.lastname_1974@e-mail.com" =~ emailRegex :: Bool
    True

    >>> "invalid@mail@com" =~ emailRegex :: Bool
    False

    >>> "invalid@mail.COM" =~ emailRegex :: Bool
    False

    >>> "#@invalid.com" =~ emailRegex :: Bool
    False

    -- non-monadic
    λ> <to-match-against> =~ <regex>

    -- monadic, uses fail on lack of match
    λ> <to-match-against> =~~ <regex>

(`=~`) and (`=~~`) are polymorphic in their return type. This is so that regex-tdfa can pick the most efficient way to give you your result based on what you need. For instance, if all you want is to check whether the regex matched or not, there's no need to allocate a result string. If you only want the first match, rather than all the matches, then the matching engine can stop after finding a single hit.

This does mean, though, that you may sometimes have to explicitly specify the type you want, especially if you're trying things out at the REPL.

# Common use cases

## Get the first match

    -- returns empty string if no match
    a =~ b :: String  -- or ByteString, or Text...

    >>> "alexis-de-tocqueville" =~ "[a-z]+" :: String
    "alexis"

    >>> "alexis-de-tocqueville" =~ "[0-9]+" :: String
    ""

## Check if it matched at all

    a =~ b :: Bool

    >>> "alexis-de-tocqueville" =~ "[a-z]+" :: Bool
    True

## Get first match + text before/after

    -- if no match, will just return whole
    -- string in the first element of the tuple
    a =~ b :: (String, String, String)

    >>> "alexis-de-tocqueville" =~ "de" :: (String, String, String)
    ("alexis-","de","-tocqueville")

    >>> "alexis-de-tocqueville" =~ "kant" :: (String, String, String)
    ("alexis-de-tocqueville","","")

## Get first match + submatches

    -- same as above, but also returns a list of just submatches.
    -- submatch list is empty if regex doesn't match at all
    a =~ b :: (String, String, String, [String])

    >>> "div[attr=1234]" =~ "div\\[([a-z]+)=([^]]+)\\]" :: (String, String, String, [String])
    ("","div[attr=1234]","",["attr","1234"])

## Get all matches

    -- can also return Data.Array instead of List
    getAllTextMatches (a =~ b) :: [String]

    >>> getAllTextMatches ("john anne yifan" =~ "[a-z]+") :: [String]
    ["john","anne","yifan"]

    >>> getAllTextMatches ("* - . a + z" =~ "[--z]+") :: [String]
    ["-",".","a","z"]

# Feature support

This package does provide captured parenthesized subexpressions.

Depending on the text being searched this package supports Unicode. The `[Char]`, `Text`, `Text.Lazy`, and `(Seq Char)` text types support Unicode. The `ByteString` and `ByteString.Lazy` text types only support ASCII.

As of version 1.1.1 the following GNU extensions are recognized, all anchors:

- \` at beginning of entire text
- \' at end of entire text
- \< at beginning of word
- \> at end of word
- \b at either beginning or end of word
- \B at neither beginning nor end of word

The above are controlled by the `newSyntax` Bool in `CompOption`.

Where the "word" boundaries means between characters that are and are not in the [:word:] character class which contains [a-zA-Z0-9_]. Note that \< and \b may match before the entire text and \> and \b may match at the end of the entire text.

There is no locale support, so collating elements like [.ch.] are simply ignored and equivalence classes like [=a=] are converted to just [a]. The character classes like [:alnum:] are supported over ASCII only, valid classes are alnum, digit, punct, alpha, graph, space, blank, lower, upper, cntrl, print, xdigit, word.

    >>> getAllTextMatches ("john anne yifan" =~ "[[:lower:]]+") :: [String]
    ["john","anne","yifan"]

This package does not provide "basic" regular expressions. This package does not provide back references inside regular expressions.

The package does not provide Perl style regular expressions. Please look at the regex-pcre and pcre-light packages instead.

This package does not provide find-and-replace.

# Avoiding backslashes

If you find yourself writing a lot of regexes, take a look at raw-strings-qq. It'll let you write regexes without needing to escape all your backslashes.

    {-# LANGUAGE QuasiQuotes #-}

    import Text.RawString.QQ
    import Text.Regex.TDFA

    λ> "2 * (3 + 1) / 4" =~ [r|\([^)]+\)|] :: String
    "(3 + 1)"

Synopsis

- getVersion_Text_Regex_TDFA :: Version
- (=~) :: (RegexMaker Regex CompOption ExecOption source, RegexContext Regex source1 target) => source1 -> source -> target
- (=~~) :: (RegexMaker Regex CompOption ExecOption source, RegexContext Regex source1 target, MonadFail m) => source1 -> source -> m target
- data CompOption = CompOption {
  - caseSensitive :: Bool
  - multiline :: Bool
  - rightAssoc :: Bool
  - newSyntax :: Bool
  - lastStarGreedy :: Bool
  }
- data Regex
- data ExecOption = ExecOption {
  - captureGroups :: Bool
  }
- module Text.Regex.Base

# Documentation

getVersion_Text_Regex_TDFA :: Version Source #

(=~) :: (RegexMaker Regex CompOption ExecOption source, RegexContext Regex source1 target) => source1 -> source -> target Source #

This is the pure functional matching operator. If the target cannot be produced then some empty result will be returned. If there is an error in processing, then `error` will be called.

(=~~) :: (RegexMaker Regex CompOption ExecOption source, RegexContext Regex source1 target, MonadFail m) => source1 -> source -> m target Source #

This is the monadic matching operator. If a single match fails, then `fail` will be called.

data CompOption Source #

Control whether the pattern is multiline or case-sensitive like Text.Regex and whether to capture the subgroups (\1, \2, etc). Controls enabling extra anchor syntax.

Constructors

CompOption |

Fields

- caseSensitive :: Bool

  True in `blankCompOpt` and `defaultCompOpt`.

- multiline :: Bool

  False in `blankCompOpt`, True in `defaultCompOpt`. Compile for newline-sensitive matching.

  From regexp man page: "By default, newline is a completely ordinary character with no special meaning in either REs or strings. With this flag, inverted bracket expressions `[^` and `.` never match newline, a `^` anchor matches the null string after any newline in the string in addition to its normal function, and the `$` anchor matches the null string before any newline in the string in addition to its normal function."

- rightAssoc :: Bool

  True (and therefore right associative) in `blankCompOpt` and `defaultCompOpt`.

- newSyntax :: Bool

  False in `blankCompOpt`, True in `defaultCompOpt`. Enables the extended non-POSIX syntax described in Text.Regex.TDFA haddock documentation.

- lastStarGreedy :: Bool

  False by default. This is POSIX correct but it takes space and is slower. Setting this to True will improve performance, and should be done if you plan to set the `captureGroups` `ExecOption` to False.

#### Instances

Instances details

Read CompOption Source # |
Instance details Defined in Text.Regex.TDFA.Common Methods readsPrec :: Int -> ReadS CompOption Source # readList :: ReadS [CompOption] Source # readPrec :: ReadPrec CompOption Source # readListPrec :: ReadPrec [CompOption] Source #
Show CompOption Source # |
Instance details Defined in Text.Regex.TDFA.Common Methods showsPrec :: Int -> CompOption -> ShowS Source # show :: CompOption -> String Source # showList :: [CompOption] -> ShowS Source #
RegexOptions Regex CompOption ExecOption Source # |
Instance details Defined in Text.Regex.TDFA.Common Methods blankCompOpt :: CompOption Source # blankExecOpt :: ExecOption Source # defaultCompOpt :: CompOption Source # defaultExecOpt :: ExecOption Source # setExecOpts :: ExecOption -> Regex -> Regex Source # getExecOpts :: Regex -> ExecOption Source #
RegexMaker Regex CompOption ExecOption ByteString Source # |
Instance details Defined in Text.Regex.TDFA.ByteString Methods makeRegex :: ByteString -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex Source # makeRegexM :: MonadFail m => ByteString -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex Source #
RegexMaker Regex CompOption ExecOption ByteString Source # |
Instance details Defined in Text.Regex.TDFA.ByteString.Lazy Methods makeRegex :: ByteString -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex Source # makeRegexM :: MonadFail m => ByteString -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex Source #
RegexMaker Regex CompOption ExecOption Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text Methods makeRegex :: Text -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Text -> Regex Source # makeRegexM :: MonadFail m => Text -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Text -> m Regex Source #
RegexMaker Regex CompOption ExecOption Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text.Lazy Methods makeRegex :: Text -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Text -> Regex Source # makeRegexM :: MonadFail m => Text -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Text -> m Regex Source #
RegexMaker Regex CompOption ExecOption String Source # |
Instance details Defined in Text.Regex.TDFA.String Methods makeRegex :: String -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> String -> Regex Source # makeRegexM :: MonadFail m => String -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> String -> m Regex Source #
RegexMaker Regex CompOption ExecOption (Seq Char) Source # |
Instance details Defined in Text.Regex.TDFA.Sequence Methods makeRegex :: Seq Char -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Seq Char -> Regex Source # makeRegexM :: MonadFail m => Seq Char -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Seq Char -> m Regex Source #

data Regex Source #

The TDFA backend specific `Regex` type, used by this module's `RegexOptions` and `RegexMaker`.

#### Instances

Instances details

RegexLike Regex ByteString Source # |

Instance details

Defined in Text.Regex.TDFA.ByteString

Methods

matchOnce :: Regex -> ByteString -> Maybe MatchArray Source #

matchAll :: Regex -> ByteString -> [MatchArray] Source #

matchCount :: Regex -> ByteString -> Int Source #

matchTest :: Regex -> ByteString -> Bool Source #

matchAllText :: Regex -> ByteString -> [MatchText ByteString] Source #

matchOnceText :: Regex -> ByteString -> Maybe (ByteString, MatchText ByteString, ByteString) Source #

RegexLike Regex ByteString Source # |

Instance details

Defined in Text.Regex.TDFA.ByteString.Lazy

Methods

matchOnce :: Regex -> ByteString -> Maybe MatchArray Source #

matchAll :: Regex -> ByteString -> [MatchArray] Source #

matchCount :: Regex -> ByteString -> Int Source #

matchTest :: Regex -> ByteString -> Bool Source #

matchAllText :: Regex -> ByteString -> [MatchText ByteString] Source #

matchOnceText :: Regex -> ByteString -> Maybe (ByteString, MatchText ByteString, ByteString) Source #

RegexLike Regex Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text Methods matchOnce :: Regex -> Text -> Maybe MatchArray Source # matchAll :: Regex -> Text -> [MatchArray] Source # matchCount :: Regex -> Text -> Int Source # matchTest :: Regex -> Text -> Bool Source # matchAllText :: Regex -> Text -> [MatchText Text] Source # matchOnceText :: Regex -> Text -> Maybe (Text, MatchText Text, Text) Source #
RegexLike Regex Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text.Lazy Methods matchOnce :: Regex -> Text -> Maybe MatchArray Source # matchAll :: Regex -> Text -> [MatchArray] Source # matchCount :: Regex -> Text -> Int Source # matchTest :: Regex -> Text -> Bool Source # matchAllText :: Regex -> Text -> [MatchText Text] Source # matchOnceText :: Regex -> Text -> Maybe (Text, MatchText Text, Text) Source #
RegexLike Regex String Source # |

Instance details

Defined in Text.Regex.TDFA.String

Methods

matchOnce :: Regex -> String -> Maybe MatchArray Source #

matchAll :: Regex -> String -> [MatchArray] Source #

matchCount :: Regex -> String -> Int Source #

matchTest :: Regex -> String -> Bool Source #

matchAllText :: Regex -> String -> [MatchText String] Source #

matchOnceText :: Regex -> String -> Maybe (String, MatchText String, String) Source #

RegexContext Regex ByteString ByteString Source # |
Instance details Defined in Text.Regex.TDFA.ByteString Methods match :: Regex -> ByteString -> ByteString Source # matchM :: MonadFail m => Regex -> ByteString -> m ByteString Source #
RegexContext Regex ByteString ByteString Source # |
Instance details Defined in Text.Regex.TDFA.ByteString.Lazy Methods match :: Regex -> ByteString -> ByteString Source # matchM :: MonadFail m => Regex -> ByteString -> m ByteString Source #
RegexContext Regex Text Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text Methods match :: Regex -> Text -> Text Source # matchM :: MonadFail m => Regex -> Text -> m Text Source #
RegexContext Regex Text Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text.Lazy Methods match :: Regex -> Text -> Text Source # matchM :: MonadFail m => Regex -> Text -> m Text Source #
RegexContext Regex String String Source # |
Instance details Defined in Text.Regex.TDFA.String Methods match :: Regex -> String -> String Source # matchM :: MonadFail m => Regex -> String -> m String Source #
RegexOptions Regex CompOption ExecOption Source # |
Instance details Defined in Text.Regex.TDFA.Common Methods blankCompOpt :: CompOption Source # blankExecOpt :: ExecOption Source # defaultCompOpt :: CompOption Source # defaultExecOpt :: ExecOption Source # setExecOpts :: ExecOption -> Regex -> Regex Source # getExecOpts :: Regex -> ExecOption Source #
RegexMaker Regex CompOption ExecOption ByteString Source # |
Instance details Defined in Text.Regex.TDFA.ByteString Methods makeRegex :: ByteString -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex Source # makeRegexM :: MonadFail m => ByteString -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex Source #
RegexMaker Regex CompOption ExecOption ByteString Source # |
Instance details Defined in Text.Regex.TDFA.ByteString.Lazy Methods makeRegex :: ByteString -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex Source # makeRegexM :: MonadFail m => ByteString -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex Source #
RegexMaker Regex CompOption ExecOption Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text Methods makeRegex :: Text -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Text -> Regex Source # makeRegexM :: MonadFail m => Text -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Text -> m Regex Source #
RegexMaker Regex CompOption ExecOption Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text.Lazy Methods makeRegex :: Text -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Text -> Regex Source # makeRegexM :: MonadFail m => Text -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Text -> m Regex Source #
RegexMaker Regex CompOption ExecOption String Source # |
Instance details Defined in Text.Regex.TDFA.String Methods makeRegex :: String -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> String -> Regex Source # makeRegexM :: MonadFail m => String -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> String -> m Regex Source #
RegexMaker Regex CompOption ExecOption (Seq Char) Source # |
Instance details Defined in Text.Regex.TDFA.Sequence Methods makeRegex :: Seq Char -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Seq Char -> Regex Source # makeRegexM :: MonadFail m => Seq Char -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Seq Char -> m Regex Source #
RegexLike Regex (Seq Char) Source # |

Instance details

Defined in Text.Regex.TDFA.Sequence

Methods

matchOnce :: Regex -> Seq Char -> Maybe MatchArray Source #

matchAll :: Regex -> Seq Char -> [MatchArray] Source #

matchCount :: Regex -> Seq Char -> Int Source #

matchTest :: Regex -> Seq Char -> Bool Source #

matchAllText :: Regex -> Seq Char -> [MatchText (Seq Char)] Source #

matchOnceText :: Regex -> Seq Char -> Maybe (Seq Char, MatchText (Seq Char), Seq Char) Source #

RegexContext Regex (Seq Char) (Seq Char) Source # |
Instance details Defined in Text.Regex.TDFA.Sequence Methods match :: Regex -> Seq Char -> Seq Char Source # matchM :: MonadFail m => Regex -> Seq Char -> m (Seq Char) Source #

data ExecOption Source #

Constructors

ExecOption |

Fields

- captureGroups :: Bool

  True by default. Set to False to improve speed (and space).

#### Instances

Instances details

Read ExecOption Source # |
Instance details Defined in Text.Regex.TDFA.Common Methods readsPrec :: Int -> ReadS ExecOption Source # readList :: ReadS [ExecOption] Source # readPrec :: ReadPrec ExecOption Source # readListPrec :: ReadPrec [ExecOption] Source #
Show ExecOption Source # |
Instance details Defined in Text.Regex.TDFA.Common Methods showsPrec :: Int -> ExecOption -> ShowS Source # show :: ExecOption -> String Source # showList :: [ExecOption] -> ShowS Source #
RegexOptions Regex CompOption ExecOption Source # |
Instance details Defined in Text.Regex.TDFA.Common Methods blankCompOpt :: CompOption Source # blankExecOpt :: ExecOption Source # defaultCompOpt :: CompOption Source # defaultExecOpt :: ExecOption Source # setExecOpts :: ExecOption -> Regex -> Regex Source # getExecOpts :: Regex -> ExecOption Source #
RegexMaker Regex CompOption ExecOption ByteString Source # |
Instance details Defined in Text.Regex.TDFA.ByteString Methods makeRegex :: ByteString -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex Source # makeRegexM :: MonadFail m => ByteString -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex Source #
RegexMaker Regex CompOption ExecOption ByteString Source # |
Instance details Defined in Text.Regex.TDFA.ByteString.Lazy Methods makeRegex :: ByteString -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> ByteString -> Regex Source # makeRegexM :: MonadFail m => ByteString -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> ByteString -> m Regex Source #
RegexMaker Regex CompOption ExecOption Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text Methods makeRegex :: Text -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Text -> Regex Source # makeRegexM :: MonadFail m => Text -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Text -> m Regex Source #
RegexMaker Regex CompOption ExecOption Text Source # | Since: 1.3.1
Instance details Defined in Text.Regex.TDFA.Text.Lazy Methods makeRegex :: Text -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Text -> Regex Source # makeRegexM :: MonadFail m => Text -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Text -> m Regex Source #
RegexMaker Regex CompOption ExecOption String Source # |
Instance details Defined in Text.Regex.TDFA.String Methods makeRegex :: String -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> String -> Regex Source # makeRegexM :: MonadFail m => String -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> String -> m Regex Source #
RegexMaker Regex CompOption ExecOption (Seq Char) Source # |
Instance details Defined in Text.Regex.TDFA.Sequence Methods makeRegex :: Seq Char -> Regex Source # makeRegexOpts :: CompOption -> ExecOption -> Seq Char -> Regex Source # makeRegexM :: MonadFail m => Seq Char -> m Regex Source # makeRegexOptsM :: MonadFail m => CompOption -> ExecOption -> Seq Char -> m Regex Source #

module Text.Regex.Base