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