d39261b3a6578738900a4f8c03f69b36fde54bb4
[packages/haskell2010.git] / System / IO / Error.hs
1 #if __GLASGOW_HASKELL__ >= 701
2 {-# LANGUAGE Safe #-}
3 #endif
4
5 module System.IO.Error (
6 -- * I\/O errors
7 IOError, -- = IOException
8
9 userError, -- :: String -> IOError
10
11 mkIOError, -- :: IOErrorType -> String -> Maybe Handle
12 -- -> Maybe FilePath -> IOError
13
14 annotateIOError, -- :: IOError -> String -> Maybe Handle
15 -- -> Maybe FilePath -> IOError
16
17 -- ** Classifying I\/O errors
18 isAlreadyExistsError, -- :: IOError -> Bool
19 isDoesNotExistError,
20 isAlreadyInUseError,
21 isFullError,
22 isEOFError,
23 isIllegalOperation,
24 isPermissionError,
25 isUserError,
26
27 -- ** Attributes of I\/O errors
28 ioeGetErrorString, -- :: IOError -> String
29 ioeGetHandle, -- :: IOError -> Maybe Handle
30 ioeGetFileName, -- :: IOError -> Maybe FilePath
31
32 -- * Types of I\/O error
33 IOErrorType, -- abstract
34
35 alreadyExistsErrorType, -- :: IOErrorType
36 doesNotExistErrorType,
37 alreadyInUseErrorType,
38 fullErrorType,
39 eofErrorType,
40 illegalOperationErrorType,
41 permissionErrorType,
42 userErrorType,
43
44 -- * Throwing and catching I\/O errors
45
46 ioError, -- :: IOError -> IO a
47
48 catch, -- :: IO a -> (IOError -> IO a) -> IO a
49 try -- :: IO a -> IO (Either IOError a)
50
51 ) where
52
53 import qualified "base" Control.Exception as Exception
54 import "base" System.IO.Error hiding (IOError)
55 import qualified "base" System.IO.Error as Base
56 import Prelude hiding (IOError,catch)
57
58 -- | Errors of type 'IOError' are used by the 'IO' monad. This is an
59 -- abstract type; the module "System.IO.Error" provides functions to
60 -- interrogate and construct values of type 'IOError'.
61 type IOError = Base.IOError
62
63 -- SDM: duplicated docs for catch and try, omitting the part about non-IO
64 -- exceptions.
65
66 -- | The 'catch' function establishes a handler that receives any 'IOError'
67 -- raised in the action protected by 'catch'. An 'IOError' is caught by
68 -- the most recent handler established by 'catch'. These handlers are
69 -- not selective: all 'IOError's are caught. Exception propagation
70 -- must be explicitly provided in a handler by re-raising any unwanted
71 -- exceptions. For example, in
72 --
73 -- > f = catch g (\e -> if IO.isEOFError e then return [] else ioError e)
74 --
75 -- the function @f@ returns @[]@ when an end-of-file exception
76 -- (cf. 'System.IO.Error.isEOFError') occurs in @g@; otherwise, the
77 -- exception is propagated to the next outer handler.
78 --
79 -- When an exception propagates outside the main program, the Haskell
80 -- system prints the associated 'IOError' value and exits the program.
81 --
82 catch :: IO a -> (IOError -> IO a) -> IO a
83 catch = Exception.catch
84
85 -- | The construct 'try' @comp@ exposes IO errors which occur within a
86 -- computation, and which are not fully handled.
87 --
88 try :: IO a -> IO (Either IOError a)
89 try = Exception.try