# Standard i/o services

This chapter covers the input/output facilities available in the standard i/o module. The basic operations are related to file manipulations and are later extended to any input or output streams. Later, various file system calls are described.

## Input and output streams

The `afnix-sio` module is based on facilities provided by two base classes, namely, the `InputStream` stream and the `OutputStream` stream. Both classes have associated predicates with the name `input-stream-p` and `output-stream-p`. The base class associated is the `Stream` class those sole purpose is to define the stream coding mode.

### Stream base class

The `Stream` class is the base class for the `InputStream` and `OutputStream` classes. The `Stream` class is used to define the stream coding mode that affects how characters are read or written. When a stream operates in byte mode, each character is assumed to be encoded in one byte. In that case, the input stream methods `read` and `getu` are equivalent and no transformation is performed when writing characters. This behavior is the default stream behavior. For certain stream, like terminal, this behavior is changed depending on the current localization settings. For instance, if the current locale is operating with an UTF-8 codeset, the `Terminal` stream coding mode is automatically adjusted to reflect this situation. Since the US-ASCII codeset is predominant and the default steam coding mode is the byte mode, there should be no conflict during the read and write operations.

### Stream transcoding

The `Stream` class provides the support for the transcoding of different codesets. All ISO-8859 codesets are supported. Since the engine operates internally with Unicode characters, the transcoding operation takes care of changing a character in one particular codeset into its equivalent Unicode representation. This operation is done for an input stream that operates in byte mode. For an output stream, the opposite operation is done. An internal Unicode characters representation is therefore mapped into a particular codeset. Note that only the codeset characters can be mapped.

### Supported stream codesets

Codeset | Description
--- | ---
DEFAULT | Default codeset, i.e US-ASCII
ISO-01 | ISO-8859-1 codeset
ISO-02 | ISO-8859-2 codeset
ISO-03 | ISO-8859-3 codeset
ISO-04 | ISO-8859-4 codeset
ISO-05 | ISO-8859-5 codeset
ISO-06 | ISO-8859-6 codeset
ISO-07 | ISO-8859-7 codeset
ISO-08 | ISO-8859-8 codeset
ISO-09 | ISO-8859-9 codeset
ISO-10 | ISO-8859-10 codeset
ISO-11 | ISO-8859-11 codeset
ISO-13 | ISO-8859-13 codeset
ISO-14 | ISO-8859-14 codeset
ISO-15 | ISO-8859-15 codeset
ISO-16 | ISO-8859-16 codeset
UTF-08 | Unicode UTF-8 codeset

The `set-encoding-mode` can be used to set the stream encoding codeset. The method operates either by enumeration or string. The `get-encoding-mode` returns the stream encoding mode. There are some time good reasons to force a stream encoding mode. For example, a file encoded in UTF-8 that is read will require this call since the default stream mode is to work in byte mode. It should be noted that there is a difference between the enumeration and the string encoding mode. The enumeration mode defines whether the stream operates in byte or UTF-8 mode. When the stream operates in byte mode, it is also necessary to define the transcoding mode with the `set-transcoding-mode` method. For simplicity, the string version of the `set-encoding-mode` takes care of setting both the stream mode and the transcoding mode. It is also worth to note that internally, the `Stream` class is derived from the `Transcoder` class.

### Input stream

The `InputStream` base class has several method for reading and testing for byte availability. Moreover, the class provides a push-back buffer. Reading bytes is in the form of three methods. The `read` method without argument returns the next available byte or the end-of-stream `eos`. With an integer argument, the `read` method returns a `Buffer` with at most the number of requested bytes. The `readln` method returns the next available line. When it is necessary to read characters instead of bytes, the `getu` is more appropriate since it returns an Unicode character.

### Output stream

The `OutputStream` base class provides the base methods to write to an output stream. The `write` method takes literal objects which are automatically converted to string representation and then written to the output stream. Note that for the case of a `Buffer` object, it is the buffer itself that take a stream argument and not the opposite.

### The valid-p predicate

The input stream provides a general mechanism to test and read for bytes. The base method is the `valid-p` predicate that returns `true` if a byte can be read from the stream. It is important to understand its behavior which depends on the stream type.

Without argument, the `valid-p` predicate checks for an available byte from the input stream. This predicate will block if no byte is available. On the other end, for a bounded stream like an input file, the method will not block at the end of file. With one integer argument, the `valid-p` predicate will timeout after the specified time specified in milliseconds. This second behavior is particularly useful with unbound stream like socket stream.

### The eos-p predicate

The `eos-p` predicate does not take argument. The predicate behaves like `not (valid-p 0)`. However, there are more subtle behaviors. For an input file, the predicate will return `true` if and only if a byte cannot be read. If a byte has been pushed-back and the end-of-stream marker is reached, the method will return false. For an input terminal, the method returns true if the user and entered the end-of-stream byte. Once again, the method reacts to the contents of the push-back buffer. For certain input stream, like a tcp socket, the method will return true when no byte can be read, that is here, the connection has been closed. For an udp socket, the method will return `true` when all datagram bytes have be read.

### The read method

The `read` method is sometimes disturbing. Nevertheless, the method is a blocking one and will return a byte when completed. The noticeable exception is the returned byte when an end-of-stream marker has been reached. The method returns the ctrl-d byte. Since a binary file might contains valid byte like ctrl-d it is necessary to use the `valid-p` or `eos-p` predicate to check for a file reading completion. This remark apply also to bounded streams like a tcp socket. For some type of streams like a udp socket, the method will block when all datagram bytes have been consumed and no more datagram has arrived. With this kind of stream, there is no end-of-stream condition and therefore care should be taken to properly assert the stream content. This last remark is especially true for the `readln` method. The method will return when the end-of-stream marker is reached, even if a newline byte has not been read. With an udp socket, such behavior will not happen.

### Buffer read mode

The `read` method with an integer argument, returns a buffer with at least the number of bytes specified as an argument. This method is particularly useful when the contents has a precise size. The method returns a `Buffer` object which can later be used to read, or transform bytes. Multi-byte conversion to number should use such approach. The `read` method does not necessarily returns the number of requested bytes. Once the buffer is returned, the `length` method can be used to check the buffer size. Note also the existence of the `to-string` method which returns a string representation of the buffer.

# try to read 256 bytes const buf (is:read 256) # get the buffer size println (buf:length) # get a string representation println (buf:to-string)

## File stream

The `afnix-sio` module provides two classes for file access. The `InputFile` class open a file for input. The `OutputFile` class opens a file for output. The `InputFile` class is derived from the `InputStream` base class. The `OutputFile` class is derived from the `OutputStream` class. By default an output file is created if it does not exist. If the file already exist, the file is truncated to 0. Another constructor for the output file gives more control about this behavior. It takes two boolean flags that defines the truncate and append mode.

# load the module interp:library "afnix-sio" # create an input file by name const if (afnix:sio:InputFile "orig.txt") # create an output file by name const of (afnix:sio:OutputFile "copy.txt")

### Stream information

Both `InputFile` and `OutputFile` supports the `get-name` method which returns the file name.

println (if:get-name) println (of:get-name)

Predicates are also available for these classes. The `input-file-p` returns true for an input file object.The `output-file-p` returns true for an output file object.

afnix:sio:input-stream-p if afnix:sio:output-stream-p of afnix:sio:input-file-p if afnix:sio:output-file-p of

### Reading and writing

The `read` method reads a byte on an input stream. The `write` method writes one or more literal arguments on the output stream. The `writeln` method writes one or more literal arguments followed by a newline byte on the output stream. The `newline` method write a newline byte on the output stream. The `eos-p` predicate returns true for an input stream, if the stream is at the end. The `valid-p` predicate returns true if an input stream is in a valid state. With these methods, copying a file is a simple operation.

# load the module and open the files interp:library "afnix-sio" const if (afnix:sio:InputFile "orig.txt") const of (afnix:sio:OutputFile "copy.txt")

# loop in the input file and write while (if:valid-p) (of:write (if:read))

The use of the `readln` method can be more effective. The example below is a simple cat program which take the file name an argument.

# cat a file on the output terminal # usage: axi 0601.als file

# get the io module interp:library "afnix-sio"

# cat a file const cat (name) { const f (afnix:sio:InputFile name) while (f:valid-p) (println (f:readln)) f:close }

# get the file if (== 0 (interp:argv:length)) { errorln "usage: axi 0601.als file" } { cat (interp:argv:get 0) }

## Multiplexing

I/O multiplexing is the ability to manipulate several streams at the same time and process one at a time. Although the use of threads reduce the needs for i/o multiplexing, there is still situations where they are needed. In other words, I/O multiplexing is identical to the `valid-p` predicate, except that it works with several stream objects.

### Selector object

I/O multiplexing is accomplished with the `Selector` class. The constructor takes 0 or several stream arguments. The class manages automatically to differentiate between `InputStream` stream and `OutputStream` streams. Once the class is constructed, it is possible to get the first stream ready for reading or writing or all of them. We assume in the following example that `is` and `os` are respectively an input and an output stream.

# create a selector const slt (afnix:sio:Selector is)

# at this stage the selector has one stream # the add method can add more streams slt:add os

The `add` method adds a new stream to the selector. The stream must be either an `InputStream` and `OutputStream` stream or an exception is raised. If the stream is both an input and an output stream, the preference is given to the input stream. If this preference is not acceptable, the `input-add` or the `output-add` methods might be preferable. The `input-length` method returns the number of input streams in this selector. The `output-length` method returns the number of output streams in this selector. The `input-get` method returns the selector input stream by index. The `output-get` method returns the selector output stream by index.

### Waiting for i/o event

The `wait` and `wait-all` methods can be used to detect a status change in the selector. Without argument both methods will block indefinitely until one stream change. With one integer argument, both method blocks until one stream change or the integer argument timeout expires. The timeout is expressed in milliseconds. Note that 0 indicates an immediate return. The `wait` method returns the first stream which is ready either for reading or writing depending whether it is an input or output stream. The `wait-all` method returns a vector with all streams that have changed their status. The `wait` method returns `nil` if the no stream have changed. Similarly, the `wait-all` method returns an empty vector.

# wait for a status change const is (slt:wait) # is is ready for reading - make sure it is an input one if (afnix:sio:input-stream-p is) (is:read)

A call to the `wait` method will always returns the first input stream.

### Marking mode

When used with several input streams in a multi-threaded context, the selector behavior can becomes quite complicated. For this reason, the selector can be configured to operate in marking mode. In such mode, the selector can be marked as ready by a thread independently of the bounded streams. This is a useful mechanism which can be used to cancel a select loop. The `mark` method is designed to mark the selector while the `marked-p` predicate returns true if the stream has been marked.

## Terminal streams

Terminal streams are another kind of streams available in the standard i/o module. The `InputTerm`, `OutputTerm` and `ErrorTerm` classes are low level classes used to read or write from or to the standard streams. The basic methods to read or write are the same as the file streams. Reading from the input terminal is not a good idea, since the class does not provide any formatting capability. One may prefer to use the `Terminal` class. The use of the output terminal or error terminal streams is convenient when the interpreter standard streams have been changed but one still need to print to the terminal.

### Terminal class

The `Terminal` class combines an input stream and an output stream with some line editing capabilities. When the class is created, the constructed attempts to detect if the input and output streams are bounded to a terminal (i.e tty). If the line editing capabilities can be loaded (i.e non canonical mode), the terminal is initialized for line editing. Arrows, backspace, delete and other control sequences are available when using the `read-line` method. The standard methods like `read` or `readln` do not use the line editing features. When using a terminal, the prompt can be set to whatever the user wishes with the methods `set-primary-prompt` or `set-secondary-prompt`. A secondary prompt is displayed when the `read-line` method is called with the boolean argument false.

const term (Terminal) term:set-primary-prompt "demo:" const line (term:read-line) errorln line

### Using the error terminal

The `ErrorTerm` class is the most frequently used class for printing data on the standard error stream. The reserved keywords `error` or `errorln` are available to write on the interpreter error stream. If the interpreter error stream has been changed, the use of the `ErrorTerm` will provide the facility required to print directly on the terminal. The `cat` program can be rewritten to do exactly this.

# cat a file on the error terminal

# get the io module interp:library "afnix-sio"

# cat a file const cat (name es) { const f (afnix:sio:InputFile name) while (f:valid-p) (es:writeln (f:readln)) f:close }