diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +# 1.2.3.2 + +* Significantly improved documentation (h/t William Yao). + # 1.2.3.1 * Compatibility with `containers-0.6`. @@ -37,7 +41,7 @@ # 1.1.4 -fixed +fixed # 1.1.3 diff --git a/Text/Regex/TDFA.hs b/Text/Regex/TDFA.hs --- a/Text/Regex/TDFA.hs +++ b/Text/Regex/TDFA.hs @@ -1,4 +1,4 @@ -{-| +{-| The "Text.Regex.TDFA" module provides a backend for regular expressions. It provides instances for the classes defined and @@ -12,13 +12,114 @@ for examples of your OS's bugs. += Importing and using + +Add to your package.yaml/cabal file: + +> dependencies: +> - regex-tdfa + +In modules where you need to use regexes: + +> import Text.Regex.TDFA + +Note that regex-tdfa does not provide support for @Text@ by default. +If you need this functionality, add +as a dependency and @import Text.Regex.TDFA.Text ()@. + += Basics + +@ +λ> let emailRegex = "[a-zA-Z0-9+.\_-]+\@[a-zA-Z-]+\\\\.[a-z]+" +λ> "my email is email@email.com" '=~' emailRegex :: Bool +>>> True + +/-- non-monadic/ +λ> \ '=~' \ + +/-- monadic, uses 'fail' on lack of match/ +λ> \ '=~~' \ +@ + +('=~') 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"] +@ + += Feature support + This package does provide captured parenthesized subexpressions. Depending on the text being searched this package supports Unicode. -The [Char] and (Seq Char) text types support Unicode. The ByteString -and ByteString.Lazy text types only support ASCII. It is possible to -support utf8 encoded ByteString.Lazy by using regex-tdfa and -regex-tdfa-utf8 packages together (required the utf8-string package). +The @[Char]@ and @(Seq Char)@ text types support Unicode. The @ByteString@ +and @ByteString.Lazy@ text types only support ASCII. It is possible to +support utf8 encoded @ByteString.Lazy@ by using regex-tdfa and + +packages together (required the utf8-string package). As of version 1.1.1 the following GNU extensions are recognized, all anchors: @@ -47,7 +148,26 @@ 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. +look at the +and 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 +. 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)" +@ -} diff --git a/Text/Regex/TDFA/ByteString.hs b/Text/Regex/TDFA/ByteString.hs --- a/Text/Regex/TDFA/ByteString.hs +++ b/Text/Regex/TDFA/ByteString.hs @@ -1,6 +1,6 @@ -{-| +{-| This modules provides 'RegexMaker' and 'RegexLike' instances for using -'ByteString' with the DFA backend ("Text.Regex.Lib.WrapDFAEngine" and +@ByteString@ with the DFA backend ("Text.Regex.Lib.WrapDFAEngine" and "Text.Regex.Lazy.DFAEngineFPS"). This module is usually used via import "Text.Regex.TDFA". @@ -44,7 +44,7 @@ matchCount r s = length (matchAll r' s) where r' = r { regex_execOptions = (regex_execOptions r) {captureGroups = False} } matchTest = Tester.matchTest - matchOnceText regex source = + matchOnceText regex source = fmap (\ma -> let (o,l) = ma!0 in (B.take o source ,fmap (\ol@(off,len) -> (B.take len (B.drop off source),ol)) ma diff --git a/Text/Regex/TDFA/ByteString/Lazy.hs b/Text/Regex/TDFA/ByteString/Lazy.hs --- a/Text/Regex/TDFA/ByteString/Lazy.hs +++ b/Text/Regex/TDFA/ByteString/Lazy.hs @@ -1,6 +1,6 @@ -{-| +{-| This modules provides 'RegexMaker' and 'RegexLike' instances for using -'ByteString' with the DFA backend ("Text.Regex.Lib.WrapDFAEngine" and +@ByteString@ with the DFA backend ("Text.Regex.Lib.WrapDFAEngine" and "Text.Regex.Lazy.DFAEngineFPS"). This module is usually used via import "Text.Regex.TDFA". @@ -45,7 +45,7 @@ matchCount r s = length (matchAll r' s) where r' = r { regex_execOptions = (regex_execOptions r) {captureGroups = False} } matchTest = Tester.matchTest - matchOnceText regex source = + matchOnceText regex source = fmap (\ma -> let (o32,l32) = ma!0 o = fi o32 @@ -64,7 +64,7 @@ let (off0,len0) = x!0 trans pair@(off32,len32) = (L.take (fi len32) (L.drop (fi (off32-i)) t),pair) t' = L.drop (fi (off0+len0-i)) t - in amap trans x : seq t' (go (off0+len0) t' xs) + in amap trans x : seq t' (go (off0+len0) t' xs) in go 0 source (matchAll regex source) fi :: (Integral a, Num b) => a -> b diff --git a/Text/Regex/TDFA/Sequence.hs b/Text/Regex/TDFA/Sequence.hs --- a/Text/Regex/TDFA/Sequence.hs +++ b/Text/Regex/TDFA/Sequence.hs @@ -1,6 +1,6 @@ -{-| +{-| This modules provides 'RegexMaker' and 'RegexLike' instances for using -'ByteString' with the DFA backend ("Text.Regex.Lib.WrapDFAEngine" and +@ByteString@ with the DFA backend ("Text.Regex.Lib.WrapDFAEngine" and "Text.Regex.Lazy.DFAEngineFPS"). This module is usually used via import "Text.Regex.TDFA". @@ -49,7 +49,7 @@ matchCount r s = length (matchAll r' s) where r' = r { regex_execOptions = (regex_execOptions r) {captureGroups = False} } matchTest = Tester.matchTest - matchOnceText regex source = + matchOnceText regex source = fmap (\ma -> let (o,l) = ma!0 in (before o source ,fmap (\ol -> (extract ol source,ol)) ma diff --git a/regex-tdfa.cabal b/regex-tdfa.cabal --- a/regex-tdfa.cabal +++ b/regex-tdfa.cabal @@ -1,5 +1,5 @@ Name: regex-tdfa -Version: 1.2.3.1 +Version: 1.2.3.2 License: BSD3 License-File: LICENSE Copyright: Copyright (c) 2007, Christopher Kuklewicz @@ -11,7 +11,13 @@ Synopsis: Replaces/Enhances Text.Regex Description: A new all Haskell "tagged" DFA regex engine, inspired by libtre Category: Text -Tested-With: GHC == 7.6.3, GHC == 7.8.4, GHC == 7.10.3, GHC == 8.0.1, GHC == 8.2.2, GHC == 8.4.1 +Tested-With: GHC==7.6.3 + , GHC==7.8.4 + , GHC==7.10.3 + , GHC==8.0.2 + , GHC==8.2.2 + , GHC==8.4.4 + , GHC==8.6.4 Build-Type: Simple extra-source-files: CHANGELOG.md @@ -26,7 +32,7 @@ default: False manual: True -library +library Build-Depends: array >= 0.4 && < 0.6 , base >= 4 && < 5 , bytestring >= 0.10 && < 0.11