Module System.IO

Library for IO operations like reading and writing files that are not already contained in the prelude.

Author: Michael Hanus, Bernd Brassel

Version: March 2015

Summary of exported operations:

stdin :: Handle  Deterministic 
Standard input stream.
stdout :: Handle  Deterministic 
Standard output stream.
stderr :: Handle  Deterministic 
Standard error stream.
openFile :: String -> IOMode -> IO Handle  Deterministic 
Opens a file in specified mode and returns a handle to it.
hClose :: Handle -> IO ()  Deterministic 
Closes a file handle and flushes the buffer in case of output file.
hFlush :: Handle -> IO ()  Deterministic 
Flushes the buffer associated to handle in case of output file.
hIsEOF :: Handle -> IO Bool  Deterministic 
Is handle at end of file?
isEOF :: IO Bool  Deterministic 
Is standard input at end of file?
hSeek :: Handle -> SeekMode -> Int -> IO ()  Deterministic 
Set the position of a handle to a seekable stream (e.g., a file).
hWaitForInput :: Handle -> Int -> IO Bool  Deterministic 
Waits until input is available on the given handle.
hWaitForInputs :: [Handle] -> Int -> IO Int  Deterministic 
Waits until input is available on some of the given handles.
hWaitForInputOrMsg :: Handle -> [a] -> IO (Either Handle [a])  Deterministic 
Waits until input is available on a given handles or a message in the message stream.
hWaitForInputsOrMsg :: [Handle] -> [a] -> IO (Either Int [a])  Deterministic 
Waits until input is available on some of the given handles or a message in the message stream.
hReady :: Handle -> IO Bool  Deterministic 
Checks whether an input is available on a given handle.
hGetChar :: Handle -> IO Char  Deterministic 
Reads a character from an input handle and returns it.
hGetLine :: Handle -> IO String  Deterministic 
Reads a line from an input handle and returns it.
hGetContents :: Handle -> IO String  Deterministic 
Reads the complete contents from an input handle and closes the input handle before returning the contents.
getContents :: IO String  Deterministic 
Reads the complete contents from the standard input stream until EOF.
hPutChar :: Handle -> Char -> IO ()  Deterministic 
Puts a character to an output handle.
hPutStr :: Handle -> String -> IO ()  Deterministic 
Puts a string to an output handle.
hPutStrLn :: Handle -> String -> IO ()  Deterministic 
Puts a string with a newline to an output handle.
hPrint :: Show a => Handle -> a -> IO ()  Deterministic 
Converts a term into a string and puts it to an output handle.
hIsReadable :: Handle -> IO Bool  Deterministic 
Is the handle readable?
hIsWritable :: Handle -> IO Bool  Deterministic 
Is the handle writable?
hIsTerminalDevice :: Handle -> IO Bool  Deterministic 
Is the handle connected to a terminal?

Exported datatypes:


Handle

Constructors:


IOMode

The modes for opening a file.

Constructors:

  • ReadMode :: IOMode
  • WriteMode :: IOMode
  • AppendMode :: IOMode

SeekMode

The modes for positioning with hSeek in a file.

Constructors:

  • AbsoluteSeek :: SeekMode
  • RelativeSeek :: SeekMode
  • SeekFromEnd :: SeekMode

Exported operations:

stdin :: Handle  Deterministic 

Standard input stream.

Further infos:
  • externally defined

stdout :: Handle  Deterministic 

Standard output stream.

Further infos:
  • externally defined

stderr :: Handle  Deterministic 

Standard error stream.

Further infos:
  • externally defined

openFile :: String -> IOMode -> IO Handle  Deterministic 

Opens a file in specified mode and returns a handle to it.

hClose :: Handle -> IO ()  Deterministic 

Closes a file handle and flushes the buffer in case of output file.

hFlush :: Handle -> IO ()  Deterministic 

Flushes the buffer associated to handle in case of output file.

hIsEOF :: Handle -> IO Bool  Deterministic 

Is handle at end of file?

isEOF :: IO Bool  Deterministic 

Is standard input at end of file?

hSeek :: Handle -> SeekMode -> Int -> IO ()  Deterministic 

Set the position of a handle to a seekable stream (e.g., a file). If the second argument is AbsoluteSeek, SeekFromEnd, or RelativeSeek, the position is set relative to the beginning of the file, to the end of the file, or to the current position, respectively.

hWaitForInput :: Handle -> Int -> IO Bool  Deterministic 

Waits until input is available on the given handle. If no input is available within t milliseconds, it returns False, otherwise it returns True.

Example call:
(hWaitForInput handle timeout)
Parameters:
  • handle : a handle for an input stream
  • timeout : milliseconds to wait for input (< 0 : no time out)

hWaitForInputs :: [Handle] -> Int -> IO Int  Deterministic 

Waits until input is available on some of the given handles. If no input is available within t milliseconds, it returns -1, otherwise it returns the index of the corresponding handle with the available data.

Example call:
(hWaitForInputs handles timeout)
Parameters:
  • handles : a list of handles for input streams
  • timeout : milliseconds to wait for input (< 0 : no time out)
Returns:
-1 if no input is available within the time out, otherwise i if (handles!!i) has data available

hWaitForInputOrMsg :: Handle -> [a] -> IO (Either Handle [a])  Deterministic 

Waits until input is available on a given handles or a message in the message stream. Usually, the message stream comes from an external port. Thus, this operation implements a committed choice over receiving input from an IO handle or an external port.

Note that the implementation of this operation works only with Sicstus-Prolog 3.8.5 or higher (due to a bug in previous versions of Sicstus-Prolog).

Example call:
(hWaitForInputOrMsg handle msgs)
Parameters:
  • handle : a handle for an input stream
  • msgs : a stream of messages received via an external port (see Ports)
Returns:
(Left handle) if the handle has some data available (Right msgs) if the stream msgs is instantiated with at least one new message at the head

hWaitForInputsOrMsg :: [Handle] -> [a] -> IO (Either Int [a])  Deterministic 

Waits until input is available on some of the given handles or a message in the message stream. Usually, the message stream comes from an external port. Thus, this operation implements a committed choice over receiving input from IO handles or an external port.

EMNote that the implementation of this operation works only with Sicstus-Prolog 3.8.5 or higher (due to a bug in previous versions of Sicstus-Prolog)./EM

Example call:
(hWaitForInputsOrMsg handles msgs)
Parameters:
  • handles : a list of handles for input streams
  • msgs : a stream of messages received via an external port (see Ports)
Returns:
(Left i) if (handles!!i) has some data available (Right msgs) if the stream msgs is instantiated with at least one new message at the head

hReady :: Handle -> IO Bool  Deterministic 

Checks whether an input is available on a given handle.

hGetChar :: Handle -> IO Char  Deterministic 

Reads a character from an input handle and returns it. Throws an error if the end of file has been reached.

hGetLine :: Handle -> IO String  Deterministic 

Reads a line from an input handle and returns it. Throws an error if the end of file has been reached while reading the first character. If the end of file is reached later in the line, it ist treated as a line terminator and the (partial) line is returned.

hGetContents :: Handle -> IO String  Deterministic 

Reads the complete contents from an input handle and closes the input handle before returning the contents.

getContents :: IO String  Deterministic 

Reads the complete contents from the standard input stream until EOF.

hPutChar :: Handle -> Char -> IO ()  Deterministic 

Puts a character to an output handle.

hPutStr :: Handle -> String -> IO ()  Deterministic 

Puts a string to an output handle.

hPutStrLn :: Handle -> String -> IO ()  Deterministic 

Puts a string with a newline to an output handle.

hPrint :: Show a => Handle -> a -> IO ()  Deterministic 

Converts a term into a string and puts it to an output handle.

hIsReadable :: Handle -> IO Bool  Deterministic 

Is the handle readable?

hIsWritable :: Handle -> IO Bool  Deterministic 

Is the handle writable?

hIsTerminalDevice :: Handle -> IO Bool  Deterministic 

Is the handle connected to a terminal?