[project @ 2002-10-03 12:57:42 by panne]

[ghc-base.git] / Text / Regex / Posix.hsc

diff --git a/Text/Regex/Posix.hsc b/Text/Regex/Posix.hsc
index 1035518..8d2fc53 100644 (file)
--- a/Text/Regex/Posix.hsc
+++ b/Text/Regex/Posix.hsc
@@ -1,25 +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)
---
--- $Id: Posix.hsc,v 1.7 2002/04/24 16:31:47 simonmar Exp $
+-- 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
@@ -27,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 <sys/types.h>
@@ -40,36 +44,57 @@ 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
+#ifdef __HUGS__
+  regex_fptr <- mallocForeignPtrBytes (#const sizeof(regex_t))
+#else
   regex_ptr <- mallocBytes (#const sizeof(regex_t))
   regex_fptr <- newForeignPtr regex_ptr (regfree regex_ptr)
+#endif /* __HUGS__ */
   r <- withCString pattern $ \cstr ->
         withForeignPtr regex_fptr $ \p ->
            c_regcomp p cstr (fromIntegral flags)
+#ifdef __HUGS__
+  addForeignPtrFinalizer regex_fptr ptr_regfree
+#endif
   if (r == 0)
      then return (Regex regex_fptr)
      else error "Text.Regex.Posix.regcomp: error in pattern" -- ToDo
 
+#ifndef __HUGS__
 regfree :: Ptr CRegex -> IO ()
 regfree p_regex = do
   c_regfree p_regex
   free p_regex
+#endif /* __HUGS__ */
 
 -- -----------------------------------------------------------------------------
 -- 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
@@ -114,7 +139,7 @@ unpack string p_match = do
 -- Flags for regexec
 #enum Int,, \
        REG_NOTBOL, \
-       REG_NOTEOL \
+       REG_NOTEOL
 
 -- Return values from regexec
 #enum Int,, \
@@ -149,8 +174,13 @@ type CRegMatch = ()
 foreign import ccall unsafe "regcomp"
   c_regcomp :: Ptr CRegex -> CString -> CInt -> IO CInt
 
+#ifdef __HUGS__
+foreign import ccall  unsafe "&regfree"
+  ptr_regfree :: FunPtr (Ptr CRegex -> IO ())
+#else
 foreign import ccall  unsafe "regfree"
   c_regfree :: Ptr CRegex -> IO ()
+#endif /* __HUGS__ */
 
 foreign import ccall unsafe "regexec"
   c_regexec :: Ptr CRegex -> CString -> CSize