| Standard Input/Output Module

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.

All AFNIX standard i/o objects are located in the `afnix-sio` module. This module must be loaded prior any operation. Multiple calls to the module initialization routine are harmless. The interpreter method `module` loads a specific module by name. When the module has been loaded, the object are available in the `afnix:sio` nameset.

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 AFNIX 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.

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.

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.

Stream information

Both `InputFile` and `OutputFile` supports the `get-name` method which returns the file 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.

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.

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.

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.

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. 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.

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

Multiplexing policy

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 buffers 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.

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.

Using the error terminal

The `ErrorTerm` class is the most frequently used class for printing data on the standard error stream. AFNIX provides the reserved keyword `error` or `errorln` 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.

Special i/o objects

This chapter is dedicated to special facilities which are part of the standard i/o module.

Directory

The `Directory` class provides a facility to manipulate directories. A directory object is created either by name or without argument by considering the current working directory. Once the directory object is created, it is possible to retrieve its contents, create new directory or remove empty one.

Reading a directory

A `Directory` object is created either by name or without argument. With no argument, the current directory is opened. When the current directory is opened, its full name is computed internally and can be retrieved with the `get-name` method.

Once the directory object is opened, it is possible to list its contents. The `get-list` method returns the full contents of the directory object. The `get-files` method returns a list of files in this directory. The `get-subdirs` method returns a list of sub directories in this directory.

Creating and removing directories

The `mkdir` and `rmdir` methods can be used to create or remove a directory. Both methods take a string argument and construct a full path name from the directory name and the argument. This approach has the advantage of being file system independent. If the directory already exists, the `mkdir` methods succeeds. The `rmdir` method requires the directory to be empty.

The function `absolute-path` constructs an absolute path name from the argument list. If relative path needs to be constructed, the function `relative-path` might be used instead.

Logtee

The `Logtee` class is a message logger facility associated with an output stream. When a message is added to the logger object, the message is also sent to the output stream, depending on the controlling flags. The name "logtee" comes from the contraction of "logger" and "tee". One particularity of the class is that without a stream, the class behaves like a regular logger.

Creating a logger

The `Logtee` default constructor creates a standard logger object without an output stream. The instance can also be created by size or with an output stream or both. A third method can also attach an information string.

Adding messages

The process of adding messages is similar to the regular logger. The only difference is that the message is placed on the output stream if a control flag is set and the message level is less or equal the report level. In the other word, the control flag controls the message display -- the tee operation -- while the report level filters some of the messages.

The `set-tee` method sets the control flag. The `set-report-level` method sets the report level. Note that the `set-report-level` and its associated `get-report-level` method is part of the base `Logger` class.

Path name

The `Pathname` class is a base class designed to ease the manipulation of system path. It is particularly useful when it come to manipulate directory component.

Creating a path name

A path name is created either by file name or by file and directory name. In the first case, only the file name is used. In the second case, the full path name is characterized.

Adding a directory path

The best way to add a directory path is to use the `absolute-path` or the `relative-path` functions.

Getting the path information

The path information can be obtained individually or globally. The `get-file-name` and `get-directory-name` methods return respectively the file and directory name. The `get-root` method returns the root component of the directory name. The `get-full` method returns the full path name.

Standard i/o reference

This appendix is a reference of the AFNIX 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.

Predicate

    transcoder-p

Inheritance

    Object

Constants

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.

Constructors

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.

Methods

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 AFNIX standard streams. The class is automatically constructed by a derived class and provides the common methods for all streams.

Predicate

    stream-p

Inheritance

    Transcoder

Constants

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 getu 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 getu and write methods

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.

InputStream

The `InputStream` class is a base class for the AFNIX standard i/o module. The class is automatically constructed by a derived class and provides the common methods for all input streams. The input stream is associated with a timeout value which is used for read operation. By default, timeout is infinite, meaning that any read without data will be a blocking one.

Predicate

    input-stream-p

Inheritance

    Stream

Methods

flush (→ none|Character) (none)

The flush method the input stream buffer. In the first form, without argument, the input stream buffer is entirely flushed. In the second form, the input stream buffer is flushed until the character argument is found.

get-timeout (→ Integer) (none)

The get-timeout method returns the input stream timeout. A negative value is a blocking timeout.

set-timeout (→ none) (Integer)

The set-timeout method sets the input stream timeout. A negative value is a blocking timeout. Chaning the stream timeout does not cancel any pending read operation.

read (→ Byte) (none)

The read method returns the next byte available from the input stream. If the stream has been closed or consumed, the end-of-stream 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 end-of-stream character is returned.

getu (→ Character) (none)

The getu method returns the next available unicode character from the input stream. If the stream has been closed or consumed, the end-of-stream character 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.

eos-p (→ Boolean) (none)

The eos-p predicate returns true if the input stream has been closed or all bytes consumed.

pushback (→ Integer) (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 encoded bytes of the string. The method returns the number of bytes pushed back.

get-buffer-length (→ Integer) (none)

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

to-string (→ String) (none)

The to-string method returns a string representation of the input stream 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 `InputStream` class.

Predicate

    input-file-p

Inheritance

    InputStream
    Nameable

Constructors

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.

Methods

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.

get-modification-time (→ Integer) (none)

The get-modification-time method returns the modification time of the file in the form of an atc time. The returned argument is suitable for the Time and Date system classes.

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.

Predicate

    input-mapped-p

Inheritance

    InputStream
    Nameable

Constructors

InputMapped (String)

The InputMapped 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 InputMapped 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.

Methods

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-modification-time (→ Integer) (none)

The get-modification-time method returns the modification time of the file in the form of an atc time. The returned argument is suitable for the Time and Date system classes.

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.

Predicate

    input-string-p

Inheritance

    InputStream

Constructors

InputString (none)

The InputString constructor creates an empty input string.

InputString (String)

The InputString constructor creates an input string by value.

Methods

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.

Predicate

    input-term-p

Inheritance

    InputStream
    OutputStream

Constructors

InputTerm (none)

The InputTerm constructor creates a default input terminal.

Methods

set-ignore-eos (→ none) (Boolean)

The set-ignore-eos method set the input terminal end-of-stream ignore flag. When the flag is on, any character that match a ctrl-d is changed to the end-of-stream mapped character returned by a read. This method is useful to prevent a reader to exit when the ctrl-d byte is generated.

set-mapped-eos (→ none) (Byte)

The set-mapped-eos method set the input terminal end-of-stream mapped character. By default the character is set to end-of-line. This method should be used in conjunction with the set-ignore-eos method.

OutputStream

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

Predicate

    output-stream-p

Inheritance

    Stream

Methods

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.

write-soh (→ none) (none)

The write-soh method writes a start-of-heading character to the output stream.

write-stx (→ none) (none)

The write-stx method writes a start-of-transmission character to the output stream.

write-etx (→ none) (none)

The write-etx method writes an end-of-transmission character to the output stream.

write-eos (→ none) (none)

The write-eos method writes an end-of-stream character to the output stream.

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 `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. The t-flag is the truncate flag. The a-flag is the append flag.

Predicate

    output-file-p

Inheritance

    OutputStream
    Nameable

Constructors

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.

Methods

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.

Predicate

    output-string-p

Inheritance

    OutputStream

Constructors

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.

Methods

flush (→ none) (none)

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

get-buffer-length (→ Integer) (none)

The get-buffer-length method returns the length of the output 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.

Predicate

    output-term-p

Inheritance

    OutputStream

Constructors

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.

Predicate

    terminal-p

Inheritance

    InputTerm
    OutputTerm

Constructors

Terminal (none)

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

Methods

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.

InputOutput

The `InputOutput` class implements an input-output stream with a buffer which holds character during the processing of transit between the output stream to the input stream. The theory of operation goes as follow. The internal buffer is filled with characters with the help of the output stream. The characters are consumed from the buffer with the help of the input stream (read method). If the buffer becomes empty the iseos returns true and the valid method false. The read method will return the eos character. This class does not provide any blocking mechanism in the case there is no character available.

Predicate

    input-output-p

Inheritance

    InputStream
    OutputStream

Constructors

InputOutput (none)

The InputOutput constructor creates a default input/output stream.

InputOutput (String)

The InputOutput constructor creates an input/output stream initialized with the string argument. The string argument is used to fill the string buffer.

Methods

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.

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 `InputStream` 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. 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.

Predicate

    selector

Inheritance

    Object

Constructors

Selector (none)

The Selector constructor creates a default stream selector.

Selector ([InputStream|OutputStream]*)

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

Methods

add (→ none) (InputStream|OutputStream)

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 (→ InputStream) (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 (→ OutputStream) (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.

Predicate

    logtee-p

Inheritance

    Logger

Constructors

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 (OutputStream)

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

Logtee (Integer OutputStream)

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

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.

Methods

set-tee-stream (→ none) (OutputStream)

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

get-tee-stream (→ OutputStream) (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.

Predicate

    pathname-p

Inheritance

    Object

Constructors

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.

Methods

reset (→ none) (none)

The reset method reset the path name by removing all path and file information.

dir-p (→ Boolean) (none)

The dir-p predicate returns true if the path is a directory.

file-p (→ Boolean) (none)

The file-p predicate returns true if the path is a file.

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.

add-directory-name (→ none) (String)

The add-directory-name method add the directory name to the directory path component. The string argument is the directory 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.

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.

add-path (→ none) (String)

The add-path method add a new path component by name. The path is separated into individual component and added to the directory path unless it is a root path. If the file name is set, the file name is added as a directory component. If the path is a root path, a new path name is rebuilt. This last case is equivalent to a call to set-file-name.

normalize (→ none) (none)

The normalize method rebuild the path name by determining the full path nature if possible. In case of success, the path structure reflects the actual path type.

Pathlist

The `Pathlist` class is a base class designed to ease the manipulation of a file search path. The class acts like a list of search paths and various facilities are provided to find a valid path for a given name. The path list can be manipulated like any other list.

Predicate

    pathlist-p

Inheritance

    Object

Constructors

Pathlist (none)

The Pathlist constructor creates a default path list.

Pathlist (Boolean|String)

The Pathlist constructor creates a path list with a local search flag or with an initial path component. In the first form, a boolean argument controls the local search flag. In the second for, a string argument is used as the initial path component.

Methods

reset (→ none) (none)

The reset method resets the path list by clearing the local search flag and removing all path components.

local-p (→ Boolean) (none)

The local-p predicate returns true if the local search flag is set.

set-local-search (→ none) (Boolean)

The set-local-search method sets the local search flag.

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.

file-p (→ Boolean) (String)

The file-p predicate returns true if the file name argument can be resolved. If the local search flag is set, the local directory is check first.

resolve (→ String) (String)

The resolve method returns a string represenation of the resolved file path. If the local search flag is set and the file name is found localy, the initial name argument is returned.

Functions

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.

Special i/o objects reference

Directory

The `Directory` class provides some facilities to access a directory. By default, a directory object is constructed to represent the current directory. With one argument, the object is constructed from the directory name. Once the object is constructed, it is possible to retrieve its content.

Predicate

    directory-p

Inheritance

    Object

Constructors

Directory (none)

The Directory constructor creates a directory object those location is the current directory. If the directory cannot be opened, an exception is raised.

Directory (String)

The Directory constructor create a directory object by name. If the directory cannot be opened, an exception is raised. The first argument is the directory name to open.

Methods

mkdir (→ Directory) (String)

The mkdir method creates a new directory in the current one. The full path is constructed by taking the directory name and adding the argument. Once the directory is created, the method returns a directory object of the newly constructed directory. An exception is thrown if the directory cannot be created.

rmdir (→ none) (String)

The rmdir method removes an empty directory. The full path is constructed by taking the directory name and adding the argument. An exception is thrown if the directory cannot be removed.

rmfile (→ none) (String)

The rmfile method removes a file in the current directory. The full path is constructed by taking the directory name and adding the argument. An exception is thrown if the file cannot be removed.

get-name (→ String) (none)

The get-name method returns the directory name. If the default directory was created, the method returns the full directory path.

get-list (→ List) (none)

The get-list method returns the directory contents. The method returns a list of strings. The list contains all valid names at the time of the call, including the current directory and the parent directory.

get-files (→ List) (none)

The get-files method returns the directory contents. The method returns a list of strings of files. The list contains all valid names at the time of the call.

get-subdirs (→ List) (none)

The get-subdirs method returns the sub directories. The method returns a list of strings of subdirectories. The list contains all valid names at the time of the call, including the current directory and the parent directory.

next-name (→ String) (none)

The next-name method returns the next available name from the directory stream. This method is useful when operating with a large number of elements.

next-path (→ String) (none)

The next-path method returns the next available path name from the directory stream. This method is useful when operating with a large number of elements.

next-file-name (→ String) (none)

The next-file-name method returns the next available file name from the directory stream. This method is useful when operating with a large number of elements.

next-file-path (→ String) (none)

The next-file-path method returns the next available file path name from the directory stream. This method is useful when operating with a large number of elements.

next-dir-name (→ String) (none)

The next-dir-name method returns the next available directory name from the directory stream. This method is useful when operating with a large number of elements.

next-dir-path (→ String) (none)

The next-dir-path method returns the next available directory path name from the directory stream. This method is useful when operating with a large number of elements.

Logtee

The `Logtee` class is a message logger facility associated with an output stream. When a message is added to the logger object, the message is also sent to the output stream, depending on the controlling flags. The name "logtee" comes from the contraction of "logger" and "tee". One particularity of the class is that without a stream, the class behaves like a regular logger.

Predicate

    logtee-p

Inheritance

    Logger

Constructors

Logtee (none)

The Logtee constructor creates a default logger without an output stream

Logtee (Integer)

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

Logtee (Output)

The Logtee constructor creates a logger object with an output stream.

Logtee (Integer Output)

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

Logtee (Integer String Output)

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

Methods

set-output-stream (→ none) (Output)

The set-output-stream method attaches the output stream to the logtee object.

get-output-stream (→ Output) (none)

The get-output-stream method returns the logtee output stream.

set-tee (→ none) (Boolean)

The set-tee method sets the logtee control flag. The control flag controls the message display to the output stream.

get-tee (→ Boolean) (none)

The get-tee method returns the logtee output stream.

NamedFifo

The `NameFifo` class is a string vector designed to operate as a stream fifo object. The class provides the facility to read or write the fifo content from a stream. The stream can be created by name for writing, in which case the named fifo operates as a backup object.

Predicate

    named-fifo-p

Inheritance

    Strvec
    Nameable

Constructors

NamedFifo (none)

The NamedFifo constructor creates a default named fifo without a backing name. In this case the fifo cannot be read or written by stream.

NamedFifo (String)

The NamedFifo constructor creates a named fifo by name. The name is used as a file name for reading or writing the fifo.

NamedFifo (String Boolean)

The NamedFifo constructor creates a named fifo by name. The name is used as a file name for reading or writing the fifo.If the boolean argument is true, the fifo is read.

Methods

read (→ none) (none)

The read method reads the fifo file name and fill the fifo.

write (→ none) (none)

The write method writes the fifo contents to the fifo file name.

set-name (→ none) (String)

The set-name method sets the fifo file name.

FileInfo

The `FileInfo` is a file information class that holds the primary information related to a file, such like its size or its modification time. The file information is set at construction but can be updated with the help of the `update` method.

Predicate

    file-info-p

Inheritance

    Nameable

Constructors

(String)

The FileInfo constructor creates a file information by name. The string argument is the file name to query.

Methods

length (→ Integer) (none)

The length method returns the file size information.

get-modification-time (→ Integer) (none)

The get-modification-time method returns the file modification time. The time is expressed in the ATC system and can be used as an argument to the Time or Date object.

update (→ none) (none)

The update method the file information data.