X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=Text%2FRegex.hs;h=a0d724e3d9c3ce74a79fdc9367f0a86ceace4e31;hb=693255e8d7c52e0e6e88e6b9c112ae123877a6a8;hp=43a73a307db1526f2cdd5d6402f3ff89d798641c;hpb=9fa9bc17072a58c0bae2cce4764d38677e96ac29;p=ghc-base.git

diff --git a/Text/Regex.hs b/Text/Regex.hs
index 43a73a3..a0d724e 100644
--- a/Text/Regex.hs
+++ b/Text/Regex.hs
@@ -2,20 +2,19 @@
 -- |
 -- Module      :  Text.Regex
 -- Copyright   :  (c) The University of Glasgow 2001
--- License     :  BSD-style (see the file libraries/core/LICENSE)
+-- License     :  BSD-style (see the file libraries/base/LICENSE)
 -- 
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
 -- Portability :  non-portable (only on platforms that provide a regex lib)
 --
--- $Id: Regex.hs,v 1.2 2002/04/24 16:31:46 simonmar Exp $
---
--- 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,14 +24,26 @@ module Text.Regex (
 
 import Prelude
 import qualified Text.Regex.Posix as RE
+import Text.Regex.Posix ( Regex )
 import System.IO.Unsafe
 
-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
@@ -42,17 +53,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)