a1a8fcc5f7db9b9b25aa7bc3a88ebce6671f9ef8
[packages/haskell2010.git] / System / IO.hs
1 #if __GLASGOW_HASKELL__ >= 701
2 {-# LANGUAGE Safe #-}
3 #endif
4
5 module System.IO (
6 -- * The IO monad
7
8 IO, -- instance MonadFix
9 fixIO, -- :: (a -> IO a) -> IO a
10
11 -- * Files and handles
12
13 FilePath, -- :: String
14
15 Handle, -- abstract, instance of: Eq, Show.
16
17 -- ** Standard handles
18
19 -- | Three handles are allocated during program initialisation,
20 -- and are initially open.
21
22 stdin, stdout, stderr, -- :: Handle
23
24 -- * Opening and closing files
25
26 -- ** Opening files
27
28 withFile,
29 openFile, -- :: FilePath -> IOMode -> IO Handle
30 IOMode(ReadMode,WriteMode,AppendMode,ReadWriteMode),
31
32 -- ** Closing files
33
34 hClose, -- :: Handle -> IO ()
35
36 -- ** Special cases
37
38 -- | These functions are also exported by the "Prelude".
39
40 readFile, -- :: FilePath -> IO String
41 writeFile, -- :: FilePath -> String -> IO ()
42 appendFile, -- :: FilePath -> String -> IO ()
43
44 -- ** File locking
45
46 -- $locking
47
48 -- * Operations on handles
49
50 -- ** Determining and changing the size of a file
51
52 hFileSize, -- :: Handle -> IO Integer
53 hSetFileSize, -- :: Handle -> Integer -> IO ()
54
55 -- ** Detecting the end of input
56
57 hIsEOF, -- :: Handle -> IO Bool
58 isEOF, -- :: IO Bool
59
60 -- ** Buffering operations
61
62 BufferMode(NoBuffering,LineBuffering,BlockBuffering),
63 hSetBuffering, -- :: Handle -> BufferMode -> IO ()
64 hGetBuffering, -- :: Handle -> IO BufferMode
65 hFlush, -- :: Handle -> IO ()
66
67 -- ** Repositioning handles
68
69 hGetPosn, -- :: Handle -> IO HandlePosn
70 hSetPosn, -- :: HandlePosn -> IO ()
71 HandlePosn, -- abstract, instance of: Eq, Show.
72
73 hSeek, -- :: Handle -> SeekMode -> Integer -> IO ()
74 SeekMode(AbsoluteSeek,RelativeSeek,SeekFromEnd),
75 hTell, -- :: Handle -> IO Integer
76
77 -- ** Handle properties
78
79 -- | Each of these operations returns 'True' if the handle has the
80 -- the specified property, or 'False' otherwise.
81
82 hIsOpen, hIsClosed, -- :: Handle -> IO Bool
83 hIsReadable, hIsWritable, -- :: Handle -> IO Bool
84 hIsSeekable, -- :: Handle -> IO Bool
85
86 -- ** Terminal operations
87
88 hIsTerminalDevice, -- :: Handle -> IO Bool
89
90 hSetEcho, -- :: Handle -> Bool -> IO ()
91 hGetEcho, -- :: Handle -> IO Bool
92
93 -- ** Showing handle state
94 hShow, -- :: Handle -> IO String
95
96 -- * Text input and output
97
98 -- ** Text input
99
100 hWaitForInput, -- :: Handle -> Int -> IO Bool
101 hReady, -- :: Handle -> IO Bool
102 hGetChar, -- :: Handle -> IO Char
103 hGetLine, -- :: Handle -> IO [Char]
104 hLookAhead, -- :: Handle -> IO Char
105 hGetContents, -- :: Handle -> IO [Char]
106
107 -- ** Text output
108
109 hPutChar, -- :: Handle -> Char -> IO ()
110 hPutStr, -- :: Handle -> [Char] -> IO ()
111 hPutStrLn, -- :: Handle -> [Char] -> IO ()
112 hPrint, -- :: Show a => Handle -> a -> IO ()
113
114 -- ** Special cases for standard input and output
115
116 -- | These functions are also exported by the "Prelude".
117
118 interact, -- :: (String -> String) -> IO ()
119 putChar, -- :: Char -> IO ()
120 putStr, -- :: String -> IO ()
121 putStrLn, -- :: String -> IO ()
122 print, -- :: Show a => a -> IO ()
123 getChar, -- :: IO Char
124 getLine, -- :: IO String
125 getContents, -- :: IO String
126 readIO, -- :: Read a => String -> IO a
127 readLn, -- :: Read a => IO a
128
129 ) where
130
131 import "base" System.IO hiding (openFile, hWaitForInput)
132 import qualified "base" System.IO as Base
133
134 -- $locking
135 -- Implementations should enforce as far as possible, at least locally to the
136 -- Haskell process, multiple-reader single-writer locking on files.
137 -- That is, /there may either be many handles on the same file which manage input, or just one handle on the file which manages output/. If any
138 -- open or semi-closed handle is managing a file for output, no new
139 -- handle can be allocated for that file. If any open or semi-closed
140 -- handle is managing a file for input, new handles can only be allocated
141 -- if they do not manage output. Whether two files are the same is
142 -- implementation-dependent, but they should normally be the same if they
143 -- have the same absolute path name and neither has been renamed, for
144 -- example.
145 --
146 -- /Warning/: the 'readFile' operation holds a semi-closed handle on
147 -- the file until the entire contents of the file have been consumed.
148 -- It follows that an attempt to write to a file (using 'writeFile', for
149 -- example) that was earlier opened by 'readFile' will usually result in
150 -- failure with 'System.IO.Error.isAlreadyInUseError'.
151
152
153 -- SDM: custom verison of openFile docs removing reference to 'openBinaryFile'
154
155 -- | Computation 'openFile' @file mode@ allocates and returns a new, open
156 -- handle to manage the file @file@. It manages input if @mode@
157 -- is 'ReadMode', output if @mode@ is 'WriteMode' or 'AppendMode',
158 -- and both input and output if mode is 'ReadWriteMode'.
159 --
160 -- If the file does not exist and it is opened for output, it should be
161 -- created as a new file. If @mode@ is 'WriteMode' and the file
162 -- already exists, then it should be truncated to zero length.
163 -- Some operating systems delete empty files, so there is no guarantee
164 -- that the file will exist following an 'openFile' with @mode@
165 -- 'WriteMode' unless it is subsequently written to successfully.
166 -- The handle is positioned at the end of the file if @mode@ is
167 -- 'AppendMode', and otherwise at the beginning (in which case its
168 -- internal position is 0).
169 -- The initial buffer mode is implementation-dependent.
170 --
171 -- This operation may fail with:
172 --
173 -- * 'isAlreadyInUseError' if the file is already open and cannot be reopened;
174 --
175 -- * 'isDoesNotExistError' if the file does not exist; or
176 --
177 -- * 'isPermissionError' if the user does not have permission to open the file.
178 --
179 openFile :: FilePath -> IOMode -> IO Handle
180 openFile = Base.openFile
181
182 -- SDM: local version of docs for hWaitForInput, omitting GHC-specific notes.
183
184 -- If hWaitForInput finds anything in the Handle's buffer, it
185 -- immediately returns. If not, it tries to read from the underlying
186 -- OS handle. Notice that for buffered Handles connected to terminals
187 -- this means waiting until a complete line is available.
188
189 -- | Computation 'hWaitForInput' @hdl t@
190 -- waits until input is available on handle @hdl@.
191 -- It returns 'True' as soon as input is available on @hdl@,
192 -- or 'False' if no input is available within @t@ milliseconds. Note that
193 -- 'hWaitForInput' waits until one or more full /characters/ are available,
194 -- which means that it needs to do decoding, and hence may fail
195 -- with a decoding error.
196 --
197 -- If @t@ is less than zero, then @hWaitForInput@ waits indefinitely.
198 --
199 -- This operation may fail with:
200 --
201 -- * 'isEOFError' if the end of file has been reached.
202 --
203 -- * a decoding error, if the input begins with an invalid byte sequence
204 -- in this Handle's encoding.
205 --
206
207 hWaitForInput :: Handle -> Int -> IO Bool
208 hWaitForInput = Base.hWaitForInput