From: simonmar Date: Tue, 28 May 2002 10:38:50 +0000 (+0000) Subject: [project @ 2002-05-28 10:38:50 by simonmar] X-Git-Tag: nhc98-1-18-release~1007 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=1487a8e7d26ff432dea87e57164e66ff21c00f47;p=ghc-base.git [project @ 2002-05-28 10:38:50 by simonmar] Document Text.Regex.Posix and Text.Regex --- diff --git a/Text/Regex.hs b/Text/Regex.hs index 9551102..3dc0da9 100644 --- a/Text/Regex.hs +++ b/Text/Regex.hs @@ -8,12 +8,13 @@ -- Stability : experimental -- Portability : non-portable (only on platforms that provide a regex lib) -- --- Regular expression matching. --- Uses the POSIX regular expression interface in Text.Regex.Posix for now. +-- Regular expression matching. Uses the POSIX regular expression +-- interface in "Text.Regex.Posix". -- ----------------------------------------------------------------------------- module Text.Regex ( + -- * Regular expressions Regex, mkRegex, mkRegexWithOpts, @@ -25,12 +26,26 @@ import Prelude import qualified Text.Regex.Posix as RE import System.IO.Unsafe +-- | A compiled regular expression type Regex = RE.Regex +-- | Makes a regular expression with the default options (multi-line, +-- case-sensitive). The syntax of regular expressions is +-- otherwise that of @egrep@ (i.e. POSIX \"extended\" regular +-- expressions). mkRegex :: String -> Regex mkRegex s = unsafePerformIO (RE.regcomp s RE.regExtended) -mkRegexWithOpts :: String -> Bool -> Bool -> Regex +-- | Makes a regular expression, where the multi-line and +-- case-sensitve options can be changed from the default settings. +mkRegexWithOpts + :: String -- ^ The regular expression to compile + -> Bool -- ^ 'True' @<=>@ \'@^@\' and \'@$@\' match the beginning and + -- end of individual lines respectively, and \'.\' does /not/ + -- match the newline character. + -> Bool -- ^ 'True' @<=>@ matching is case-sensitive + -> Regex -- ^ Returns: the compiled regular expression + mkRegexWithOpts s single_line case_sensitive = unsafePerformIO (RE.regcomp s (RE.regExtended + newline + igcase)) where @@ -40,17 +55,30 @@ mkRegexWithOpts s single_line case_sensitive igcase | case_sensitive = 0 | otherwise = RE.regIgnoreCase -matchRegex :: Regex -> String -> Maybe [String] +-- | Match a regular expression against a string +matchRegex + :: Regex -- ^ The regular expression + -> String -- ^ The string to match against + -> Maybe [String] -- ^ Returns: @'Just' strs@ if the match succeeded + -- (and @strs@ is the list of subexpression matches), + -- or 'Nothing' otherwise. matchRegex p str = case (unsafePerformIO (RE.regexec p str)) of Nothing -> Nothing Just (before, match, after, sub_strs) -> Just sub_strs -matchRegexAll :: Regex -> String -> - Maybe ( String, -- \$` - String, -- \$& - String, -- \$' - [String] -- \$1.. - ) +-- | Match a regular expression against a string, returning more information +-- about the match. +matchRegexAll + :: Regex -- ^ The regular expression + -> String -- ^ The string to match against + -> Maybe ( String, String, String, [String] ) + -- ^ Returns: 'Nothing' if the match failed, or: + -- + -- > Just ( everything before match, + -- > portion matched, + -- > everything after the match, + -- > subexpression matches ) + matchRegexAll p str = unsafePerformIO (RE.regexec p str) diff --git a/Text/Regex/Posix.hsc b/Text/Regex/Posix.hsc index 8c84dbd..e2f243b 100644 --- a/Text/Regex/Posix.hsc +++ b/Text/Regex/Posix.hsc @@ -1,23 +1,32 @@ ----------------------------------------------------------------------------- -- | -- Module : Text.Regex.Posix --- Copyright : (c) The University of Glasgow 2001 --- License : BSD-style (see the file libraries/core/LICENSE) +-- Copyright : (c) The University of Glasgow 2002 +-- License : BSD-style (see the file libraries/base/LICENSE) -- -- Maintainer : libraries@haskell.org -- Stability : experimental --- Portability : non-portable (only on platforms that provide POSIX regexps) +-- Portability : non-portable (needs POSIX regexps) -- -- Interface to the POSIX regular expression library. --- ToDo: should have an interface using PackedStrings. -- ----------------------------------------------------------------------------- +-- ToDo: should have an interface using PackedStrings. + module Text.Regex.Posix ( + -- * The @Regex@ type Regex, -- abstract + -- * Compiling a regular expression regcomp, -- :: String -> Int -> IO Regex + -- ** Flags for regcomp + regExtended, -- (flag to regcomp) use extended regex syntax + regIgnoreCase, -- (flag to regcomp) ignore case when matching + regNewline, -- (flag to regcomp) '.' doesn't match newline + + -- * Matching a regular expression regexec, -- :: Regex -- pattern -- -> String -- string to match -- -> IO (Maybe (String, -- everything before match @@ -25,9 +34,6 @@ module Text.Regex.Posix ( -- String, -- everything after match -- [String])) -- subexpression matches - regExtended, -- (flag to regcomp) use extended regex syntax - regIgnoreCase, -- (flag to regcomp) ignore case when matching - regNewline -- (flag to regcomp) '.' doesn't match newline ) where #include @@ -38,12 +44,17 @@ import Prelude import Foreign import Foreign.C +-- | A compiled regular expression newtype Regex = Regex (ForeignPtr CRegex) -- ----------------------------------------------------------------------------- -- regcomp -regcomp :: String -> Int -> IO Regex +-- | Compiles a regular expression +regcomp + :: String -- ^ The regular expression to compile + -> Int -- ^ Flags (summed together) + -> IO Regex -- ^ Returns: the compiled regular expression regcomp pattern flags = do regex_ptr <- mallocBytes (#const sizeof(regex_t)) regex_fptr <- newForeignPtr regex_ptr (regfree regex_ptr) @@ -62,12 +73,17 @@ regfree p_regex = do -- ----------------------------------------------------------------------------- -- regexec -regexec :: Regex -- pattern - -> String -- string to match - -> IO (Maybe (String, -- everything before match - String, -- matched portion - String, -- everything after match - [String])) -- subexpression matches +-- | Matches a regular expression against a string +regexec :: Regex -- ^ Compiled regular expression + -> String -- ^ String to match against + -> IO (Maybe (String, String, String, [String])) + -- ^ Returns: 'Nothing' if the regex did not match the + -- string, or: + -- + -- > 'Just' (everything before match, + -- > matched portion, + -- > everything after match, + -- > subexpression matches) regexec (Regex regex_fptr) str = do withCString str $ \cstr -> do