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:
git clone https://github.com/basvandijk/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!
- class FileHandle handle
- 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
- data StdFileHandle ioMode r
- stdin :: StdFileHandle ReadMode RootRegion
- stdout :: StdFileHandle WriteMode RootRegion
- stderr :: StdFileHandle WriteMode RootRegion
- cast :: (AncestorRegion pr cr, MonadIO cr, CheckMode castedIOMode) => StdFileHandle anyIOMode pr -> cr (Maybe (StdFileHandle castedIOMode pr))
- openFile :: (RegionControlIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))
- withFile :: (RegionControlIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr α
- openFile' :: (RegionControlIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))
- withFile' :: (RegionControlIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr α
- module Control.Monad.Trans.Region
- hFileSize :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Integer
- hSetFileSize :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> Integer -> cr ()
- hIsEOF :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle ioMode pr -> cr Bool
- isEOF :: MonadIO m => m Bool
- data BufferMode
- = NoBuffering
- | LineBuffering
- | BlockBuffering (Maybe Int)
- hSetBuffering :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> BufferMode -> cr ()
- hGetBuffering :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr BufferMode
- hFlush :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode) => handle ioMode pr -> cr ()
- hGetPosn :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr HandlePosn
- hSetPosn :: MonadIO m => HandlePosn -> m ()
- data HandlePosn
- hSeek :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> SeekMode -> Integer -> cr ()
- data SeekMode
- hTell :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Integer
- hIsOpen :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Bool
- hIsClosed :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Bool
- hIsReadable :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Bool
- hIsWritable :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Bool
- hIsSeekable :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Bool
- hIsTerminalDevice :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Bool
- hSetEcho :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> Bool -> cr ()
- hGetEcho :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr Bool
- hShow :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr String
- hWaitForInput :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle ioMode pr -> Int -> cr Bool
- hReady :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle ioMode pr -> cr Bool
- hGetChar :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle ioMode pr -> cr Char
- hGetLine :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle ioMode pr -> cr String
- hLookAhead :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle ioMode pr -> cr Char
- hGetContents :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle ioMode pr -> cr String
- hPutChar :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode) => handle ioMode pr -> Char -> cr ()
- hPutStr :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode) => handle ioMode pr -> String -> cr ()
- hPutStrLn :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode) => handle ioMode pr -> String -> cr ()
- hPrint :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode, Show α) => handle 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 :: (RegionControlIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))
- withBinaryFile :: (RegionControlIO pr, AbsRelClass ar) => FilePath ar -> IOMode ioMode -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr α
- openBinaryFile' :: (RegionControlIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))
- withBinaryFile' :: (RegionControlIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> (forall s. RegionalFileHandle ioMode (RegionT s pr) -> RegionT s pr α) -> pr α
- hSetBinaryMode :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> Bool -> cr ()
- hPutBuf :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, WriteModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> Int -> cr ()
- hGetBuf :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, ReadModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> Int -> cr Int
- hGetBufSome :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, ReadModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> Int -> cr Int
- hPutBufNonBlocking :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, WriteModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> Int -> cr Int
- hGetBufNonBlocking :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, ReadModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> Int -> cr Int
- type Template = RelFile
- openTempFile :: (RegionControlIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))
- openBinaryTempFile :: (RegionControlIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))
- openTempFileWithDefaultPermissions :: (RegionControlIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))
- openBinaryTempFileWithDefaultPermissions :: (RegionControlIO pr, AbsRelClass ar) => DirPath ar -> Template -> RegionT s pr (AbsFile, RegionalFileHandle ReadWriteMode (RegionT s pr))
- hSetEncoding :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> TextEncoding -> cr ()
- hGetEncoding :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> NewlineMode -> cr ()
- data Newline
- nativeNewline :: Newline
- data NewlineMode = NewlineMode {}
- noNewlineTranslation :: NewlineMode
- universalNewlineMode :: NewlineMode
- nativeNewlineMode :: NewlineMode
File handles
class FileHandle handle Source
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.
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 |
Grouping the IOMode types.
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
.
A value-level IOMode.
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
The 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 safely cast
them
to the expected IOMode.
Note that these handles are pure values. This means they don't perform
side-effects like registering finalizers like hClose stdin
in the
RegionT
monad.
Finally note that the region parameter of the handles is set to
RootRegion
which is the ancestor of any region. This allows the standard
handles to be used in any region.
data StdFileHandle ioMode r Source
stdin :: StdFileHandle ReadMode RootRegionSource
Wraps: System.IO.
.
stdin
stdout :: StdFileHandle WriteMode RootRegionSource
Wraps: System.IO.
.
stdout
stderr :: StdFileHandle WriteMode RootRegionSource
Wraps: System.IO.
.
stderr
cast :: (AncestorRegion pr cr, MonadIO cr, CheckMode castedIOMode) => StdFileHandle anyIOMode pr -> cr (Maybe (StdFileHandle castedIOMode pr))Source
Cast the IOMode of a handle if the handle supports it.
This function is 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 :: (RegionControlIO 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 :: (RegionControlIO 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' :: (RegionControlIO 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' :: (RegionControlIO 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 regions using runRegionT
and duplicate a RegionalFileHandle
to a parent region using dup
.
module Control.Monad.Trans.Region
Operations on regional file handles
Determining and changing the size of a file
hFileSize :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr IntegerSource
hSetFileSize :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr BufferModeSource
Computation hGetBuffering
hdl
returns the current buffering mode for
hdl
.
Wraps: System.IO.
.
hGetBuffering
hFlush :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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
.
AbsoluteSeek | the position of |
RelativeSeek | the position of |
SeekFromEnd | the position of |
hTell :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr IntegerSource
Wraps: System.IO.
.
hTell
Handle properties
hIsOpen :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr BoolSource
hIsClosed :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr BoolSource
hIsReadable :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr BoolSource
Wraps: System.IO.
.
hIsSeekable
Terminal operations (not portable: GHC/Hugs only)
hIsTerminalDevice :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr BoolSource
Is the handle connected to a terminal?
Wraps: System.IO.
.
hIsTerminalDevice
hSetEcho :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> Bool -> cr ()Source
Set the echoing status of a handle connected to a terminal.
Wraps: System.IO.
.
hSetEcho
hGetEcho :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 ReadMode
or ReadWriteMode
.
hWaitForInput :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, ReadModes ioMode) => handle 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
WriteMode
, AppendMode
or ReadWriteMode
.
hPutChar :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode) => handle 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode) => handle ioMode pr -> String -> cr ()Source
hPrint :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr, WriteModes ioMode, Show α) => handle 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 :: (RegionControlIO 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 :: (RegionControlIO 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' :: (RegionControlIO pr, AbsRelClass ar, MkIOMode ioMode) => FilePath ar -> RegionT s pr (RegionalFileHandle ioMode (RegionT s pr))Source
Note that: openBinaryFile' filePath =
.
openBinaryFile
filePath mkIOMode
withBinaryFile' :: (RegionControlIO 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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 :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, WriteModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> 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 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).
Wraps: System.IO.
.
hPutBuf
hGetBuf :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, ReadModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> 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 handle 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
handle, and reads bytes directly.
Wraps: System.IO.
.
hGetBuf
hGetBufSome :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, ReadModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> Int -> cr IntSource
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.
Wraps: System.IO.
.
hGetBufSome
hPutBufNonBlocking :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, WriteModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> Int -> cr IntSource
Wraps: System.IO.
.
hPutBufNonBlocking
hGetBufNonBlocking :: (AncestorRegion pr1 cr, AncestorRegion pr2 cr, FileHandle handle, AllocatedPointer pointer, MonadIO cr, ReadModes ioMode) => handle ioMode pr1 -> pointer α pr2 -> 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 handle
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 handle, 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.
:: (RegionControlIO 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 :: (RegionControlIO 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 :: (RegionControlIO 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 :: (RegionControlIO 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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle 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
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.
Wraps: System.IO.
.
hSetEncoding
hGetEncoding :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> cr (Maybe TextEncoding)Source
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.
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 :: (FileHandle handle, AncestorRegion pr cr, MonadIO cr) => handle ioMode pr -> NewlineMode -> cr ()Source
Set the NewlineMode
on the specified handle.
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 }