System.IO.Dialogue

This module implements stream-based I/O as described in Haskell Report 1.2.

As th resport says, "Haskell's I/O system is based on the view that a program communicates to the outside world via streams of messages: a program issues a stream of requests to the operating system and in return receives a stream of responses." And a stream in Haskell is only a lazy list.

The Program Type

type Dialogue = [Response] -> [Request]

Type of a Haskell program. [Response] is an ordered list of responses and [Request] is an ordered list of requests; the nth response is the operating system's reply to the nth request.

Request Types

data Request

Requests a program may issue.

Constructors

ReadFile Name

ReadFile name returns the contents of file name.

• If successful, the response will be of the form Str s, where s is a string value;
• If the file does not exist, the response Failure (SearchError string) is induced;
• If it is unreachable for some other reason, the Failure (ReadError string) error is induced.

WriteFile Name String

WriteFile name string writes string to file name. If the file does not exist, it is created. If it already exists, it is overwritten.

• A successful response has form Success;
• The only failure possible has the form Failure (WriteError string).

This request is "hyperstrict" in its second argument: no response is returned until the entire list of values is completely evaluated.

AppendFile Name String

Identicle to WriteFile, except that

1. the string argument is appended to the current contents of the file named name;
2. If the file does not exist, the response Failure (SearchError string) is induced.

All other errors have form Failure (WriteError string), and the request is hyperstrict in its second argument.

ReadBinFile Name

Similar to ReadFile, except that if successful, the response will be of the form Bn b, where b is a binary value.

WriteBinFile Name Bin

Similar to WriteFile, except that it writes a binary value to file.

AppendBinFile Name Bin

Similar to AppendFile, except that it writes a binary value to file.

DeleteFile Name

DeleteFile name delete file name, with successful response Success.

• If the file does not exist, the response Failure (SearchError string) is induced.
• If it cannot be deleted for some other reason, a response of the form Failure (WriteError string) is induced.

StatusFile Name

StatusFile name induce Failure (SearchError string) if an object name does not exist, or Failure (OtherError string) if any other error should occur. Otherwise induce Str status where ststus is a string containing, in this order:

1. Either 'f', 'd', or 'u' depending on whether the object is a file, directory, or something else, respectively;
2. 'r' if the object is readable by this program, '-' if not;
3. 'w' if the object is writable by this program, '-' if not;
4. 'x' if the object is executable by this program, '-' if not.

For example, "dr--" denotes a directory that can be read but not written or executed.

ReadChan Name

ReadChan name opens channel name for input.

• A successful response returns the contents of the channel as a lazy stream of characters.
• If the channel does not exist, the response Failure (SearchError string) is induced;
• All other errors have form Failure (ReadError string).

Unlike files, once a ReadChan or ReadBinChan request has been issued for a particular channel, it cannot be issued again for the same channel in that program, This reflects the ephemeral nature of its contents and prevents a serious space leak.

Known issue: This request would leave the handle behind the channel in semi-closed state, causing any other attempt to read from the channel to fail. This should be problematic if your program issued an request to read from stdin, and

1. You called Haskell functions that read from stdin (e.g. getLine), or ran another program that issues such a request after the program finishes.
2. You're running the program from ghci.

AppendChan Name String

AppendChan name string writes string to channel name. The sematics is as for AppendFile, except:

1. The second argument is appended to whatever was previously written (if anything);
2. If channel does not exist, the response Failure (SearchError string) is induced.

All other errors have form Failure (WriteError string). This request is hyperstrict in its second argument.

ReadBinChan Name

Similar to ReadChan, except that if successful, the response will be of the form Bn b, where b is a lazy binary value.

AppendBinChan Name Bin

Similar to AppendChan, except that it writes a binary value to the channel.

StatusChan Name

StatusChan name induces Failure (SearchError string) if an channel name does not exist, otherwise it always induces Str "0 0". The two "0"s indicate that there's no bound on the maximum line length and page length allowed on the channel, respectively.

Echo Bool

Echo True enables echoing of stdin on stdecho; Echo False disables it. Either Success or Failure (OtherError string) is induced.

The report requires that the echo mode can only be set once by a particular program, before any I/O operation involving stdin. However, the restriction is loosened, and echo mode may be set at any time by the proogram multiple times.

Known issue: It's currently implemented as hSetEcho, which is known not to work on Windows.

GetArgs

Induces the response StrList str_list, where str_list is a list of the program's explicit command line arguments.

GetProgName

Returns the short name of the current program, not including search path information. If successful, the response will be of the form Str s, where s is a string. If the operating system is unable to provbide the program name, Failure (OtherError string) is induced.

GetEnv Name

GetEnv name Returns the value of environment variable name. If successful, the response will be of the form Str s, where s is a string. If the environment variable does not exist, a SearchError is induced.

SetEnv Name String

SetEnv name string sets environment variable name to string, with response Success. If the environment variable does not exist, it is created.

Instances

Read Request

Defined in System.IO.Dialogue

Methods

readsPrec :: Int -> ReadS Request

readList :: ReadS [Request]

readPrec :: ReadPrec Request

readListPrec :: ReadPrec [Request]

Show Request

Defined in System.IO.Dialogue

Methods

showsPrec :: Int -> Request -> ShowS

show :: Request -> String

showList :: [Request] -> ShowS

Eq Request

Defined in System.IO.Dialogue

Methods

(==) :: Request -> Request -> Bool

(/=) :: Request -> Request -> Bool

Ord Request

Defined in System.IO.Dialogue

Methods

compare :: Request -> Request -> Ordering

(<) :: Request -> Request -> Bool

(<=) :: Request -> Request -> Bool

(>) :: Request -> Request -> Bool

(>=) :: Request -> Request -> Bool

max :: Request -> Request -> Request

min :: Request -> Request -> Request

The Binary Type

type Bin = ByteString

Bin is a datatype for binary values, as required by the report, and is implemented as a lazy ByteString.

nullBin :: Bin

The empty binary value.

appendBin :: Bin -> Bin -> Bin

Append two Bins.

isNullBin :: Bin -> Bool

Test whether a Bin is empty.

The Name Type

type Name = String

This type synonym is described in Haskell Report 1.0, and exists for backward compatibility.

Channels

stdin :: Name

The stdin channel. Readable.

stdout :: Name

The stdout channel. Writable.

stderr :: Name

The stderr channel. Writable.

stdecho :: Name

The stdecho channel. Writable. Attached to stdout.

Response Types

data Response

Responses a program may receive.

Constructors

Success

Str String

StrList [String]

Bn Bin

Failure IOError

Instances

Read Response

Defined in System.IO.Dialogue

Methods

readsPrec :: Int -> ReadS Response

readList :: ReadS [Response]

readPrec :: ReadPrec Response

readListPrec :: ReadPrec [Response]

Show Response

Defined in System.IO.Dialogue

Methods

showsPrec :: Int -> Response -> ShowS

show :: Response -> String

showList :: [Response] -> ShowS

Eq Response

Defined in System.IO.Dialogue

Methods

(==) :: Response -> Response -> Bool

(/=) :: Response -> Response -> Bool

Ord Response

Defined in System.IO.Dialogue

Methods

compare :: Response -> Response -> Ordering

(<) :: Response -> Response -> Bool

(<=) :: Response -> Response -> Bool

(>) :: Response -> Response -> Bool

(>=) :: Response -> Response -> Bool

max :: Response -> Response -> Response

min :: Response -> Response -> Response

data IOError

Constructors

WriteError String

ReadError String

SearchError String

FormatError String

Since we're using a modern device and the maximum line length and page length allowed on the channel have no bound, this error would never occur.

OtherError String

Instances

Read IOError

Defined in System.IO.Dialogue

Methods

readsPrec :: Int -> ReadS IOError

readList :: ReadS [IOError]

readPrec :: ReadPrec IOError

readListPrec :: ReadPrec [IOError]

Show IOError

Defined in System.IO.Dialogue

Methods

showsPrec :: Int -> IOError -> ShowS

show :: IOError -> String

showList :: [IOError] -> ShowS

Eq IOError

Defined in System.IO.Dialogue

Methods

(==) :: IOError -> IOError -> Bool

(/=) :: IOError -> IOError -> Bool

Ord IOError

Defined in System.IO.Dialogue

Methods

compare :: IOError -> IOError -> Ordering

(<) :: IOError -> IOError -> Bool

(<=) :: IOError -> IOError -> Bool

(>) :: IOError -> IOError -> Bool

(>=) :: IOError -> IOError -> Bool

max :: IOError -> IOError -> IOError

min :: IOError -> IOError -> IOError

Run the Program

runDialogue :: Dialogue -> IO ()

The central function to run a program.