940237656b9bd42d7d2acb813ed69c3514e91752
[haskell-report.git] / report / io.verb
1 %**<title>The Haskell 98 Library Report: Input/Output</title>
2 %**~header
3 \section{Input/Output}
4 \label{IO}
5 \index{input/output}
6 \index{I/O}
7 \indextt{IO}
8
9 % Gotta break the figure ...
10 \outline{
11 \inputHS{lib-hdrs/IO}
12 }
13 \outline{
14 \inputHS{lib-hdrs/IO1}
15 }
16
17 The monadic I/O system used in \Haskell{} is described by the
18 \Haskell{} language report.  Commonly used I/O functions such as
19 @print@ are part of the standard prelude and need not be explicitly
20 imported.  This library contain more advanced I/O features.
21 Some related operations on file systems are contained in the
22 @Directory@ library.
23
24 \subsection{I/O Errors}
25 \index{I/O errors}
26 \label{IOError}
27 Errors of type @IOError@ are used by the I/O monad.  This is an
28 abstract type; the library provides functions to interrogate and
29 construct values in @IOError@:\indextt{IOError}
30 \begin{itemize}
31 \item
32 @isAlreadyExistsError@\indextt{isAlreadyExistsError}
33  -- the operation failed because one of its
34 arguments already exists.
35 \item
36 @isDoesNotExistError@\indextt{isDoesNotExistError}
37  -- the operation failed because one of its
38 arguments does not exist.
39 \item
40 @isAlreadyInUseError@\indextt{isAlreadyInUseError}
41  -- the operation failed because one of its
42 arguments is a single-use resource, which is already being used (for
43 example, opening the same file twice for writing might give this
44 error).
45 \item
46 @isFullError@\indextt{isFullError}
47  -- the operation failed because the device is full.
48 \item
49 @isEOFError@\indextt{isEOFError}
50  -- the operation failed because the end of file
51 has been reached.
52 \item
53 @isIllegalOperation@\indextt{isIllegalOperation}
54  -- the operation is not possible.
55 \item
56 @isPermissionError@\indextt{isPermissionError}
57  -- the operation failed because the user does not
58 have sufficient operating system privilege to perform that operation.
59 \item
60 @isUserError@\indextt{isUserError}
61  -- a programmer-defined error value has been raised using
62 @fail@.\indextt{fail}
63 \end{itemize}
64 All these functions return a @Bool@, which is @True@ if
65 its argument is the corresponding kind of error, and @False@
66 otherwise.  
67
68 Any computation which returns an @IO@ result may fail with
69 @isIllegalOperation@.  Additional errors which could be raised by
70 an implementation are listed after the corresponding operation.  In
71 some cases, an implementation will not be able to distinguish between
72 the possible error causes.  In this case it should return
73 @isIllegalOperation@.
74
75 Three additional functions are provided to obtain information about an
76 error value.  These are @ioeGetHandle@\indextt{ioeGetHandle} which
77 returns @Just@~"hdl" if the error value refers to handle "hdl" and
78 @Nothing@ otherwise; @ioeGetFileName@\indextt{ioeGetFileName} which
79 returns @Just@~"name" if the error value refers to file "name", and
80 @Nothing@ otherwise; and @ioeGetErrorString@\indextt{ioeGetErrorString} which returns a
81 string.  For ``user'' errors (those which are raised using @fail@),
82 the string returned by @ioeGetErrorString@ is the argument that was passed to
83 @fail@; for all other errors, the string is implementation-dependent.
84
85 The @try@ function returns an error in a computation explicitly using
86 the @Either@ type.
87
88 The @bracket@ function 
89 captures a common allocate, compute, deallocate idiom in which the
90 deallocation step must occur even in the case of an error during
91 computation.  This is similar to try-catch-finally in Java.
92 % Inline the code here since there's no other functions in IO that
93 % are not primitive.
94
95
96
97 \subsection{Files and Handles}
98 \Haskell{} interfaces to the external world through an abstract {\em file
99 system}\index{file system}.  This file system is a collection of named {\em file
100 system objects}, which may be organised
101 in {\em directories}\index{directories} (see @Directory@).  
102 In some implementations, directories may themselves be file system
103 objects and could be entries in other directories.  For simplicity,
104 any non-directory file system object is termed a {\em file}\index{file},
105 although it could in fact be a communication channel, or any other
106 object recognised by the operating system.  {\em Physical
107 files}\index{physical file} are 
108 persistent, ordered files, and normally reside on disk.
109
110 File and directory names are values of type @String@, whose precise
111 meaning is operating system dependent.  Files can be opened, yielding
112 a handle which can then be used to operate on the contents of that
113 file.
114
115 \label{Handles}
116 \index{handles}
117
118 \Haskell{} defines operations to read and write characters from and to files,
119 represented by values of type @Handle@.  Each value of this type is a {\em
120 handle}: a record used by the \Haskell{} run-time system to {\em manage} I/O
121 with file system objects.  A handle has at least the following properties:
122
123 \begin{itemize}
124 \item
125  whether it manages input or output or both;
126 \item
127  whether it is {\em open}, {\em closed} or {\em semi-closed};
128 \item
129  whether the object is seekable;
130 \item
131  whether buffering is disabled, or enabled on a line or block basis;
132 \item
133  a buffer (whose length may be zero).
134 \end{itemize}
135
136 Most handles will also have a current I/O position indicating where the next
137 input or output operation will occur.  A handle is {\em readable} if it
138 manages only input or both input and output; likewise, it is {\em writable} if
139 it manages only output or both input and output.  A handle is {\em open} when
140 first allocated.  Once it is closed it can no longer be used for either input
141 or output, though an implementation cannot re-use its storage while references
142 remain to it.  Handles are in the @Show@ and @Eq@ classes.  The string
143 produced by showing a handle is system dependent; it should include 
144 enough information to identify the handle for debugging.  A handle is
145 equal according to @==@ only to itself; no attempt
146 is made to compare the internal state of different handles for equality.
147
148 \subsubsection{Standard Handles}
149 \label{StandardHandles}
150 \index{standard handles}
151
152 Three handles are allocated during program initialisation.  The first
153 two (@stdin@\indextt{stdin} and @stdout@\indextt{stdout}) manage input or output from the \Haskell{}
154 program's standard input or output channel respectively.  The third
155 (@stderr@\indextt{stderr}) manages output to the standard error channel.  These
156 handles are initially open.
157
158 \subsubsection{Semi-Closed Handles}
159 \label{SemiClosed}
160 \index{semi-closed handles}
161
162 The operation "@hGetContents@ hdl"\indextt{hGetContents} (Section~\ref{hGetContents})
163 puts a handle "hdl" into an intermediate
164 state, {\em semi-closed}.  In this state, "hdl" is effectively closed,
165 but items are read from "hdl" on demand and accumulated in a special
166 list returned by @hGetContents@~"hdl".
167
168 Any operation that fails because a handle is
169 closed, also fails if a handle is semi-closed. The only exception is @hClose@.
170 A semi-closed handle becomes closed:
171 \begin{itemize}
172 \item
173 if  @hClose@ is applied to it;
174 \item
175 if an I/O error occurs when reading an item from the handle;
176 \item
177 or once the entire contents of the handle has been read.
178 \end{itemize}
179
180 Once a semi-closed handle becomes closed, the contents of the
181 associated list becomes fixed.  The contents of this final list is
182 only partially specified: it will contain at least all the items of
183 the stream that were evaluated prior to the handle becoming closed.
184
185 Any I/O errors encountered while a handle is semi-closed are simply
186 discarded.
187  
188 \subsubsection{File locking}
189
190 Implementations should enforce as far as possible, at least locally to the
191 \Haskell{} process, multiple-reader single-writer locking on files.
192 That is, {\em there may either be many handles on the same file which manage
193 input, or just one handle on the file which manages output}.  If any
194 open or semi-closed handle is managing a file for output, no new
195 handle can be allocated for that file.  If any open or semi-closed
196 handle is managing a file for input, new handles can only be allocated
197 if they do not manage output.  Whether two files are the same is
198 implementation-dependent, but they should normally be the same if they
199 have the same absolute path name and neither has been renamed, for
200 example.
201
202 {\em Warning}: the @readFile@ operation (Section~\ref{standard-io-functions})
203 holds a semi-closed handle on the file until the entire contents of the file have been
204 consumed.  It follows that an attempt to write to a file (using @writeFile@, for example)
205 that was earlier opened by @readFile@ will usually result in 
206 failure with @isAlreadyInUseError@.
207 \indextt{readFile}
208 \indextt{writeFile}
209
210
211 \subsection{Opening and Closing Files}
212 \label{OpeningClosing}
213
214 \subsubsection{Opening Files}
215 \label{Opening}
216 \index{opening a file}
217 \index{creating a file}
218
219 Computation @openFile@~"file"~"mode"\indextt{openFile} allocates and
220 returns a new, open handle to manage the file "file".
221 % I don't believe this footnote is technically correct -- functions
222 % are never computations IIRC: the computation is the action
223 % that occurs when the function is applied to a state token -- KH
224 % \footnote{We use
225 % the term "computation" instead of "function" here to separate
226 % functions which denote actions in the I/O monad from those outside the monad.}
227 It manages
228 input if "mode"\indextycon{IOMode} is @ReadMode@\indextt{ReadMode},
229 output if "mode" is @WriteMode@\indextt{WriteMode} or
230 @AppendMode@,\indextt{AppendMode} and both input and output if mode is
231 @ReadWriteMode@.\indextt{ReadWriteMode}
232
233 If the file does not exist and it is opened for output, it should be created
234 as a new file.  If "mode" is @WriteMode@ and the file already exists, then it
235 should be truncated to zero length.  Some operating systems delete empty
236 files, so there is no guarantee that the file will exist following an
237 @openFile@ with "mode" @WriteMode@ unless it is subsequently written to
238 successfully.  The handle is positioned at the end of the file if "mode" is
239 @AppendMode@, and otherwise at the beginning (in which case its internal I/O
240 position is 0).  The initial buffer mode is implementation-dependent.
241
242 If @openFile@ fails on a file opened for output, the file may still
243 have been created if it did not already exist.
244
245 {\em Error reporting}: the @openFile@ computation may fail with
246 @isAlreadyInUseError@ if the file is already open and cannot be
247 reopened;
248 @isDoesNotExistError@ if the file does not exist; or
249 @isPermissionError@ if the user does not have
250 permission to open the file.
251 \indextt{isAlreadyInUseError}
252 \indextt{isDoesNotExistError}
253 \indextt{isPermissionError}
254
255 \subsubsection{Closing Files}
256 \label{Closing}
257 \index{closing a file}
258
259 Computation @hClose@~"hdl"\indextt{hClose} makes handle "hdl" closed.  Before the
260 computation finishes, if "hdl" is writable its buffer is flushed as
261 for @hFlush@.
262 Performing @hClose@ on a handle that has already been closed has no effect; 
263 doing so not an error.  All other operations on a closed handle will fail.
264 If @hClose@ fails for any reason, any further operations (apart from @hClose@) on the 
265 handle will still fail as if "hdl" had been successfully closed.
266
267 \subsection{Determining the Size of a File}
268 \label{FileSize}
269 \index{size of file}
270
271 For a handle "hdl" which is attached to a physical file, @hFileSize@\indextt{hFileSize}
272 "hdl" returns the size of that file in 8-bit bytes ("\geq" 0).
273
274 \subsubsection{Detecting the End of Input}
275 \label{EOF}
276 \index{end of file}
277
278 For a readable handle "hdl", computation @hIsEOF@~"hdl"\indextt{hIsEOF} returns @True@
279 if no further input can be taken from "hdl"; for a handle attached to a 
280 physical file this means that the current I/O position is equal to the length of the file.
281 Otherwise, it returns @False@.  The computation @isEOF@\indextt{isEOF} is identical,
282 except that it works only on @stdin@.
283
284 % The computation may fail with:
285 % \begin{itemize}
286 % \item
287 % @HardwareFault@
288 % A physical I/O error has occurred.
289 % [@EIO@]
290 % \item
291 % @ResourceExhausted@
292 % Insufficient resources are available to perform the operation.
293 % [@ENOMEM@]
294 % \item
295 % @IllegalOperation@
296 % The handle is not open for reading.
297 % \end{itemize}
298
299 \subsubsection{Buffering Operations}
300 \label{Buffering}
301 \index{file buffering}
302
303 Three kinds of buffering are supported: line-buffering, 
304 block-buffering or no-buffering.  These modes have the following effects.
305 For output, items are written out, or {\em flushed}, from the internal buffer 
306 according to the buffer mode:
307 \begin{itemize}
308 \item
309 {\bf line-buffering:}
310 the entire buffer is flushed whenever a newline is output, the
311 buffer overflows, a @hFlush@ is issued, or the handle is closed.
312 \item
313 {\bf block-buffering:}
314 the entire buffer is written out whenever it overflows, a @hFlush@ is
315 issued, or the handle is closed.
316 \item
317 {\bf no-buffering:}
318 output is written immediately, and never stored in the buffer.
319 \end{itemize}
320 An implementation is free to flush the buffer more frequently, but not 
321 less frequently, than
322 specified above.  The buffer is emptied as soon as it has been written out.
323
324 Similarly, input occurs according to the buffer mode for handle "hdl".
325 \begin{itemize}
326 \item
327 {\bf line-buffering:}
328 when the buffer for "hdl" is not empty, the next item is obtained from
329 the buffer; otherwise, when the buffer is empty, characters are read into
330 the buffer until the next newline character is encountered or the buffer is full.  No
331 characters are available until the newline character is available or the buffer is full.
332 \item
333 {\bf block-buffering:} 
334 when the buffer for "hdl" becomes empty, the
335 next block of data is read into the buffer.
336 \item
337 {\bf no-buffering:} 
338 the next input item is read and returned.  The @hLookAhead@\indextt{hLookAhead} 
339 operation (Section~\ref{hLookAhead}) implies that
340 even a no-buffered handle may require a one-character buffer.
341 \end{itemize}
342
343 For most implementations, physical files will normally be block-buffered 
344 and terminals will normally be line-buffered.
345
346 Computation @hSetBuffering@~"hdl"~"mode"\indextt{hSetBuffering} sets the
347 mode of buffering for handle "hdl" on subsequent reads and writes.
348 \begin{itemize}
349 \item
350 If "mode" is @LineBuffering@, line-buffering is
351 enabled if possible.
352 \item
353 If "mode" is @BlockBuffering@~"size", then block-buffering
354 is enabled if possible.  The size of the buffer is "n" items
355 if "size" is @Just @"n" and is otherwise implementation-dependent.
356 \item
357 If "mode" is @NoBuffering@, then buffering is disabled if possible.
358 \end{itemize}
359
360 If the buffer mode is changed from @BlockBuffering@ or
361 @LineBuffering@ to @NoBuffering@, then 
362 \begin{itemize}
363 \item
364 if "hdl" is writable, the buffer is flushed as for 
365 @hFlush@;
366 \item
367 if "hdl" is not writable, the contents of the buffer is discarded.
368 \end{itemize}
369
370 {\em Error reporting}: the @hSetBuffering@ computation may fail with
371 @isPermissionError@ if
372 the handle has already been used for reading or writing
373 and the implementation does not allow the buffering mode to
374 be changed.
375
376 Computation @hGetBuffering@~"hdl"\indextt{hGetBuffering} returns the current buffering mode
377 for "hdl".
378
379 The default buffering mode when a handle is opened is
380 implementation-dependent and may depend on the file system object which is
381 attached to that handle.
382
383 \subsubsection{Flushing Buffers}
384 \label{Flushing}
385 \index{flushing a file buffer}
386
387 Computation @hFlush@~"hdl"\indextt{hFlush} causes any items buffered for output in
388 handle "hdl" to be sent immediately to the operating system.
389
390 {\em Error reporting}: the @hFlush@ computation may fail with:
391 @isFullError@ if the device is full; @isPermissionError@ if a
392 system resource limit would be exceeded.  It is unspecified whether the
393 characters in the buffer are discarded or retained under these circumstances.
394
395 \subsection{Repositioning Handles}
396 \label{Seeking}
397 \index{random access files}
398 \index{seeking a file}
399
400 \subsubsection{Revisiting an I/O Position}
401
402 Computation @hGetPosn@~"hdl"\indextt{hGetPosn} returns the current I/O position of "hdl" as a
403 value of the abstract type @HandlePosn@.  If a call to "@hGetPosn@~h" returns a position "p",
404 then computation @hSetPosn@~"p"\indextt{hSetPosn} sets the
405 position of "h" to the position it held at the time of the call to @hGetPosn@.
406
407
408 {\em Error reporting}: the @hSetPosn@ computation may fail with:
409 @isPermissionError@ if a system resource limit would be exceeded.
410
411 \subsubsection{Seeking to a new Position}
412
413 Computation @hSeek@~"hdl"~"mode"~"i"\indextt{hSeek} sets the position of handle
414 "hdl" depending on "mode".\indextycon{SeekMode}  If "mode" is:
415 \begin{itemize}
416 \item
417 @AbsoluteSeek@:\indextt{AbsoluteSeek} the position of "hdl" is set to "i".
418 \item
419 @RelativeSeek@:\indextt{RelativeSeek} the position of "hdl" is set to offset "i" from
420 the current position.
421 \item
422 @SeekFromEnd@:\indextt{SeekFromEnd} the position of "hdl" is set to offset "i" from
423 the end of the file.
424 \end{itemize}
425 The offset is given in terms of 8-bit bytes.
426
427 If "hdl" is block- or line-buffered, then seeking to a position which is not
428 in the current buffer will first cause any items in the output buffer to be
429 written to the device, and then cause the input buffer to be discarded.  Some
430 handles may not be seekable (see @hIsSeekable@), or only support a subset of
431 the possible positioning operations (for instance, it may only be possible to
432 seek to the end of a tape, or to a positive offset from the beginning or
433 current position).  It is not possible to set a negative I/O position, or for
434 a physical file, an I/O position beyond the current end-of-file.
435
436 {\em Error reporting}:
437 the @hSeek@ computation may fail with:
438 @isPermissionError@ if a system resource limit would be exceeded.
439
440 \subsection{Handle Properties}
441 \label{Query}
442
443 The functions 
444 @hIsOpen@\indextt{hIsOpen}, 
445 @hIsClosed@\indextt{hIsClosed},
446 @hIsReadable@\indextt{hIsReadable},
447 @hIsWritable@\indextt{hIsWritable} and
448 @hIsSeekable@\indextt{hIsSeekable}
449 return information about the properties of a handle.
450 Each of these returns @True@ if the handle has the specified property, and
451 @False@ otherwise.
452
453
454 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
455 %%
456 %% Haskell 1.3 Text Input: LibReadTextIO
457 %%
458 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
459
460 \subsection{Text Input and Output}
461 \index{reading from a file}
462 %\indextt{LibReadTextIO}
463
464 Here we define a standard set of input operations for reading
465 characters and strings from text files, using handles.  Many of these
466 functions are generalizations of Prelude functions.  I/O in the
467 Prelude generally uses @stdin@ and @stdout@; here, handles are explicitly
468 specified by the I/O operation.
469
470 \subsubsection{Checking for Input}
471 \label{hReady}
472 \label{hWaitForInput}
473 \index{polling a handle for input}
474
475 Computation @hWaitForInput@~"hdl"~"t"\indextt{hWaitForInput} 
476 waits until input is available on handle "hdl".
477 It returns @True@ as soon as input is available on "hdl", or @False@ if no input is available
478 within "t" milliseconds.
479
480 Computation @hReady@~"hdl"\indextt{hReady} indicates whether at least one item is
481 available for input from handle "hdl".
482
483 {\em Error reporting}:
484 the @hWaitForInput@ and @hReady@ computations fail with
485 @isEOFError@ if the end of file has been reached.
486
487 \subsubsection{Reading Input}
488
489 Computation @hGetChar@~"hdl"\indextt{hGetChar} reads a character from
490 the file or channel managed by "hdl".
491
492 Computation @hGetLine@~"hdl"\indextt{hGetLine} reads a line from the file or
493 channel managed by "hdl". The Prelude's @getLine@ is a shorthand
494 for @hGetLine stdin@.
495
496 {\em Error reporting}:
497 the @hGetChar@ computation fails with
498 @isEOFError@ if the end of file has been reached.
499 The @hGetLine@ computation fails with @isEOFError@ if the end of file is encountered
500 when reading the {\em first} character of the line. If @hGetLine@ encounters
501 end-of-file at any other point while reading in a line, it is treated as
502 a line terminator and the (partial) line is returned.
503
504
505 \subsubsection{Reading Ahead}
506 \label{hLookAhead}
507 \index{lookahead}
508
509 Computation @hLookAhead@~"hdl"\indextt{hLookAhead} returns the next character from handle
510 "hdl" without removing it from the input buffer, blocking until a
511 character is available.
512
513 {\em Error reporting}:
514 the @hLookAhead@ computation may fail with:
515 @isEOFError@ if the end of file has been reached.
516
517 \subsubsection{Reading The Entire Input}
518 \label{hGetContents}
519 \index{get the contents of a file}
520
521 Computation @hGetContents@~"hdl"\indextt{hGetContents} returns the list of
522 characters corresponding to the unread portion of the channel or file managed
523 by "hdl", which is made semi-closed.
524
525 {\em Error reporting}:
526 the @hGetContents@ computation may fail with:
527 @isEOFError@ if the end of file has been reached.
528
529 \subsubsection{Text Output}
530
531 Computation @hPutChar@~"hdl"~"c"\indextt{hPutChar} writes the character "c" to the file
532 or channel managed by "hdl".  Characters may be buffered if buffering
533 is enabled for "hdl".
534
535 Computation @hPutStr@~"hdl"~"s"\indextt{hPutStr} writes the string
536 "s" to the file or channel managed by "hdl".
537
538 Computation @hPrint@~"hdl"~"t"\indextt{hPrint} writes the string representation of "t"
539 given by the @shows@ function to the file or channel managed by "hdl" and appends a newline.
540
541 {\em Error reporting}:
542 the @hPutChar@, @hPutStr@ and @hPrint@ computations may fail with:
543 @isFull@-@Error@ if the device is full;
544 or @isPermissionError@ if another system resource limit would be exceeded.
545
546
547
548 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
549 %%
550 %% Haskell 1.3 Examples
551 %%
552 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
553
554 \subsection{Examples}
555 \index{input/output examples}
556
557 Here are some simple examples to illustrate \Haskell{} I/O.
558
559 \subsubsection{Summing Two Numbers}
560
561 This program reads and sums two @Integer@s.
562 \bprog
563 @
564 import IO
565
566 main = do
567          hSetBuffering stdout NoBuffering            
568          putStr   "Enter an integer: "        
569          x1 <- readNum 
570          putStr   "Enter another integer: "          
571          x2 <- readNum                          
572          putStr  ("Their sum is " ++ show (x1+x2) ++ "\n")
573        where readNum :: IO Integer
574                 -- Providing a type signature avoids reliance on
575                 -- the defaulting rule to fix the type of x1,x2
576              readNum = readLn
577 @
578 \eprog
579
580 \subsubsection{Copying Files}
581
582 A simple program to create a copy of a file, with all lower-case
583 characters translated to upper-case.  This program will not allow a
584 file to be copied to itself.  This version uses character-level I/O.
585 Note that exactly two arguments must be supplied to the program.
586 \bprog
587 @
588 import IO
589 import System
590 import Char( toUpper )
591
592 main = do 
593          [f1,f2] <- getArgs
594          h1 <- openFile f1 ReadMode     
595          h2 <- openFile f2 WriteMode 
596          copyFile h1 h2            
597          hClose h1                  
598          hClose h2
599
600 copyFile h1 h2 = do
601                    eof <- hIsEOF h1
602                    if eof then return () else
603                       do
604                         c <- hGetChar h1
605                         hPutChar h2 (toUpper c)   
606                         copyFile h1 h2
607 @
608 \eprog
609
610 An equivalent but much shorter version, using string I/O is:
611 \bprog
612 @
613 import System
614 import Char( toUpper )
615
616 main = do
617          [f1,f2] <- getArgs
618          s <- readFile f1
619          writeFile f2 (map toUpper s)
620 @
621 \eprog
622
623 %       Not any more in Haskell 98!
624 % The @~@ used in the patterns above is a necessary consequence of the
625 % @do@-notation which has been used for the I/O operations.  In general,
626 % if the pattern on the left of any @<-@ fails to match, the value of
627 % the entire @do@-expression is defined to be the ``zero'' in the
628 % underlying monad.  However, since the @IO@ monad has no zero, the @~@
629 % is required in order to force the pattern to be irrefutable.  Without
630 % the @~@, a class error would occur because there is no instance of
631 % @IO@ for class @MonadZero@.
632
633 \subsection{Library @IO@}
634
635 \inputHS{lib-code/IO}
636
637 %**~footer