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

Exported datatypes:


Handle

The abstract type of a handle for a stream.

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   

Standard input stream.

Further infos:
  • externally defined

stdout :: Handle   

Standard output stream.

Further infos:
  • externally defined

stderr :: Handle   

Standard error stream.

Further infos:
  • externally defined

openFile :: String -> IOMode -> IO Handle   

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

hClose :: Handle -> IO ()   

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

hFlush :: Handle -> IO ()   

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

hIsEOF :: Handle -> IO Bool   

Is handle at end of file?

isEOF :: IO Bool   

Is standard input at end of file?

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

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   

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   

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])   

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])   

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.

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:
(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   

Checks whether an input is available on a given handle.

hGetChar :: Handle -> IO Char   

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   

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   

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

getContents :: IO String   

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

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

Puts a character to an output handle.

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

Puts a string to an output handle.

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

Puts a string with a newline to an output handle.

hPrint :: Handle -> a -> IO ()   

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

hIsReadable :: Handle -> IO Bool   

Is the handle readable?

hIsWritable :: Handle -> IO Bool   

Is the handle writable?

hIsTerminalDevice :: Handle -> IO Bool   

Is the handle connected to a terminal?