Maintainer | Bas van Dijk <v.dijk.bas@gmail.com> |
---|
The contributions of this module are as follows:
- This module extends the
regions
library with the ability to open files in aRegionT
. When the region terminates, all opened resources will be closed automatically. The main advantage of regions is that the handles to the opened resources can not be returned from the region. This ensures no I/O with closed resources is possible. The primary technique used inregions
is called "Lightweight monadic regions" which was invented by Oleg Kiselyov and Chung-chieh Shan. See: http://okmij.org/ftp/Haskell/regions.html#light-weight - Secondly this module provides all the file operations of
System.IO
lifted to the region monad. - Third, filepaths that are given to functions like
openFile
are created and manipulated in a type-safe way using thepathtype
package. - The final contribution of this module is that file handles are
parameterised with the IOMode in which the file was opened. This can be
either
ReadMode
,WriteMode
,AppendMode
orReadWriteMode
. All operations on files explicitly specify the needed IOMode using theReadModes
andWriteModes
type classes. This way it is impossible to read from a write-only handle or write to a read-only handle for example.
See the safer-file-handles-examples
package for examples how to use this
package:
darcs get http://code.haskell.org/~basvandijk/code/safer-file-handles-examples
NOTE: This module also provides functions from System.IO
which don't
directly work with file handles like putStrLn
or getLine
for
example. These functions implicitly use the standard handles. I actually
provide more general versions of these that work in any MonadIO
. It could
be argued that these functions don't belong in this module because they don't
have anything to do with regions and explicit IOModes. However I provide them
as a convenience. But be warned that in the future these lifted functions may
move to their own package!
- data RegionalFileHandle ioMode r
- data ReadMode
- data WriteMode
- data AppendMode
- data ReadWriteMode
- class ReadModesPrivate ioMode => ReadModes ioMode
- class WriteModesPrivate ioMode => WriteModes ioMode
- data IOMode ioMode where
- class MkIOMode ioMode where
- stdin :: RegionalFileHandle ReadMode r
- stdout :: RegionalFileHandle WriteMode r
- stderr :: RegionalFileHandle WriteMode r
- cast :: (ParentOf pr cr, MonadIO cr, CheckMode castedIOMode) => RegionalFileHandle anyIOMode pr -> cr (Maybe (RegionalFileHandle castedIOMode pr))
- openFile :: (MonadCatchIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))
- withFile :: (MonadCatchIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr α
- openFile' :: (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))
- withFile' :: (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr α
- module Control.Monad.Trans.Region
- hFileSize :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Integer
- hSetFileSize :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> Integer -> cr ()
- hIsEOF :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr Bool
- isEOF :: MonadIO m => m Bool
- data BufferMode
- = NoBuffering
- | LineBuffering
- | BlockBuffering (Maybe Int)
- hSetBuffering :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> BufferMode -> cr ()
- hGetBuffering :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr BufferMode
- hFlush :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> cr ()
- hGetPosn :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr HandlePosn
- hSetPosn :: MonadIO m => HandlePosn -> m ()
- data HandlePosn
- hSeek :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> SeekMode -> Integer -> cr ()
- data SeekMode
- hTell :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Integer
- hIsOpen :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Bool
- hIsClosed :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Bool
- hIsReadable :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Bool
- hIsWritable :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Bool
- hIsSeekable :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Bool
- hIsTerminalDevice :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Bool
- hSetEcho :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> Bool -> cr ()
- hGetEcho :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr Bool
- hShow :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr String
- hWaitForInput :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> Int -> cr Bool
- hReady :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr Bool
- hGetChar :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr Char
- hGetLine :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr String
- hLookAhead :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr Char
- hGetContents :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr String
- hPutChar :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> Char -> cr ()
- hPutStr :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> String -> cr ()
- hPutStrLn :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> String -> cr ()
- hPrint :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode, Show α) => RegionalFileHandle ioMode pr -> α -> cr ()
- interact :: MonadIO m => (String -> String) -> m ()
- putChar :: MonadIO m => Char -> m ()
- putStr :: MonadIO m => String -> m ()
- putStrLn :: MonadIO m => String -> m ()
- print :: (MonadIO m, Show α) => α -> m ()
- getChar :: MonadIO m => m Char
- getLine :: MonadIO m => m String
- getContents :: MonadIO m => m String
- readIO :: (MonadIO m, Read α) => String -> m α
- readLn :: (MonadIO m, Read α) => m α
- openBinaryFile :: (MonadCatchIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))
- withBinaryFile :: (MonadCatchIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr α
- openBinaryFile' :: (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))
- withBinaryFile' :: (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr α
- hSetBinaryMode :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> Bool -> cr ()
- hPutBuf :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> Ptr α -> Int -> cr ()
- hGetBuf :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> Ptr α -> Int -> cr Int
- hPutBufNonBlocking :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> Ptr α -> Int -> cr Int
- hGetBufNonBlocking :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> Ptr α -> Int -> cr Int
- type Template = RelFile
- openTempFile :: (MonadCatchIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))
- openBinaryTempFile :: (MonadCatchIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))
- openTempFileWithDefaultPermissions :: (MonadCatchIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))
- openBinaryTempFileWithDefaultPermissions :: (MonadCatchIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))
- hSetEncoding :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> TextEncoding -> cr ()
- hGetEncoding :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr (Maybe TextEncoding)
- data TextEncoding
- latin1 :: TextEncoding
- utf8 :: TextEncoding
- utf8_bom :: TextEncoding
- utf16 :: TextEncoding
- utf16le :: TextEncoding
- utf16be :: TextEncoding
- utf32 :: TextEncoding
- utf32le :: TextEncoding
- utf32be :: TextEncoding
- localeEncoding :: TextEncoding
- mkTextEncoding :: MonadIO m => String -> m TextEncoding
- hSetNewlineMode :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> NewlineMode -> cr ()
- data Newline
- nativeNewline :: Newline
- data NewlineMode = NewlineMode {}
- noNewlineTranslation :: NewlineMode
- universalNewlineMode :: NewlineMode
- nativeNewlineMode :: NewlineMode
Regional file handles
data RegionalFileHandle ioMode r Source
A regional handle to an opened file parameterized by the IOMode
in which
you opened the file and the region in which it was created.
Dup (RegionalFileHandle ioMode) |
IO Modes
Types that represent the IOMode an opened file can be in.
data ReadMode
Read only.
data WriteMode
Write only.
data AppendMode
Write only by appending.
WriteModesPrivate AppendMode | |
WriteModes AppendMode | |
MkIOMode AppendMode | |
CheckMode AppendMode |
data ReadWriteMode
Both read and write.
ReadModesPrivate ReadWriteMode | |
WriteModesPrivate ReadWriteMode | |
ReadModes ReadWriteMode | |
WriteModes ReadWriteMode | |
MkIOMode ReadWriteMode | |
CheckMode ReadWriteMode |
class ReadModesPrivate ioMode => ReadModes ioMode
Class of readable IO mode types.
Note the super class ReadModesPrivate
. This type class is not exported by
this module which ensures you can't accidentally make another type (like
WriteMode
or AppendMode
) an instance of ReadModes
.
class WriteModesPrivate ioMode => WriteModes ioMode
Class of writable IO mode types.
Note the super class WriteModesPrivate
. This type class is not exported by
this module which ensures you can't accidentally make another type (like
ReadMode
) an instance of WriteModes
.
data IOMode ioMode where
The IOMode GADT which for each constructor specifies the associated IOMode type.
Also see: System.IO.
.
IOMode
class MkIOMode ioMode where
Standard handles
These standard handles have concrete IOModes by default which work
for the majority of cases. In the rare occasion that you know these
handles have different IOModes you can cast
them.
stdin :: RegionalFileHandle ReadMode rSource
Wraps: System.IO.
.
stdin
stdout :: RegionalFileHandle WriteMode rSource
Wraps: System.IO.
.
stdout
stderr :: RegionalFileHandle WriteMode rSource
Wraps: System.IO.
.
stderr
cast :: (ParentOf pr cr, MonadIO cr, CheckMode castedIOMode) => RegionalFileHandle anyIOMode pr -> cr (Maybe (RegionalFileHandle castedIOMode pr))Source
Cast the IOMode of a handle if the handle supports it.
This function is primarily used in combination with the standard handles. When you know the IOMode of a handle is different from its default IOMode you can cast it to the right one.
Opening files in a region
openFile :: (MonadCatchIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))Source
Computation openFile
filePath ioMode
allocates and returns a new,
regional file handle to manage the file identified by filePath
. It provides a
safer replacement for System.IO.
.
openFile
If the file does not exist and it is opened for output, it should be created as
a new file. If ioMode
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
ioMode
WriteMode
unless it is subsequently written to successfully. The
handle is positioned at the end of the file if ioMode
is AppendMode
, and
otherwise at the beginning (in which case its internal position is 0). The
initial buffer mode is implementation-dependent.
Note that the returned regional file handle is parameterized by the region in which it was created. This ensures that handles can never escape their region. And it also allows operations on handles to be executed in a child region of the region in which the handle was created.
Note that if you do wish to return a handle from the region in which it was
created you have to duplicate the handle by applying dup
to it.
Finally note that the returned regional file handle is also parameterized by the
IOMode in which you opened the file. All operations on files explicitly specify
the needed IOMode using the ReadModes
and WriteModes
type classes. This way
it is impossible to read from a write-only handle or write to a read-only handle
for example.
This operation may fail with:
-
isAlreadyInUseError
if the file is already open and cannot be reopened; -
isDoesNotExistError
if the file does not exist; or -
isPermissionError
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
.
withFile :: (MonadCatchIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr αSource
Convenience function which opens a file, applies the given continuation
function to the resulting regional file handle and runs the resulting
region. This provides a safer safer replacement for System.IO.
.
withFile
Opening files by inferring the IOMode
openFile' :: (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))Source
Open a file without explicitly specifying the IOMode. The IOMode is
inferred from the type of the resulting RegionalFileHandle
.
withFile' :: (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr αSource
Regions
Note that this module re-exports the Control.Monad.Trans.Region
module from the regions
package which allows you to:
- Run a region using
runRegionT
. - Concurrently run a region inside another region using
forkIOTopRegion
. - Duplicate a
RegionalFileHandle
to a parent region usingdup
.
module Control.Monad.Trans.Region
Operations on regional file handles
Determining and changing the size of a file
hSetFileSize :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> Integer -> cr ()Source
hSetFileSize
hdl
size
truncates the physical file with handle hdl
to size
bytes.
Wraps: System.IO.
.
hSetFileSize
Detecting the end of input
hIsEOF :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr BoolSource
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 is the same as calling
hLookAhead
and checking for an EOF exception.
Wraps: System.IO.
.
hIsEOF
Buffering operations
data BufferMode
Three kinds of buffering are supported: line-buffering, block-buffering or no-buffering. These modes have the following effects. For output, items are written out, or flushed, from the internal buffer according to the buffer mode:
- line-buffering: the entire output buffer is flushed whenever a newline is output, the buffer overflows, a System.IO.hFlush is issued, or the handle is closed.
- block-buffering: the entire buffer is written out whenever it overflows, a System.IO.hFlush is issued, or the handle is closed.
- no-buffering: output is written immediately, and never stored in the buffer.
An implementation is free to flush the buffer more frequently, but not less frequently, than specified above. The output buffer is emptied as soon as it has been written out.
Similarly, input occurs according to the buffer mode for the handle:
- line-buffering: when the buffer for the handle is not empty, the next item is obtained from the buffer; otherwise, when the buffer is empty, characters up to and including the next newline character are read into the buffer. No characters are available until the newline character is available or the buffer is full.
- block-buffering: when the buffer for the handle becomes empty, the next block of data is read into the buffer.
- no-buffering: the next input item is read and returned. The System.IO.hLookAhead operation implies that even a no-buffered handle may require a one-character buffer.
The default buffering mode when a handle is opened is implementation-dependent and may depend on the file system object which is attached to that handle. For most implementations, physical files will normally be block-buffered and terminals will normally be line-buffered.
NoBuffering | buffering is disabled if possible. |
LineBuffering | line-buffering should be enabled if possible. |
BlockBuffering (Maybe Int) | block-buffering should be enabled if possible.
The size of the buffer is |
hSetBuffering :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> BufferMode -> cr ()Source
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.
Wraps: System.IO.
.
hSetBuffering
hGetBuffering :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr BufferModeSource
Computation hGetBuffering
hdl
returns the current buffering mode for
hdl
.
Wraps: System.IO.
.
hGetBuffering
hFlush :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> cr ()Source
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.
Wraps: System.IO.
.
hFlush
Repositioning handles
hGetPosn :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr HandlePosnSource
Computation hGetPosn
hdl
returns the current I/O position of hdl
as
a value of the abstract type HandlePosn
.
Wraps: System.IO.
.
hGetPosn
hSetPosn :: MonadIO m => HandlePosn -> m ()Source
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.
Wraps: System.IO.
.
hSetPosn
data HandlePosn
hSeek :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> SeekMode -> Integer -> cr ()Source
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:
-
isPermissionError
if a system resource limit would be exceeded.
Wraps: System.IO.
.
hSeek
data SeekMode
A mode that determines the effect of hSeek hdl mode i
, as follows:
AbsoluteSeek | the position of |
RelativeSeek | the position of |
SeekFromEnd | the position of |
hTell :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr IntegerSource
Wraps: System.IO.
.
hTell
Handle properties
hIsReadable :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr BoolSource
Note that this operation should always return True
for IOModes which have
an instance for ReadModes
. This function is used only for testing the
correctness of this library.
Wraps: System.IO.
.
hIsReadable
hIsWritable :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr BoolSource
Note that this operation should always return True
for IOModes which have
an instance for WriteModes
. This function is used only for testing the
correctness of this library.
Wraps: System.IO.
.
hIsWritable
hIsSeekable :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr BoolSource
Wraps: System.IO.
.
hIsSeekable
Terminal operations (not portable: GHC/Hugs only)
hIsTerminalDevice :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr BoolSource
Is the handle connected to a terminal?
Wraps: System.IO.
.
hIsTerminalDevice
hSetEcho :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> Bool -> cr ()Source
Set the echoing status of a handle connected to a terminal.
Wraps: System.IO.
.
hSetEcho
hGetEcho :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr BoolSource
Get the echoing status of a handle connected to a terminal.
Wraps: System.IO.
.
hGetEcho
Showing handle state (not portable: GHC only)
hShow :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr StringSource
Wraps: System.IO.
.
hShow
Text input and output
Text input
Note that the following text input operations are polymorphic in the
IOMode of the given handle. However the IOModes are restricted to
ReadModes
only which can be either R
or RW
.
hWaitForInput :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> Int -> cr BoolSource
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.
If t
is less than zero, then hWaitForInput
waits indefinitely.
This operation may fail with:
-
isEOFError
if the end of file has been reached.
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.
Wraps: System.IO.
.
hWaitForInput
hReady :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr BoolSource
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.
Wraps: System.IO.
.
hReady
hGetChar :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr CharSource
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.
Wraps: System.IO.
.
hGetChar
hGetLine :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr StringSource
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.
Wraps: System.IO.
.
hGetLine
hLookAhead :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr CharSource
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.
Wraps: System.IO.
.
hLookAhead
hGetContents :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> cr StringSource
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. A semi-closed handle becomes closed:
- if its corresponding region terminates;
- 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.
Wraps: System.IO.
.
hGetContents
Text ouput
Note that the following text output operations are polymorphic in the
IOMode of the given handle. However the IOModes are restricted to
WriteModes
only which can be either W
, A
or RW
.
hPutChar :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> Char -> cr ()Source
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; or -
isPermissionError
if another system resource limit would be exceeded.
Wraps: System.IO.
.
hPutChar
hPutStr :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> String -> cr ()Source
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; or -
isPermissionError
if another system resource limit would be exceeded.
Wraps: System.IO.
.
hPutStr
hPutStrLn :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> String -> cr ()Source
hPrint :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode, Show α) => RegionalFileHandle ioMode pr -> α -> cr ()Source
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; or -
isPermissionError
if another system resource limit would be exceeded.
Wraps: System.IO.
.
hPrint
Special cases for standard input and output
getContents :: MonadIO m => m StringSource
Generalizes System.IO.
to any getContents
MonadIO
.
Binary input and output
openBinaryFile :: (MonadCatchIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))Source
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
.)
This provides a safer replacement for System.IO.
.
openBinaryFile
withBinaryFile :: (MonadCatchIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr αSource
A convenience function which opens a file in binary mode, applies the given
continuation function to the resulting regional file handle and runs the
resulting region. This provides a safer replacement for
System.IO.
.
withBinaryFile
Opening binary files by inferring the IOMode
openBinaryFile' :: (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))Source
Note that: openBinaryFile' filePath =
.
openBinaryFile
filePath mkIOMode
withBinaryFile' :: (MonadCatchIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr αSource
Note that: withBinaryFile' filePath =
.
withBinaryFile
filePath mkIOMode
Operations on binary handles
hSetBinaryMode :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> Bool -> cr ()Source
Select binary mode (True
) or text mode (False
) on a open handle.
(See also openBinaryFile
.)
This has the same effect as calling hSetEncoding
with latin1
, together
with hSetNewlineMode
with noNewlineTranslation
.
Wraps: System.IO.
.
hSetBinaryMode
hPutBuf :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> Ptr α -> Int -> cr ()Source
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 RegionalFileHandle
,
writing the bytes directly to the underlying file or device.
hPutBuf
ignores the prevailing TextEncoding
and
NewlineMode
on the RegionalFileHandle
, 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).
Wraps: System.IO.
.
hPutBuf
hGetBuf :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> Ptr α -> Int -> cr IntSource
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
ignores whatever TextEncoding
the RegionalFileHandle
is
currently using, and reads bytes directly from the underlying IO device.
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
RegionalFileHandle
, and reads bytes directly.
Wraps: System.IO.
.
hGetBuf
hPutBufNonBlocking :: (ParentOf pr cr, MonadIO cr, WriteModes ioMode) => RegionalFileHandle ioMode pr -> Ptr α -> Int -> cr IntSource
Wraps: System.IO.
.
hPutBufNonBlocking
hGetBufNonBlocking :: (ParentOf pr cr, MonadIO cr, ReadModes ioMode) => RegionalFileHandle ioMode pr -> Ptr α -> Int -> cr IntSource
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
.
hGetBufNonBlocking
ignores whatever TextEncoding
the RegionalFileHandle
is currently using, and reads bytes directly from the underlying IO device.
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 RegionalFileHandle
, and reads bytes directly.
Wraps: System.IO.
.
hGetBufNonBlocking
Temporary files
The template of a temporary file path.
If the template is "foo.ext" then the created file will be "fooXXX.ext" where XXX is some random number.
:: (MonadCatchIO pr, AbsRelClass ar) | |
=> DirPath ar | Directory in which to create the file. |
-> Template | File name template. |
-> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr)) |
The function creates a temporary file in ReadWriteMode
. The created file
isn't deleted automatically, so you need to delete it manually.
The file is created 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.
This provides a safer replacement for System.IO.
.
openTempFile
openBinaryTempFile :: (MonadCatchIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))Source
Like openTempFile
, but opens the file in binary mode. See
openBinaryFile
for more comments.
This provides a safer replacement for System.IO.
.
openBinaryTempFile
openTempFileWithDefaultPermissions :: (MonadCatchIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))Source
Like openTempFile
, but uses the default file permissions.
This provides a safer replacement for
System.IO.
.
openTempFileWithDefaultPermissions
openBinaryTempFileWithDefaultPermissions :: (MonadCatchIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))Source
Like openBinaryTempFile
, but uses the default file permissions.
This provides a safer replacement for
System.IO.
.
openBinaryTempFileWithDefaultPermissions
Unicode encoding/decoding
hSetEncoding :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> TextEncoding -> cr ()Source
The action hSetEncoding
hdl
encoding
changes the text encoding for
the handle hdl
to encoding
. The default encoding when a
RegionalFileHandle
is created is localeEncoding
, namely the default
encoding for the current locale.
To create a RegionalFileHandle
with no encoding at all, use
openBinaryFile
. To stop further encoding or decoding on an existing
RegionalFileHandle
, use hSetBinaryMode
.
hSetEncoding
may need to flush buffered data in order to change
the encoding.
Wraps: System.IO.
.
hSetEncoding
hGetEncoding :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> cr (Maybe TextEncoding)Source
Return the current TextEncoding
for the specified RegionalFileHandle
,
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 RegionalFileHandle
. 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.
Wraps: System.IO.
.
hGetEncoding
Unicode encodings
data TextEncoding
A TextEncoding
is a specification of a conversion scheme
between sequences of bytes and sequences of Unicode characters.
For example, UTF-8 is an encoding of Unicode characters into a sequence
of bytes. The TextEncoding
for UTF-8 is utf8.
The Latin1 (ISO8859-1) encoding. This encoding maps bytes
directly to the first 256 Unicode code points, and is thus not a
complete Unicode encoding. An attempt to write a character greater than
'\255' to a Handle using the latin1
encoding will result in an error.
utf8 :: TextEncoding
The UTF-8 Unicode encoding
The UTF-8 Unicode encoding, with a byte-order-mark (BOM; the byte
sequence 0xEF 0xBB 0xBF). This encoding behaves like utf8
,
except that on input, the BOM sequence is ignored at the beginning
of the stream, and on output, the BOM sequence is prepended.
The byte-order-mark is strictly unnecessary in UTF-8, but is sometimes used to identify the encoding of a file.
The UTF-16 Unicode encoding (a byte-order-mark should be used to indicate endianness).
The UTF-16 Unicode encoding (litte-endian)
The UTF-16 Unicode encoding (big-endian)
The UTF-32 Unicode encoding (a byte-order-mark should be used to indicate endianness).
The UTF-32 Unicode encoding (litte-endian)
The UTF-32 Unicode encoding (big-endian)
localeEncoding :: TextEncoding
The Unicode encoding of the current locale
mkTextEncoding :: MonadIO m => String -> m TextEncodingSource
Generalizes System.IO.
to any mkTextEncoding
MonadIO
.
Newline conversion
hSetNewlineMode :: (ParentOf pr cr, MonadIO cr) => RegionalFileHandle ioMode pr -> NewlineMode -> cr ()Source
Set the NewlineMode
on the specified RegionalFileHandle
. All buffered
data is flushed first.
Wraps: System.IO.
.
hSetNewlineMode
data Newline
The representation of a newline in the external file or stream.
data NewlineMode
Specifies the translation, if any, of newline characters between internal Strings and the external file or stream. Haskell Strings are assumed to represent newlines with the '\n' character; the newline mode specifies how to translate '\n' on output, and what to translate into '\n' on input.
noNewlineTranslation :: NewlineMode
Do no newline translation at all.
noNewlineTranslation = NewlineMode { inputNL = LF, outputNL = LF }
universalNewlineMode :: NewlineMode
Map '\r\n' into '\n' on input, and '\n' to the native newline
represetnation on output. This mode can be used on any platform, and
works with text files using any newline convention. The downside is
that readFile >>= writeFile
might yield a different file.
universalNewlineMode = NewlineMode { inputNL = CRLF,
outputNL = nativeNewline }
nativeNewlineMode :: NewlineMode
Use the native newline representation on both input and output
nativeNewlineMode = NewlineMode { inputNL = nativeNewline
outputNL = nativeNewline }