# Standard i/o reference

This appendix is a reference of the standard i/o module.

## Standard i/o module

Symbol | Description
--- | ---
afnix-sio | module
afnix:sio | nameset

Transcoder

The `Transcoder` class is a codeset transcoder class. The class is responsible to map a byte character in a given codeset into its associated unicode character. It should be noted that not all characters can be transcoded.

transcoder-p
Object
DEFAULT

The `DEFAULT` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode. In default mode, each character is not transcoded. This mode is the identity mode.

I8859-01

The `I8859-01` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-6 codeset.

I8859-02

The `I8859-02` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-2 codeset.

I8859-03

The `I8859-03` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-3 codeset.

I8859-04

The `I8859-04` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-4 codeset.

I8859-05

The `I8859-05` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-5 codeset.

I8859-06

The `I8859-06` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-6 codeset.

I8859-07

The `I8859-07` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-7 codeset.

I8859-08

The `I8859-08` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-8 codeset.

I8859-09

The `I8859-09` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-9 codeset.

I8859-10

The `I8859-10` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-10 codeset.

I8859-11

The `I8859-11` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-11 codeset.

I8859-13

The `I8859-13` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-13 codeset.

I8859-14

The `I8859-14` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-14 codeset.

I8859-15

The `I8859-15` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-15 codeset.

I8859-16

The `I8859-16` constant is used by the `set-transcoding-mode` method to specify the class transcoding mode that corresponds to the ISO-8859-16 codeset.

Transcoder
none

The `Transcoder` constructor creates a default transcoder that operates in default mode by using the identity function.

Transcoder
constant

The `Transcoder` constructor creates a transcoder with the argument mode.

set-transcoding-mode
none
constant

The `set-transcoding-mode` method sets the class transcoding mode.

get-transcoding-mode
constant
none

The `get-transcoding-mode` method returns the class transcoding mode.

valid-p
Byte|Character
Boolean

The `valid-p` predicate returns true if character can be transcoded. If the argument is a byte, the method returns true if the byte can be transcoded to a character. If the argument is a character, the method returns true if the character can be transcoded to a byte.

encode
Byte
Character

The `encode` method encodes a byte into a character. If the character cannot be encoded, an exception is raised.

decode
Character
Byte

The `decode` method decodes a character into a byte. If the character cannot be decoded, an exception is raised.

Stream

The `Stream` class is a base class for the standard streams. The class is automatically constructed by a derived class and provides the common methods for all streams.

stream-p
Transcoder
BYTE

The `BYTE` constant is used by the `set-coding-mode` method to specify the stream coding mode. In byte mode, each character is assumed to be coded with one byte. This value affects the `rduc` and `write` methods

UTF-8

The `UTF-8` constant is used by the `set-coding-mode` method to specify the stream coding mode. In utf-8 mode, each character is assumed to be coded in the UTF-8 representation. This value affects the `rduc` and `write` methods

set-encoding-mode
none
constant|String

The `set-encoding-mode` method sets the stream coding mode that affects how characters are read or written. In the enumeration form, the method only sets the stream coding mode which is either byte or UTF-8 mode. In the string mode, the method sets the stream encoding mode and the transcoding mode.

get-encoding-mode
constant
none

The `get-coding-mode` method returns the stream coding mode which affects how characters are read or written.

Input

The `Input` class is a base class for the standard i/o module. The class is automatically constructed by a derived class and provides the common methods for all input streams.

input-p
Stream
read
Byte
none

The `read` method returns the next byte available from the input stream. If the stream has been closed or consumed, the eof byte is returned.

read
Buffer
Integer

The `read` method returns a buffer object with at most the number of bytes specified as an argument. The buffer `length` method should be used to check how many bytes have been placed in the buffer.

readln
String
none

The `readln` method returns the next line available from the input stream. If the stream has been closed or consumed, the eof byte is returned.

rduc
Character
none

The `rduc` method returns the next available Unicode character from the input stream. If the stream has been closed or consumed, the eof byte is returned. During the read process, if the character decoding operation fails, an exception is raised.

valid-p
Boolean
none|Integer

The `valid-p` method returns true if the input stream is in a valid state. By valid state, we mean that the input stream can return a byte with a call to the read method. With one argument, the method timeout after the specified time in milliseconds. If the timeout is null, the method returns immediately. With -1, the method blocks indefinitely if no byte is available.

eof-p
Boolean
none

The `eof-p` method returns true if the input stream has been closed or all bytes consumed.

pushback
none
Byte|Character|String

The `pushback` method push-back a byte, an Unicode character or a string in the input stream. Subsequent calls to read will return the last pushed bytes. Pushing a string is equivalent to push each bytes of the string.

get-buffer-length
Integer
none

The `get-buffer-length` method returns the length of the push-back buffer.

InputFile

The `InputFile` class provide the facility for an input file stream. An input file instance is created with a file name. If the file does not exist or cannot be opened, an exception is raised. The `InputFile` class is derived from the `Input` class.

input-file-p
Input
Nameable
InputFile
String

The `InputFile` constructor create an input file by name. If the file cannot be created, an exception is raised. The first argument is the file name to open.

InputFile
String String

The `InputFile` constructor create an input file by name and encoding mode. If the file cannot be created, an exception is raised. The first argument is the file name to open.The second argument is the encoding mode to use.

close
Boolean
none

The `close` method close the input file and returns true on success, false otherwise. In case of success, multiple calls return true.

lseek
none
Integer

The `lseek` set the input file position to the integer argument. Note that the push-back buffer is reset after this call.

length
Integer
none

The `length` method returns the length of the input file. The length is expressed in bytes.

InputMapped

The `InputMapped` class provide the facility for an input file stream with offset and size. The class is similar to the `InputFile` class except that the constructor can also accepts an integer offset and size argument. If the file offset or size are out of range, the class behaves like an input file. If the file does not exist or cannot be opened, an exception is raised.

input-mapped-p
Input
Nameable
InputMapped
String

The `InputFile` constructor create an input mapped file by name. If the file cannot be created, an exception is raised. The first argument is the file name to open.

InputMapped
String Integer Integer

The `InputFile` constructor create an input mapped file by name and offset. If the file cannot be created, an exception is raised. The first argument is the file name to open. The second argument is the offset inside that file. The third argument is the size that should be used for this mapped file.

lseek
none
Integer

The `lseek` set the input mapped file position to the integer argument. Note that the push-back buffer is reset after this call.

length
Integer
none

The `length` method returns the length of the input mapped file. The length is expressed in bytes.

get-offset
Integer
none

The `get-name` method returns the input mapped file offset.

InputString

The `InputString` class provide the facility for an input string stream. The class is initialized or set with a string and then behaves like a stream. This class is very useful to handle generic stream method without knowing what kind of stream is behind it.

input-string-p
Input
InputString
none

The `InputString` constructor creates an empty input string.

InputString
String

The `InputString` constructor creates an input string by value.

get
Byte
none

The `get` method returns the next available byte from the input stream but do not remove it.

set
none
String

The `set` method sets the input string by first resetting the push-back buffer and then initializing the input string with the argument value.

InputTerm

The `InputTerm` class provide the facility for an input terminal stream. The input terminal reads byte from the standard input stream. No line editing facility is provided with this class This is a low level class, and normally, the `Terminal` class should be used instead.

input-term-p
Input
Output
InputTerm
none

The `InputTerm` constructor creates a default input terminal.

set-eof-ignore
none
Boolean

The `set-eof-ignore` method set the input terminal ctrl-d ignore flag. When the flag is on, any byte that match a ctrl-d is changed to the re-mapped byte and returned by a read. This method is useful to prevent a reader to exit when the ctrl-d byte is generated.

set-eof-byte
none
Byte

The `set-eof-byte` method set the input terminal ctrl-d re-mapping byte. By default the byte is set to the end-of-line byte. This method should be used in conjunction with the `set-eof-ignore` method.

Output

The `Output` class is a base class for the standard i/o module. The class is automatically constructed by a derived class and provide the common methods for all output streams.

output-p
Stream
write
none
Literal+

The `write` method write one or more literal arguments on the output stream. This method returns nil;

writeln
none
Literal+

The `writeln` method write one or more literal argument to the output stream and finish with a newline. This method return nil.

errorln
none
Literal+

The `errorln` method write one or more literal argument to the associated output error stream and finish with a newline. Most of the time, the output stream and error stream are the same except for an output terminal.

newline
none
none

The `newline` method writes a new line byte to the output stream. The method returns nil.

OutputFile

The `OutputFile` class provide the facility for an output file stream. An output file instance is created with a file name. If the file does not exist, it is created. If the file cannot be created, an exception is raised. Once the file is created, it is possible to write literals. The class is derived from the `Output` 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. The t-flag is the truncate flag. The a-flag is the append flag.

output-file-p
Output
Nameable
OutputFile
String

The `OutputFile` constructor create an output file by name. If the file cannot be created, an exception is raised. The first argument is the file name to create.

OutputFile
String String

The `OutputFile` constructor create an output file by name and encoding mode. If the file cannot be created, an exception is raised. The first argument is the file name to create. The second argument is the encoding mode to use.

OutputFile
String Boolean Boolean

The `OutputFile` constructor create an output file by name. If the file cannot be created, an exception is raised. The first argument is the file name to create. The second argument is the truncate flag. If the file already exists and the truncate flag is set, the file is truncated to 0. The third argument is the append mode. If set to true, the file is open in append mode.

close
Boolean
none

The `close` method closes the output file and returns true on success, false otherwise. In case of success, multiple calls returns true.

OutputString

The `OutputString` class provide the facility for an output string stream. The class is initially empty and acts as a buffer which accumulate the write method bytes. The `to-string` method can be used to retrieve the buffer content.

output-string-p
Output
OutputString
none

The `OutputString` constructor creates a default output string.

OutputString
String

The `OutputString` constructor creates an output string by value. The output string stream is initialized with the string value.

flush
none
none

The `flush` method flushes the output string stream by resetting the string buffer.

to-string
String
none

The `to-string` method returns a string representation of the output string buffer.

OutputTerm

The `OutputTerm` class provide the facility for an output terminal. The output terminal is defined as the standard output stream. If the standard error stream needs to be used, the `ErrorTerm` class is more appropriate.

output-term-p
Output
OutputTerm
none

The `OutputTerm` constructor creates a default output terminal

ErrorTerm
none

The `ErrorTerm` constructor creates a default error terminal

Terminal

The `Terminal` class provides the facility for an i/o terminal with line editing capability. The class combines the `InputTerm` and `OutputTerm` methods.

terminal-p
InputTerm
OutputTerm
Terminal
none

The `Terminal` constructor creates a default terminal which combines an input and output terminal with line editing capabilities.

set-primary-prompt
none
String

The `set-primary-prompt` method sets the terminal primary prompt which is used when the `read-line` method is called.

set-secondary-prompt
none
String

The `set-secondary-prompt` method sets the terminal secondary prompt which is used when the `read-line` method is called.

get-primary-prompt
String
none

The `get-primary-prompt` method returns the terminal primary prompt.

get-secondary
String
none

The `get-secondary-prompt` method returns the terminal secondary prompt.

Selector

The `Selector` class provides some facilities to perform i/o multiplexing. The constructor takes 0 or several stream arguments.The class manages automatically to differentiate between `Input` and `Output` streams. Once the class is constructed, it is possible to get the first stream ready for reading or writing or all of them. It is also possible to add more steams after construction with the `add` method. When used with several input streams in a multi-threaded context, the selector behavior can becomes quite complicated. Either `wait` and `wait-all` methods check first the input streams push-back buffer. If one or several buffer are not empty, the method returns with these streams. During this operation, the input streams are locked, so no other thread can push-back a byte. The selector then checks for status change and unlock the streams. Note that the output streams are not locked. Note also that a thread which rely on the input stream push-back method to release a selector will result in a dead-lock.

selector
Object
Selector
none

The `Selector` constructor creates a default stream selector.

Selector
[Input|Output]*

The `Selector` constructor creates a stream selector with 0 or more stream arguments.

add
none
Input|Output

The `add` method adds an input or output stream to the selector.

wait
Object
none|Integer

The `wait` method waits for a status change in the selector and returns the first stream that has change status. With one argument, the selector time-out after the specified time in milliseconds. Note that at the time of the return, several streams may have changed status.

wait-all
Vector
none|Integer

The `wait` method waits for a status change in the selector and returns all streams that has change status in a vector object. With one argument, the selector time-out after the specified time in milliseconds. If the selector has timed-out, the vector is empty.

input-get
Input
Integer

The `input-get` method returns the input streams in the selector by index. If the index is out of bound, an exception is raised.

output-get
Output
Integer

The `output-get` method returns the output streams in the selector by index. If the index is out of bound, an exception is raised.

input-length
Integer
none

The `input-length` method returns the number of input streams in the selector.

output-length
Integer
none

The `output-length` method returns the number of output streams in the selector.

Logtee

The `Logtee` class provides the facility of a logger object associated with an output stream. When a message is added, the message is written to the output stream depending on an internal flag. By default the tee mode is false and can be activated with the `set-tee` method.

logtee-p
Logger
Logtee
none

The `Logtee` constructor creates a default logger without an output stream.

Logtee
Integer

The `Logtee` constructor creates a logger with a specific size without an output stream. terminal

Logtee
Output

The `Logtee` constructor creates a logger with an output stream. The object is initialized to operate in write mode.

Logtee
Integer Output

The `Logtee` constructor creates a logger with a specific size with an output stream. The first argument is the logger size. The second argument is the output stream.

Logtee
Integer String Output

The `Logtee` constructor creates a logger with a specific size, an information string and an output stream. The first argument is the logger size. The second argument is information string. The third argument is the output stream.

set-tee-stream
none
Output

The `set-tee-stream` method sets the tee output stream. This stream is different from the logger output stream

get-tee-stream
Output
none

The `get-tee-stream` method returns the object output stream.

set-tee
none
Boolean

The `set-tee` method sets the object tee flag. When the flag is true, the logger writes the added message on the output stream.

get-tee
Boolean
none

The `get-tee` method returns the object tee flag. When the flag is true, the logger writes the added message on the output stream.

Pathname

The `Pathname` class is a base class designed to manipulate system i/o paths. The class operates with a directory name and a file name. Both names are kept separated to ease the path manipulation. The path components can be extracted individually. However, it shall be noted that the first componenent has a special treatment to process the root directory name.

pathname-p
Object
Pathname
none

The `Pathname` constructor creates a default path name without file and directory names.

Pathname
String

The `Pathname` constructor creates a path name with a file name. The first string argument is the file name.

Pathname
String String

The `Pathname` constructor creates a pathname with a file and directory name. The first string argument is the file name. The second string argument is the directory name.

set-file-name
none
String

The `set-file-name` method set the path name file name. The string argument is the file name.

get-file-name
String
none

The `get-file-name` method returns the path name file name.

set-directory-name
none
String

The `set-directory-name` method set the directory name file name. The string argument is the directory name.

get-directory-name
String
none

The `get-directory-name` method returns the path name directory name.

length
Integer
none

The `length` method returns the number of directory path elements.

get-path
String
Integer

The `get-path` method returns a directory path element by index.

add-path
none
String

The `add-path` method add a new path component by name. The string argument is the name to add.

get-root
String
none

The `get-root` method returns the root component of a directory name.

get-full
String
none

The `get-full` method returns the full path name by combining the directory name with the file name.

dir-p
Boolean
String

The `dir-p` function returns true if the argument name is a directory name, false otherwise.

file-p
Boolean
String

The `file-p` function returns true if the argument name is a regular file name, false otherwise.

tmp-name
String
String?

The `tmp-name` function returns a name suitable for the use as a temporary file name. Without argument, a default prefix is used to build the name. An optional string prefix can control the original name.

tmp-path
String
String?

The `tmp-path` function returns a path suitable for the use as a temporary file name. Without argument, a default prefix is used to build the path. An optional string prefix can control the original name.

absolute-path
String
String+

The `absolute-path` function returns an absolute path name from an argument list. Without argument, the command returns the root directory name. With one or several argument, the absolute path is computed from the root directory.

relative-path
String
String+

The `relative-path` function returns a relative path name from an argument list. With one argument, the function returns it. With two or more arguments, the relative path is computed by joining each argument with the previous one.

rmfile
none
String+

The `rmfile` function removes one or several files specified as the arguments. If one file fails to be removed, an exception is raised.

mkdir
none
String+

The `mkdir` function creates one or several directories specified as the arguments. If one directory fails to be created, an exception is raised.

mhdir
none
String+

The `mhdir` function creates hierarchicaly one or several directories specified as the arguments. If one directory fails to be created, an exception is raised.

rmdir
none
String+

The `rmdir` function removes one or several directories specified as the arguments. If one directory fails to be removed, an exception is raised.

get-base-name
String
String

The `get-base-name` function returns the base name from a path. The base name can be either a file name or a directory name. By definition, a path is made of a base path and a base name.

get-base-path
String
String

The `get-base-path` function returns the base path from a path. The base path is a directory name. By definition, a path is made of a base path and a base name.

get-extension
String
String

The `get-extension` function returns the extension from a path.

remove-extension
String
String

The `remove-extension` function returns the extension from a path. In order to get a base file name from a path, the `get-base-name` function must be called first.