From d7019a562d5e862476d55d1c0721fd6c4e793c28 Mon Sep 17 00:00:00 2001 From: Ross Paterson Date: Sun, 10 Sep 2006 11:52:59 +0000 Subject: [PATCH] doc tweaks, including more precise equations for evaluate --- Control/Exception.hs | 4 ++-- GHC/Exception.lhs | 8 +++++--- GHC/IOBase.lhs | 4 ++-- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/Control/Exception.hs b/Control/Exception.hs index f351f87..d789f06 100644 --- a/Control/Exception.hs +++ b/Control/Exception.hs @@ -152,7 +152,7 @@ import Data.Dynamic -- argument. Otherwise, the result is returned as normal. For example: -- -- > catch (openFile f ReadMode) --- > (\e -> hPutStr stderr (\"Couldn\'t open \"++f++\": \" ++ show e)) +-- > (\e -> hPutStr stderr ("Couldn't open "++f++": " ++ show e)) -- -- For catching exceptions in pure (non-'IO') expressions, see the -- function 'evaluate'. @@ -251,7 +251,7 @@ mapException f v = unsafePerformIO (catch (evaluate v) -- @('Right' a)@ if no exception was raised, or @('Left' e)@ if an -- exception was raised and its value is @e@. -- --- > try a = catch (Right \`liftM\` a) (return . Left) +-- > try a = catch (Right `liftM` a) (return . Left) -- -- Note: as with 'catch', it is only polite to use this variant if you intend -- to re-throw the exception after performing whatever cleanup is needed. diff --git a/GHC/Exception.lhs b/GHC/Exception.lhs index 0f9223d..073e7a9 100644 --- a/GHC/Exception.lhs +++ b/GHC/Exception.lhs @@ -106,10 +106,12 @@ unblock (IO io) = IO $ unblockAsyncExceptions# io -- the 'IO' monad. It can be used to order evaluation with respect to -- other 'IO' operations; its semantics are given by -- --- > evaluate undefined `seq` return () ==> return () --- > catch (evaluate undefined) (\e -> return ()) ==> return () +-- > evaluate x `seq` y ==> y +-- > evaluate x `catch` f ==> (return $! x) `catch` f +-- > evaluate x >>= f ==> (return $! x) >>= f -- --- NOTE: @(evaluate a)@ is /not/ the same as @(a \`seq\` return a)@. +-- /Note:/ the first equation implies that @(evaluate x)@ is /not/ the +-- same as @(return $! x)@. evaluate :: a -> IO a evaluate a = IO $ \s -> case a `seq` () of () -> (# s, a #) -- NB. can't write diff --git a/GHC/IOBase.lhs b/GHC/IOBase.lhs index 499899a..3442677 100644 --- a/GHC/IOBase.lhs +++ b/GHC/IOBase.lhs @@ -815,8 +815,8 @@ throw exception = raise# exception -- Although 'throwIO' has a type that is an instance of the type of 'throw', the -- two functions are subtly different: -- --- > throw e `seq` return () ===> throw e --- > throwIO e `seq` return () ===> return () +-- > throw e `seq` x ===> throw e +-- > throwIO e `seq` x ===> x -- -- The first example will cause the exception @e@ to be raised, -- whereas the second one won\'t. In fact, 'throwIO' will only cause -- 1.7.10.4