Copyright | (c) Aaron Stevens, 2014 |
---|---|
License | GPL2 |
Maintainer | bheklilr2@gmail.com |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
- module System.IO
- class Access io => HandleWriteAccess io where
- class Access io => HandleReadAccess io where
- hWaitForInput' :: Handle -> Int -> io Bool
- hGetChar' :: Handle -> io Char
- hGetLine' :: Handle -> io String
- hLookAhead' :: Handle -> io Char
- hGetContents' :: Handle -> io String
- hGetBuf' :: Handle -> Ptr a -> Int -> io Int
- hGetBufSome' :: Handle -> Ptr a -> Int -> io Int
- hGetBufNonBlocking' :: Handle -> Ptr a -> Int -> io Int
- class (HandleWriteAccess io, HandleReadAccess io) => HandleAccess io where
- hClose' :: Handle -> io ()
- hFileSize' :: Handle -> io Integer
- hSetFileSize' :: Handle -> Integer -> io ()
- hIsEOF' :: Handle -> io Bool
- hSetBuffering' :: Handle -> BufferMode -> io ()
- hGetBuffering' :: Handle -> io BufferMode
- hFlush' :: Handle -> io ()
- hGetPosn' :: Handle -> io HandlePosn
- hSetPosn' :: HandlePosn -> io ()
- hSeek' :: Handle -> SeekMode -> Integer -> io ()
- hTell' :: Handle -> io Integer
- hIsOpen' :: Handle -> io Bool
- hIsClosed' :: Handle -> io Bool
- hIsReadable' :: Handle -> io Bool
- hIsWritable' :: Handle -> io Bool
- hIsSeekable' :: Handle -> io Bool
- hIsTerminalDevice' :: Handle -> io Bool
- hSetEcho' :: Handle -> Bool -> io ()
- hGetEcho' :: Handle -> io Bool
- hShow' :: Handle -> io String
- hReady' :: Handle -> io Bool
- hSetEncoding' :: Handle -> TextEncoding -> io ()
- hGetEncoding' :: Handle -> io (Maybe TextEncoding)
- hSetNewlineMode' :: Handle -> NewlineMode -> io ()
- class Access io => StdInAccess io where
- class Access io => StdOutAccess io where
- class (StdInAccess io, StdOutAccess io) => StdIOAccess io where
- class FileReadAccess io where
- class Access io => FileWriteAccess io where
- writeFile' :: FilePath -> String -> io ()
- appendFile' :: FilePath -> String -> io ()
- class (HandleAccess io, FileReadAccess io, FileWriteAccess io) => FileAccess io where
- class Access io => TempFileAccess io where
- openTempFile' :: FilePath -> String -> io (FilePath, Handle)
- openBinaryTempFile' :: FilePath -> String -> io (FilePath, Handle)
- openTempFileWithDefaultPermissions' :: FilePath -> String -> io (FilePath, Handle)
- openBinaryTempFileWithDefaultPermissions' :: FilePath -> String -> io (FilePath, Handle)
- class Access io => TextEncodingAccess io where
- mkTextEncoding' :: String -> io TextEncoding
Documentation
module System.IO
class Access io => HandleWriteAccess io where Source
Provides access to Handle
write functions
hPutChar' :: Handle -> Char -> io () Source
Wraps hPutChar
Computation hPutChar'
hdl ch
writes the character ch
to the
file or channel managed by hdl
. Characters may be buffered if
buffering is enabled for hdl
.
This operation may fail with:
isFullError
if the device is full; orisPermissionError
if another system resource limit would be exceeded
hPutStr' :: Handle -> String -> io () Source
Wraps hPutStr
Computation hPutStr'
hdl s
writes the string s
to the file or
channel managed by hdl
This operation may fail with:
isFullError
if the device is full; orisPermissionError
if another system resource limit would be exceeded
hPutStrLn' :: Handle -> String -> io () Source
hPrint' :: Show a => Handle -> a -> io () Source
Wraps hPrint
Computation hPrint'
hdl t
writes the string representation of t
given by the shows
function to the file or channel managed
by hdl
and appends a newline.
This operation may fail with:
isFullError
if the device is full; orisPermissionError
if another system resource limit would be exceeded
hPutBuf' :: Handle -> Ptr a -> Int -> io () Source
Wraps hPutBuf
hPutBuf'
hdl buf count
writes count
8-bit bytes from the
buffer buf
to the handle hdl
. It returns ().
hPutBuf'
ignores any text encoding that applies to the Handle
,
writing the bytes directly to the underlying file or device.
hPutBuf'
ignores the prevailing TextEncoding
and
NewlineMode
on the Handle
, and writes bytes directly.
This operation may fail with:
ResourceVanished
if the handle is a pipe or socket, and the reading end is closed. (If this is a POSIX system, and the program has not asked to ignore SIGPIPE, then a SIGPIPE may be delivered instead, whose default action is to terminate the program).
hPutBufNonBlocking' :: Handle -> Ptr a -> Int -> io Int Source
Wraps hPutBufNonBlocking
hGetBufNonBlocking'
hdl buf count
reads data from the handle hdl
into the buffer buf
until either EOF is reached, or
count
8-bit bytes have been read, or there is no more data available
to read immediately.
hGetBufNonBlocking'
is identical to hGetBuf'
, except that it will
never block waiting for data to become available, instead it returns
only whatever data is available. To wait for data to arrive before
calling hGetBufNonBlocking'
, use hWaitForInput
.
If the handle is a pipe or socket, and the writing end
is closed, hGetBufNonBlocking'
will behave as if EOF was reached.
hGetBufNonBlocking'
ignores the prevailing TextEncoding
and
NewlineMode
on the Handle
, and reads bytes directly.
NOTE: on Windows, this function does not work correctly; it
behaves identically to hGetBuf'
.
class Access io => HandleReadAccess io where Source
Provides access to Handle
read functions
hWaitForInput' :: Handle -> Int -> io Bool Source
Wraps hWaitForInput
Computation hWaitForInput'
hdl t
waits until input is available on handle hdl
.
It returns True
as soon as input is available on hdl
,
or False
if no input is available within t
milliseconds. Note that
hWaitForInput'
waits until one or more full characters are available,
which means that it needs to do decoding, and hence may fail
with a decoding error.
If t
is less than zero, then hWaitForInput
waits indefinitely.
This operation may fail with:
isEOFError
if the end of file has been reached.- a decoding error, if the input begins with an invalid byte sequence in this Handle's encoding.
NOTE for GHC users: unless you use the -threaded
flag,
hWaitForInput t
where t >= 0
will block all other Haskell
threads for the duration of the call. It behaves like a
safe
foreign call in this respect.
hGetChar' :: Handle -> io Char Source
Wraps hGetChar
Computation hGetChar'
hdl
reads a character from the file or
channel managed by hdl
, blocking until a character is available.
This operation may fail with:
isEOFError
if the end of file has been reached.
hGetLine' :: Handle -> io String Source
Wraps hGetLine
Computation hGetLine'
hdl
reads a line from the file or
channel managed by hdl
.
This operation may fail with:
isEOFError
if the end of file is encountered when reading the first character of the line.
If hGetLine'
encounters end-of-file at any other point while reading
in a line, it is treated as a line terminator and the (partial)
line is returned.
hLookAhead' :: Handle -> io Char Source
Wraps hLookAhead
Computation hLookAhead
returns the next character from the handle
without removing it from the input buffer, blocking until a character
is available.
This operation may fail with:
isEOFError
if the end of file has been reached.
hGetContents' :: Handle -> io String Source
Wraps hGetContents
Computation hGetContents'
hdl
returns the list of characters
corresponding to the unread portion of the channel or file managed
by hdl
, which is put into an intermediate state, semi-closed.
In this state, hdl
is effectively closed,
but items are read from hdl
on demand and accumulated in a special
list returned by hGetContents'
hdl
.
Any operation that fails because a handle is closed,
also fails if a handle is semi-closed. The only exception is hClose'
.
A semi-closed handle becomes closed:
- if
hClose'
is applied to it; - if an I/O error occurs when reading an item from the handle;
- or once the entire contents of the handle has been read.
Once a semi-closed handle becomes closed, the contents of the associated list becomes fixed. The contents of this final list is only partially specified: it will contain at least all the items of the stream that were evaluated prior to the handle becoming closed.
Any I/O errors encountered while a handle is semi-closed are simply discarded.
This operation may fail with:
isEOFError
if the end of file has been reached.
hGetBuf' :: Handle -> Ptr a -> Int -> io Int Source
Wraps hGetBuf
hGetBuf
hdl buf count
reads data from the handle hdl
into the
buffer buf
until either EOF is reached or count
8-bit bytes have been
read. It returns the number of bytes actually read. This may be zero if
EOF was reached before any data was read (or if count
is zero).
hGetBuf
never raises an EOF exception, instead it returns a value
smaller than count
.
If the handle is a pipe or socket, and the writing end
is closed, hGetBuf
will behave as if EOF was reached.
hGetBuf
ignores the prevailing TextEncoding
and NewlineMode
on the Handle
, and reads bytes directly.
hGetBufSome' :: Handle -> Ptr a -> Int -> io Int Source
Wraps hGetBufSome
hGetBufSome
hdl buf count
reads data from the handle hdl
into the buffer buf
. If there is any data available to read,
then hGetBufSome
returns it immediately; it only blocks if there
is no data to be read.
It returns the number of bytes actually read. This may be zero if
EOF was reached before any data was read (or if count
is zero).
hGetBufSome
never raises an EOF exception, instead it returns a value
smaller than count
.
If the handle is a pipe or socket, and the writing end
is closed, hGetBufSome
will behave as if EOF was reached.
hGetBufSome
ignores the prevailing TextEncoding
and NewlineMode
on the Handle
, and reads bytes directly.
hGetBufNonBlocking' :: Handle -> Ptr a -> Int -> io Int Source
Wraps hGetBufNonBlocking
hGetBufNonBlocking
hdl buf count
reads data from the handle hdl
into the buffer buf
until either EOF is reached, or
count
8-bit bytes have been read, or there is no more data available
to read immediately.
hGetBufNonBlocking
is identical to hGetBuf
, except that it will
never block waiting for data to become available, instead it returns
only whatever data is available. To wait for data to arrive before
calling hGetBufNonBlocking
, use hWaitForInput
.
If the handle is a pipe or socket, and the writing end
is closed, hGetBufNonBlocking
will behave as if EOF was reached.
hGetBufNonBlocking
ignores the prevailing TextEncoding
and
NewlineMode
on the Handle
, and reads bytes directly.
NOTE: on Windows, this function does not work correctly; it
behaves identically to hGetBuf
.
class (HandleWriteAccess io, HandleReadAccess io) => HandleAccess io where Source
Combines the HandleWriteAccess
and HandleReadAccess
classes and adds
additional miscellaneous functions for Handle
manipulation
hClose' :: Handle -> io () Source
Wraps hClose
Computation hClose'
hdl
makes handle hdl
closed. Before the
computation finishes, if hdl
is writable its buffer is flushed as
for hFlush
.
Performing hClose'
on a handle that has already been closed has no
effect; doing so is not an error. All other operations on a closed
handle will fail. If hClose'
fails for any reason, any further
operations (apart from hClose'
) on the handle will still fail as if
hdl
had been successfully closed.
hFileSize' :: Handle -> io Integer Source
Wraps hFileSize
For a handle hdl
which attached to a physical file, hFileSize
hdl
returns the size of that file in 8-bit bytes.
hSetFileSize' :: Handle -> Integer -> io () Source
Wraps hSetFileSize
hSetFileSize'
hdl
size
truncates the physical file with handle
hdl
to size
bytes.
hIsEOF' :: Handle -> io Bool Source
Wraps hIsEOF
For a readable handle hdl
, hIsEOF'
hdl
returns
True
if no further input can be taken from hdl
or for a
physical file, if the current I/O position is equal to the length of
the file. Otherwise, it returns False
.
NOTE: hIsEOF'
may block, because it has to attempt to read from
the stream to determine whether there is any more data to be read.
hSetBuffering' :: Handle -> BufferMode -> io () Source
Wraps hSetBuffering
Computation hSetBuffering'
hdl mode
sets the mode of buffering for
handle hdl
on subsequent reads and writes.
If the buffer mode is changed from BlockBuffering
or
LineBuffering
to NoBuffering
, then
- if
hdl
is writable, the buffer is flushed as forhFlush'
; - if
hdl
is not writable, the contents of the buffer is discarded.
This operation may fail with:
isPermissionError
if the handle has already been used for reading or writing and the implementation does not allow the buffering mode to be changed.
hGetBuffering' :: Handle -> io BufferMode Source
Wraps hGetBuffering
Computation hGetBuffering'
hdl
returns the current buffering mode
hFlush' :: Handle -> io () Source
Wraps hFlush
The action hFlush'
hdl
causes any items buffered for output
in handle hdl
to be sent immediately to the operating system.
This operation may fail with:
isFullError
if the device is full;isPermissionError
if a system resource limit would be exceeded. It is unspecified whether the characters in the buffer are discarded or retained under these circumstances.
hGetPosn' :: Handle -> io HandlePosn Source
Wraps hGetPosn
Computation hGetPosn'
hdl
returns the current I/O position of
hdl
as a value of the abstract type HandlePosn
.
hSetPosn' :: HandlePosn -> io () Source
Wraps hSetPosn
If a call to hGetPosn'
hdl
returns a position p
,
then computation hSetPosn'
p
sets the position of hdl
to the position it held at the time of the call to hGetPosn'
.
This operation may fail with:
isPermissionError
if a system resource limit would be exceeded.
hSeek' :: Handle -> SeekMode -> Integer -> io () Source
Wraps hSeek
Computation hSeek'
hdl mode i
sets the position of handle
hdl
depending on mode
.
The offset i
is given in terms of 8-bit bytes.
If hdl
is block- or line-buffered, then seeking to a position which is
not in the current buffer will first cause any items in the output buffer
to be written to the device, and then cause the input buffer to be
discarded. Some handles may not be seekable (see hIsSeekable'
), or only
support a subset of the possible positioning operations (for instance, it
may only be possible to seek to the end of a tape, or to a positive
offset from the beginning or current position).
It is not possible to set a negative I/O position, or for
a physical file, an I/O position beyond the current end-of-file.
This operation may fail with:
isIllegalOperationError
if the Handle is not seekable, or does not support the requested seek mode.isPermissionError
if a system resource limit would be exceeded.
hTell' :: Handle -> io Integer Source
Wraps hTell
Computation hTell'
hdl
returns the current position of the
handle hdl
, as the number of bytes from the beginning of
the file. The value returned may be subsequently passed to
hSeek
to reposition the handle to the current position.
This operation may fail with:
isIllegalOperationError
if the Handle is not seekable.
hIsOpen' :: Handle -> io Bool Source
Wraps hIsOpen
hIsClosed' :: Handle -> io Bool Source
Wraps hIsClosed
hIsReadable' :: Handle -> io Bool Source
Wraps hIsReadable
hIsWritable' :: Handle -> io Bool Source
Wraps hIsWritable
hIsSeekable' :: Handle -> io Bool Source
Wraps hIsSeekable
hIsTerminalDevice' :: Handle -> io Bool Source
Wraps hIsTerminalDevice
Is the handle connected to a terminal?
hSetEcho' :: Handle -> Bool -> io () Source
Wraps hSetEcho
Set the echoing status of a handle connected to a terminal.
hGetEcho' :: Handle -> io Bool Source
Wraps hGetEcho
Get the echoing status of a handle connected to a terminal.
hShow' :: Handle -> io String Source
Wraps hShow
hShow'
is in the IO
monad, and gives more comprehensive output
than the (pure) instance of Show
for Handle
.
hReady' :: Handle -> io Bool Source
Wraps hReady
Computation hReady'
hdl
indicates whether at least one item is
available for input from handle hdl
.
This operation may fail with:
isEOFError
if the end of file has been reached.
hSetEncoding' :: Handle -> TextEncoding -> io () Source
Wraps hSetEncoding
The action hSetEncoding'
hdl
encoding
changes the text encoding
for the handle hdl
to encoding
. The default encoding when a Handle
is created is localeEncoding
, namely the default encoding for the
current locale.
To create a Handle
with no encoding at all, use openBinaryFile'
. To
stop further encoding or decoding on an existing Handle
, use
hSetBinaryMode'
.
hSetEncoding'
may need to flush buffered data in order to change
the encoding.
hGetEncoding' :: Handle -> io (Maybe TextEncoding) Source
Wraps hGetEncoding
Return the current TextEncoding
for the specified Handle
, or
Nothing
if the Handle
is in binary mode.
Note that the TextEncoding
remembers nothing about the state of
the encoder/decoder in use on this Handle
. For example, if the
encoding in use is UTF-16, then using hGetEncoding'
and
hSetEncoding'
to save and restore the encoding may result in an
extra byte-order-mark being written to the file.
hSetNewlineMode' :: Handle -> NewlineMode -> io () Source
Wraps hSetNewlineMode
Set the NewlineMode
on the specified Handle
. All buffered data is
flushed first.
class Access io => StdInAccess io where Source
Provides access to functions to read from stdin
getContents' :: io String Source
Wraps getContents
The getContents
operation returns all user input as a single string,
which is read lazily as it is needed (same as hGetContents'
stdin
).
class Access io => StdOutAccess io where Source
Provides access to functions to write to stdout
putChar' :: Char -> io () Source
putStr' :: String -> io () Source
putStrLn' :: String -> io () Source
print' :: Show a => a -> io () Source
Wraps print
The print'
function outputs a value of any printable type to the
standard output device.
Printable types are those that are instances of class Show
; print'
converts values to strings for output using the show
operation and
adds a newline.
For example, a program to print' the first 20 integers and their powers of 2 could be written as:
main = print' ([(n, 2^n) | n <- [0..19]])
class (StdInAccess io, StdOutAccess io) => StdIOAccess io where Source
Combines the StdInAccess
and StdOutAccess
into a single class
Wraps isEOF
For a readable handle hdl
, hIsEOF'
hdl
returns
True
if no further input can be taken from hdl
or for a
physical file, if the current I/O position is equal to the length of
the file. Otherwise, it returns False
.
NOTE: hIsEOF'
may block, because it has to attempt to read from
the stream to determine whether there is any more data to be read.
class FileReadAccess io where Source
Provides the function readFile'
for reading the contents of a file
class Access io => FileWriteAccess io where Source
Provides functions for writing to files
writeFile' :: FilePath -> String -> io () Source
Wraps writeFile
The computation writeFile'
file str
function writes the string str
,
to the file file
.
appendFile' :: FilePath -> String -> io () Source
Wraps appendFile
The computation appendFile'
file str
function appends the string
str
, to the file file
.
Note that writeFile'
and appendFile'
write a literal string
to a file. To write a value of any printable type, as with print'
,
use the show
function to convert the value to a string first.
main = appendFile' "squares" (show [(x,x*x) | x <- [0,0.1..2]])
class (HandleAccess io, FileReadAccess io, FileWriteAccess io) => FileAccess io where Source
Combines HandleAccess
, FileReadAccess
, and FileWriteAccess
for
manipulating files (this does allow for general Handle
access and should be
considered unsafe)
withFile' :: FilePath -> IOMode -> (Handle -> io r) -> io r Source
Wraps withFile
opens a file using withFile'
name mode actopenFile'
and passes
the resulting handle to the computation act
. The handle will be
closed on exit from withFile'
, whether by normal termination or by
raising an exception. If closing the handle raises an exception, then
this exception will be raised by withFile'
rather than any exception
raised by act
.
openFile' :: FilePath -> IOMode -> io Handle Source
Wraps openFile
Computation openFile'
file mode
allocates and returns a new, open
handle to manage the file file
. It manages input if mode
is ReadMode
, output if mode
is WriteMode
or AppendMode
,
and both input and output if mode is ReadWriteMode
.
If the file does not exist and it is opened for output, it should be
created as a new file. If mode
is WriteMode
and the file
already exists, then it should be truncated to zero length.
Some operating systems delete empty files, so there is no guarantee
that the file will exist following an openFile'
with mode
WriteMode
unless it is subsequently written to successfully.
The handle is positioned at the end of the file if mode
is
AppendMode
, and otherwise at the beginning (in which case its
internal position is 0).
The initial buffer mode is implementation-dependent.
This operation may fail with:
isAlreadyInUseError
if the file is already open and cannot be reopened;isDoesNotExistError
if the file does not exist; orisPermissionError
if the user does not have permission to open the file.
Note: if you will be working with files containing binary data, you'll want to
be using openBinaryFile'
.
withBinaryFile' :: FilePath -> IOMode -> (Handle -> io r) -> io r Source
Wraps withBinaryFile
opens a file using withBinaryFile'
name mode actopenBinaryFile'
and passes the resulting handle to the computation act
. The handle
will be closed on exit from withBinaryFile'
, whether by normal
termination or by raising an exception.
openBinaryFile' :: FilePath -> IOMode -> io Handle Source
Wraps openBinaryFile
Like openFile'
, but open the file in binary mode.
On Windows, reading a file in text mode (which is the default)
will translate CRLF to LF, and writing will translate LF to CRLF.
This is usually what you want with text files. With binary files
this is undesirable; also, as usual under Microsoft operating systems,
text mode treats control-Z as EOF. Binary mode turns off all special
treatment of end-of-line and end-of-file characters.
(See also hSetBinaryMode'
.)
class Access io => TempFileAccess io where Source
Provides access to functions for opening temporary file Handle
s
openTempFile' :: FilePath -> String -> io (FilePath, Handle) Source
Wraps openTempFile
The function creates a temporary file in ReadWrite
mode.
The created file isn't deleted automatically, so you need to delete it
manually.
The file is creates with permissions such that only the current user can read/write it.
With some exceptions (see below), the file will be created securely
in the sense that an attacker should not be able to cause
openTempFile'
to overwrite another file on the filesystem using your
credentials, by putting symbolic links (on Unix) in the place where
the temporary file is to be created. On Unix the O_CREAT
and
O_EXCL
flags are used to prevent this attack, but note that
O_EXCL
is sometimes not supported on NFS filesystems, so if you
rely on this behaviour it is best to use local filesystems only.
openBinaryTempFile' :: FilePath -> String -> io (FilePath, Handle) Source
Wraps openBinaryTempFile
Like openTempFile'
, but opens the file in binary mode.
See openBinaryFile'
for more comments.
openTempFileWithDefaultPermissions' :: FilePath -> String -> io (FilePath, Handle) Source
Wraps openTempFileWithDefaultPermissions
Like openTempFile'
, but uses the default file permissions
openBinaryTempFileWithDefaultPermissions' :: FilePath -> String -> io (FilePath, Handle) Source
Wraps openBinaryTempFileWithDefaultPermissions
Like openBinaryTempFile'
, but uses the default file permissions
class Access io => TextEncodingAccess io where Source
Provides access to mkTextEncoding'
mkTextEncoding' :: String -> io TextEncoding Source
Wraps mkTextEncoding
Look up the named Unicode encoding. May fail with
isDoesNotExistError
if the encoding is unknown
The set of known encodings is system-dependent, but includes at least:
UTF-8
UTF-16
,UTF-16BE
,UTF-16LE
UTF-32
,UTF-32BE
,UTF-32LE
On systems using GNU iconv (e.g. Linux), there is additional notation for specifying how illegal characters are handled:
- a suffix of
//IGNORE
, e.g.UTF-8//IGNORE
, will cause all illegal sequences on input to be ignored, and on output will drop all code points that have no representation in the target encoding. - a suffix of
//TRANSLIT
will choose a replacement character for illegal sequences or code points.
On Windows, you can access supported code pages with the prefix
CP
; for example, "CP1250"
.