-- 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,
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
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)
-----------------------------------------------------------------------------
-- |
-- 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
-- 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 <sys/types.h>
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)
-- -----------------------------------------------------------------------------
-- 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
projects / ghc-base.git / commitdiff