Provided by: afnix_2.8.1-1_amd64 
NAME
sio - standard input/output module
STANDARD INPUT/OUTPUT MODULE
The Standard Input/Outputmodule is an orginal implementation that provides objects for i/o
operations. Although input and output files are the standard objects that one might
expect, the module facilities for directory access, path manipulation and i/o event
management. At the heart of this module is the concept of stream associated with the
transcoding object which enable the passage between one coding system to another. It is
also this module which provides the stream selector object.
Input and output streams
The afnix-siomodule is based on facilities provided by two base classes, namely, the
InputStreamstream and the OutputStreamstream. Both classes have associated predicates with
the name input-stream-pand output-stream-p. The base class associated is the Streamclass
those sole purpose is to define the stream coding mode.
Stream base class
The Streamclass is the base class for the InputStreamand OutputStreamclasses. The
Streamclass 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 readand getuare 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-8codeset, the Terminalstream coding mode is automatically adjusted to reflect this
situation. Since the US-ASCIIcodeset 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 Streamclass provides the support for the transcoding of different codesets. All
ISO-8859codesets 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.
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-modecan be used to set the stream encoding codeset. The method operates
either by enumeration or string. The get-encoding-modereturns 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-modemethod. For simplicity, the string
version of the set-encoding-modetakes care of setting both the stream mode and the
transcoding mode. It is also worth to note that internally, the Streamclass is derived
from the Transcoderclass.
Input stream
The InputStreambase 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 readmethod without argument returns the next available byte or
the end-of-streameos. With an integer argument, the readmethod returns a Bufferwith at
most the number of requested bytes. The readlnmethod returns the next available line. When
it is necessary to read characters instead of bytes, the getuis more appropriate since it
returns an Unicode character.
Output stream
The OutputStreambase class provides the base methods to write to an output stream. The
writemethod takes literal objects which are automatically converted to string
representation and then written to the output stream. Note that for the case of a
Bufferobject, 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-ppredicate that returns trueif 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-ppredicate 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-
ppredicate 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-ppredicate 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
trueif and only if a byte cannot be read. If a byte has been pushed-back and the end-of-
streammarker is reached, the method will return false. For an input terminal, the method
returns true if the user and entered the end-of-streambyte. 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 truewhen all datagram bytes have be
read.
The read method
The readmethod 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-streammarker has been reached. The method returns the ctrl-dbyte. Since a binary
file might contains valid byte like ctrl-dit is necessary to use the valid-por eos-
ppredicate 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-streamcondition and therefore care should be taken
to properly assert the stream content. This last remark is especially true for the
readlnmethod. The method will return when the end-of-streammarker is reached, even if a
newline byte has not been read. With an udp socket, such behavior will not happen.
Buffer read mode
The readmethod 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 Bufferobject which can later be used to read, or
transform bytes. Multi-byte conversion to number should use such approach. The readmethod
does not necessarily returns the number of requested bytes. Once the buffer is returned,
the lengthmethod can be used to check the buffer size. Note also the existence of the to-
stringmethod 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-siomodule provides two classes for file access. The InputFileclass open a file
for input. The OutputFileclass opens a file for output. The InputFileclass is derived from
the InputStreambase class. The OutputFileclass is derived from the OutputStreamclass. 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 InputFileand OutputFilesupports the get-namemethod which returns the file name.
println (if:get-name)
println (of:get-name)
Predicates are also available for these classes. The input-file-preturns true for an input
file object.The output-file-preturns 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 readmethod reads a byte on an input stream. The writemethod writes one or more literal
arguments on the output stream. The writelnmethod writes one or more literal arguments
followed by a newline byte on the output stream. The newlinemethod write a newline byte on
the output stream. The eos-ppredicate returns true for an input stream, if the stream is
at the end. The valid-ppredicate 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 readlnmethod 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-ppredicate, except that it works with several stream objects.
Selector object
I/O multiplexing is accomplished with the Selectorclass. The constructor takes 0 or
several stream arguments. The class manages automatically to differentiate between
InputStreamstream and OutputStreamstreams. 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 isand osare 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 addmethod adds a new stream to the selector. The stream must be either an
InputStreamand OutputStreamstream 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-addor the output-addmethods might be preferable.
The input-lengthmethod returns the number of input streams in this selector. The output-
lengthmethod returns the number of output streams in this selector. The input-getmethod
returns the selector input stream by index. The output-getmethod returns the selector
output stream by index.
Waiting for i/o event
The waitand wait-allmethods 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 waitmethod returns the first stream which is ready either for reading or
writing depending whether it is an input or output stream. The wait-allmethod returns a
vector with all streams that have changed their status. The waitmethod returns nilif the
no stream have changed. Similarly, the wait-allmethod 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 waitmethod 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 markmethod is designed to mark the selector while the marked-
ppredicate 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, OutputTermand ErrorTermclasses 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 Terminalclass. 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 Terminalclass 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-
linemethod. The standard methods like reador readlndo 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-promptor set-secondary-prompt. A secondary prompt is displayed when the read-
linemethod 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 ErrorTermclass is the most frequently used class for printing data on the standard
error stream. The reserved keywords erroror errorlnare available to write on the
interpreter error stream. If the interpreter error stream has been changed, the use of the
ErrorTermwill provide the facility required to print directly on the terminal. The
catprogram 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
}
Directory
The Directoryclass 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 Directoryobject 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-namemethod.
# print the current directory
const pwd (afnix:sio:Directory)
println (pwd:get-name)
Once the directory object is opened, it is possible to list its contents. The get-
listmethod returns the full contents of the directory object. The get-filesmethod returns
a list of files in this directory. The get-subdirsmethod returns a list of sub directories
in this directory.
# print a list of files
const pwd (afnix:sio:Directory)
const lsf (d:get-files)
for (name) (lsf) (println name)
Creating and removing directories
The mkdirand rmdirmethods 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 mkdirmethods succeeds. The rmdirmethod requires the directory to be empty.
const tmp (afnix:sio:Directory (
afnix:sio:absolute-path "tmp"))
const exp (tmp:mkdir "examples")
const lsf (exp:get-files)
println (lsf:length)
tmp:rmdir "examples"
The function absolute-pathconstructs an absolute path name from the argument list. If
relative path needs to be constructed, the function relative-pathmight be used instead.
Logtee
The Logteeclass 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 Logteedefault 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.
# create a logger with the interpreter stream
const log (Logtee (interp:get-output-stream))
assert true (logger-p log)
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.
log:add 2 "a level 2 message"
The set-teemethod sets the control flag. The set-report-levelmethod sets the report level.
Note that the set-report-leveland its associated get-report-levelmethod is part of the
base Loggerclass.
Path name
The Pathnameclass 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.
# create a new path name
const path (afnix:sio:Pathname "axi")
Adding a directory path
The best way to add a directory path is to use the absolute-pathor the relative-
pathfunctions.
# adding a directory path
const name (afnix:sio:absolute-path "usr" "bin")
path:set-directory-name name
Getting the path information
The path information can be obtained individually or globally. The get-file-nameand get-
directory-namemethods return respectively the file and directory name. The get-rootmethod
returns the root component of the directory name. The get-fullmethod returns the full path
name.
STANDARD INPUT/OUTPUT REFERENCE
Transcoder
The Transcoderclass 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 DEFAULTconstant is used by the set-transcoding-modemethod to specify the class
transcoding mode. In default mode, each character is not transcoded. This mode is
the identity mode.
I8859-01
The I8859-01constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-6 codeset.
I8859-02
The I8859-02constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-2 codeset.
I8859-03
The I8859-03constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-3 codeset.
I8859-04
The I8859-04constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-4 codeset.
I8859-05
The I8859-05constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-5 codeset.
I8859-06
The I8859-06constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-6 codeset.
I8859-07
The I8859-07constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-7 codeset.
I8859-08
The I8859-08constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-8 codeset.
I8859-09
The I8859-09constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-9 codeset.
I8859-10
The I8859-10constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-10 codeset.
I8859-11
The I8859-11constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-11 codeset.
I8859-13
The I8859-13constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-13 codeset.
I8859-14
The I8859-14constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-14 codeset.
I8859-15
The I8859-15constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-15 codeset.
I8859-16
The I8859-16constant is used by the set-transcoding-modemethod to specify the class
transcoding mode that corresponds to the ISO-8859-16 codeset.
Constructors
Transcoder (none)
The Transcoderconstructor creates a default transcoder that operates in default
mode by using the identity function.
Transcoder (constant)
The Transcoderconstructor creates a transcoder with the argument mode.
Methods
set-transcoding-mode -> none (constant)
The set-transcoding-modemethod sets the class transcoding mode.
get-transcoding-mode -> constant (none)
The get-transcoding-modemethod returns the class transcoding mode.
valid-p -> Byte|Character (Boolean)
The valid-ppredicate 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 encodemethod encodes a byte into a character. If the character cannot be
encoded, an exception is raised.
decode -> Character (Byte)
The decodemethod decodes a character into a byte. If the character cannot be
decoded, an exception is raised.
Stream
The Streamclass 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.
Predicate
stream-p
Inheritance
Transcoder
Constants
BYTE
The BYTEconstant is used by the set-coding-modemethod to specify the stream coding
mode. In byte mode, each character is assumed to be coded with one byte. This value
affects the getuand writemethods
UTF-8
The UTF-8constant is used by the set-coding-modemethod 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 getuand writemethods
Methods
set-encoding-mode -> none (constant|String)
The set-encoding-modemethod 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-modemethod returns the stream coding mode which affects how
characters are read or written.
InputStream
The InputStreamclass 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. 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 flushmethod 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-timeoutmethod returns the input stream timeout. A negative value is a
blocking timeout.
set-timeout -> none (Integer)
The set-timeoutmethod sets the input stream timeout. A negative value is a blocking
timeout. Changing the stream timeout does not cancel any pending read operation.
read -> Byte (none)
The readmethod returns the next byte available from the input stream. If the stream
has been closed or consumed, the end-of-streambyte is returned.
read -> Buffer (Integer)
The readmethod returns a buffer object with at most the number of bytes specified
as an argument. The buffer lengthmethod should be used to check how many bytes have
been placed in the buffer.
readln -> String (none)
The readlnmethod returns the next line available from the input stream. If the
stream has been closed or consumed, the end-of-streamcharacter is returned.
getu -> Character (none)
The getumethod returns the next available Unicode character from the input stream.
If the stream has been closed or consumed, the end-of-streamcharacter is returned.
During the read process, if the character decoding operation fails, an exception is
raised.
valid-p -> Boolean (none|Integer)
The valid-pmethod 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-ppredicate returns true if the input stream has been closed or all bytes
consumed.
pushback -> Integer (Byte|Character|String)
The pushbackmethod 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.
consume -> Integer (none)
The consumemethod consumes an input stream and places the read characters into the
stream buffer. The method returns the number of consumed characters. This method is
generally used in conjonction with the to-stringmethod.
get-buffer-length -> Integer (none)
The get-buffer-lengthmethod returns the length of the push-back buffer.
to-string -> String (none)
The to-stringmethod returns a string representation of the input stream buffer.
InputFile
The InputFileclass 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 InputFileclass is derived from the InputStreamclass.
Predicate
input-file-p
Inheritance
InputStreamNameable
Constructors
InputFile (String)
The InputFileconstructor 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 InputFileconstructor 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 closemethod close the input file and returns true on success, false otherwise.
In case of success, multiple calls return true.
lseek -> none (Integer)
The lseekset the input file position to the integer argument. Note that the push-
back buffer is reset after this call.
length -> Integer (none)
The lengthmethod returns the length of the input file. The length is expressed in
bytes.
get-modification-time -> Integer (none)
The get-modification-timemethod returns the modification time of the file. The
returned argument is suitable for the Timeand Datesystem classes.
InputMapped
The InputMappedclass is an input stream class that provides the facility for reading a
mapped input stream. The input stream is mapped at construction given a file name, a size
and a file offset. An anonymous mapped input stream can also be designed with a buffer
object. Finally, without any information an always valid null input stream is constructed.
Predicate
input-mapped-p
Inheritance
InputStream
Constructors
InputMapped (none)
The InputMappedconstructor create a null input stream. This stream acts as a null
character generator.
InputMapped (String|Buffer)
The InputMappedconstructor create a mapped input stream by name or buffer. In the
first form, a string is used as file name to be mapped an input stream. In the
second form, a buffer is mapped as an input stream.
InputMapped (String Integer Integer)
The InputMappedconstructor create a mapped input stream by name, size and offset.
The string argument is the file name to map. The second argument is the desired
mapped size. The third argument is the offset inside the file before mapping it.
Methods
lseek -> none (Integer)
The lseekset the input mapped file position to the integer argument. Note that the
push-back buffer is reset after this call.
length -> Integer (none)
The lengthmethod returns the length of the input mapped file. The length is
expressed in bytes.
InputString
The InputStringclass 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 InputStringconstructor creates an empty input string.
InputString (String)
The InputStringconstructor creates an input string by value.
Methods
get -> Byte (none)
The getmethod returns the next available byte from the input stream but do not
remove it.
set -> none (String)
The setmethod sets the input string by first resetting the push-back buffer and
then initializing the input string with the argument value.
InputTerm
The InputTermclass 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 Terminalclass should be used instead.
Predicate
input-term-p
Inheritance
InputStreamOutputStream
Constructors
InputTerm (none)
The InputTermconstructor creates a default input terminal.
Methods
set-ignore-eos -> none (Boolean)
The set-ignore-eosmethod set the input terminal end-of-streamignore flag. When the
flag is on, any character that match a ctrl-dis 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-dbyte is generated.
set-mapped-eos -> none (Byte)
The set-mapped-eosmethod set the input terminal end-of-streammapped character. By
default the character is set to end-of-line. This method should be used in
conjunction with the set-ignore-eosmethod.
OutputStream
The OutputStreamclass 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.
Predicate
output-stream-p
Inheritance
Stream
Methods
write -> Integer (Literal+)
The writemethod write one or more literal arguments on the output stream. This
method returns the number of characters written.
writeln -> none (Literal+)
The writelnmethod write one or more literal argument to the output stream and
finish with a newline. This method return nil.
errorln -> none (Literal+)
The errorlnmethod 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 newlinemethod writes a new line byte to the output stream. The method returns
nil.
write-soh -> none (none)
The write-sohmethod writes a start-of-headingcharacter to the output stream.
write-stx -> none (none)
The write-stxmethod writes a start-of-transmissioncharacter to the output stream.
write-etx -> none (none)
The write-etxmethod writes an end-of-transmissioncharacter to the output stream.
write-eos -> none (none)
The write-eosmethod writes an end-of-streamcharacter to the output stream.
OutputFile
The OutputFileclass 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 OutputStreamclass. 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-flagis the
truncate flag. The a-flagis the append flag.
Predicate
output-file-p
Inheritance
OutputStreamNameable
Constructors
OutputFile (String)
The OutputFileconstructor 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 OutputFileconstructor 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 OutputFileconstructor 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 closemethod closes the output file and returns true on success, false
otherwise. In case of success, multiple calls returns true.
OutputString
The OutputStringclass 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-
stringmethod can be used to retrieve the buffer content.
Predicate
output-string-p
Inheritance
OutputStream
Constructors
OutputString (none)
The OutputStringconstructor creates a default output string.
OutputString (String)
The OutputStringconstructor creates an output string by value. The output string
stream is initialized with the string value.
Methods
flush -> none (none)
The flushmethod flushes the output stream by resetting the stream buffer.
length -> Integer (none)
The lengthmethod returns the length of the output string buffer.
to-string -> String (none)
The to-stringmethod returns a string representation of the output string buffer.
OutputBuffer
The OutputBufferclass provide the facility for an output byte stream. The class is
initially empty and acts as a buffer which accumulate the write method bytes. The to-
stringmethod can be used to retrieve the buffer content as a string. The formatmethod can
be used to retrieve the buffer content as an octet string. content.
Predicate
output-buffer-p
Inheritance
OutputStream
Constructors
OutputBuffer (none)
The OutputBufferconstructor creates a default output buffer.
OutputBuffer (String)
The OutputBufferconstructor creates an output buffer by value. The output buffer
stream is initialized with the string value.
Methods
flush -> none (none)
The flushmethod flushes the output stream by resetting the stream buffer.
length -> Integer (none)
The lengthmethod returns the length of the output buffer.
to-string -> String (none)
The to-stringmethod returns a string representation of the output buffer.
format -> String (none)
The formatmethod returns an octet string representation of the output buffer.
OutputTerm
The OutputTermclass 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
ErrorTermclass is more appropriate.
Predicate
output-term-p
Inheritance
OutputStream
Constructors
OutputTerm (none)
The OutputTermconstructor creates a default output terminal
ErrorTerm (none)
The ErrorTermconstructor creates a default error terminal
Terminal
The Terminalclass provides the facility for an i/o terminal with line editing capability.
The class combines the InputTermand OutputTermmethods.
Predicate
terminal-p
Inheritance
InputTermOutputTerm
Constructors
Terminal (none)
The Terminalconstructor creates a default terminal which combines an input and
output terminal with line editing capabilities.
Methods
set-primary-prompt -> none (String)
The set-primary-promptmethod sets the terminal primary prompt which is used when
the read-linemethod is called.
set-secondary-prompt -> none (String)
The set-secondary-promptmethod sets the terminal secondary prompt which is used
when the read-linemethod is called.
get-primary-prompt -> String (none)
The get-primary-promptmethod returns the terminal primary prompt.
get-secondary -> String (none)
The get-secondary-promptmethod returns the terminal secondary prompt.
Intercom
The Intercomclass is the interpreter communication class. The class operates with two
streams. One output stream is used to send serialized data while the input stream is used
to deserialize data. The sendmethod can be used to send the data, while the recvcan be
used to receive them.
Predicate
intercom-p
Inheritance
Object
Constructors
Intercom (none)
The Intercomconstructor creates a default interpreter communication object. There
is no stream attached to it.
Intercom (InputStream|OutputStream)
The Intercomconstructor creates an interpreter communication object with an input
or an output stream. In the first form, the input stream object is used by the
recvmethod to read data object. In the second form, the output stream object is
used by the sendmethod to send data object.
Intercom (InputStream OutputStream)
The Intercomconstructor creates an interpreter communication object with an input
and an output stream.
Methods
send -> none (Object)
The sendmethod serialize the object argument with the help of the output stream
bound to the interpreter communication object. If there is no output stream,
nothing is sent.
recv -> Object (none)
The recvmethod deserialize an object with the help of the input stream bound to the
interpreter communication object. If there is no output stream, nilis returned.
request -> Object (Object)
The requestmethod perform an atomic send receive operation.
set-input-stream -> none (InputStream)
The set-input-streammethod binds an input stream to the interpreter communication
object.
get-input-stream -> InputStream (none)
The get-input-streammethod returns the input stream bound to the interpreter
communication object.
set-output-stream -> none (OutputStream)
The set-output-streammethod binds an output stream to the interpreter communication
object.
get-output-stream -> OutputStream (none)
The get-output-streammethod returns the output stream bound to the interpreter
communication object.
InputOutput
The InputOutputclass 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 eos-ppredicate returns true,
the valid-ppredicate false and the readmethod will return the eoscharacter. The
InputOutput buffer can also be initialized with a buffer. This provides a nice mechanism
to use a buffer like an input stream. The i/o operations implemented by this class are
non-blocking. As a consequence, it is not possible to suspend a thread with this class and
have it awaken when some characters are available in the input stream.
Predicate
input-output-p
Inheritance
InputStreamOutputStream
Constructors
InputOutput (none)
The InputOutputconstructor creates a default input/output stream.
InputOutput (String)
The InputOutputconstructor 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 getmethod returns the next available byte from the input stream but do not
remove it.
set -> none (String)
The setmethod sets the input string by first resetting the push-back buffer and
then initializing the input string with the argument value.
Selector
The Selectorclass provides some facilities to perform i/o multiplexing. The constructor
takes 0 or several stream arguments.The class manages automatically the differentiation
between the InputStreamand the OutputStreamobjects. 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 addmethod. When a call to the
waitmethod succeeds, the method returns the first available stream. If the waitallmethod
is called, the method returns a vector with all ready steams. 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 markmethod is designed to mark the selector while the
marked-ppredicate returns true if the stream has been marked.
Predicate
selector
Inheritance
Object
Constructors
Selector (none)
The Selectorconstructor creates a default stream selector.
Selector ([Boolean] [InputStream|OutputStream]*)
The Selectorconstructor creates a stream selector with 0 or more stream arguments.
If the first argument is a boolean, the selector is constructed marked mode.
Methods
add -> none (InputStream|OutputStream)
The addmethod adds an input or output stream to the selector. 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-addor the output-addmethods might be
preferable.
input-add -> none (InputStream)
The input-addmethod adds an input stream to the selector.
output-add -> none (OutputStream)
The output-addmethod adds an output stream to the selector.
wait -> Stream (none|Integer)
The waitmethod 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 waitmethod 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-getmethod 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-getmethod 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-lengthmethod returns the number of input streams in the selector.
output-length -> Integer (none)
The output-lengthmethod returns the number of output streams in the selector.
mark -> none (none)
The markmethod marks a selector object.
marked-p -> Boolean (none)
The marked-ppredicate returns true if the selector has been marked.
Logtee
The Logteeclass 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-
teemethod.
Predicate
logtee-p
Inheritance
Logger
Constructors
Logtee (none)
The Logteeconstructor creates a default logger without an output stream.
Logtee (Integer)
The Logteeconstructor creates a logger with a specific size without an output
stream. terminal
Logtee (OutputStream)
The Logteeconstructor creates a logger with an output stream. The object is
initialized to operate in write mode.
Logtee (Integer OutputStream)
The Logteeconstructor 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 Logteeconstructor 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-streammethod sets the tee output stream. This stream is different from
the logger output stream
get-tee-stream -> OutputStream (none)
The get-tee-streammethod returns the object output stream.
set-tee -> none (Boolean)
The set-teemethod 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-teemethod returns the object tee flag. When the flag is true, the logger
writes the added message on the output stream.
Pathname
The Pathnameclass 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 component has a special treatment to process the root directory name.
Predicate
pathname-p
Inheritance
Object
Constructors
Pathname (none)
The Pathnameconstructor creates a default path name without file and directory
names.
Pathname (String)
The Pathnameconstructor creates a path name with a file name. The first string
argument is the file name.
Pathname (String String)
The Pathnameconstructor 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 resetmethod reset the path name by removing all path and file information.
dir-p -> Boolean (none)
The dir-ppredicate returns true if the path is a directory.
file-p -> Boolean (none)
The file-ppredicate returns true if the path is a file.
set-file-name -> none (String)
The set-file-namemethod set the path name file name. The string argument is the
file name.
get-file-name -> String (none)
The get-file-namemethod returns the path name file name.
add-directory-name -> none (String)
The add-directory-namemethod add the directory name to the directory path
component. The string argument is the directory name.
set-directory-name -> none (String)
The set-directory-namemethod set the directory name file name. The string argument
is the directory name.
get-directory-name -> String (none)
The get-directory-namemethod returns the path name directory name.
length -> Integer (none)
The lengthmethod returns the number of directory path elements.
get-path -> String (Integer)
The get-pathmethod returns a directory path element by index.
get-root -> String (none)
The get-rootmethod returns the root component of a directory name.
get-full -> String (none)
The get-fullmethod returns the full path name by combining the directory name with
the file name.
add-path -> none (String)
The add-pathmethod 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 normalizemethod 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 Pathlistclass 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 Pathlistconstructor creates a default path list.
Pathlist (Boolean|String)
The Pathlistconstructor 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 resetmethod resets the path list by clearing the local search flag and removing
all path components.
local-p -> Boolean (none)
The local-ppredicate returns true if the local search flag is set.
set-local-search -> none (Boolean)
The set-local-searchmethod sets the local search flag.
length -> Integer (none)
The lengthmethod returns the number of directory path elements.
get-path -> String (Integer)
The get-pathmethod returns a directory path element by index.
add-path -> none (String)
The add-pathmethod add a new path component by name. The string argument is the
name to add.
file-p -> Boolean (String)
The file-ppredicate 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 resolvemethod returns a string representation of the resolved file path. If the
local search flag is set and the file name is found locally, the initial name
argument is returned.
Functions
dir-p -> Boolean (String)
The dir-pfunction returns true if the argument name is a directory name, false
otherwise.
file-p -> Boolean (String)
The file-pfunction returns true if the argument name is a regular file name, false
otherwise.
tmp-name -> String (String?)
The tmp-namefunction 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-pathfunction 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-pathfunction 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-pathfunction 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 rmfilefunction removes one or several files specified as the arguments. If one
file fails to be removed, an exception is raised.
mkdir -> none (String+)
The mkdirfunction creates one or several directories specified as the arguments. If
one directory fails to be created, an exception is raised.
mhdir -> none (String+)
The mhdirfunction creates hierarchically one or several directories specified as
the arguments. If one directory fails to be created, an exception is raised.
rmdir -> none (String+)
The rmdirfunction 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-namefunction 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-pathfunction 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-extensionfunction returns the extension from a path.
remove-extension -> String (String)
The remove-extensionfunction returns the extension from a path. In order to get a
base file name from a path, the get-base-namefunction must be called first.
Directory
The Directoryclass 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 Directoryconstructor creates a directory object those location is the current
directory. If the directory cannot be opened, an exception is raised.
Directory (String)
The Directoryconstructor 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 mkdirmethod 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 rmdirmethod 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 rmfilemethod 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-namemethod returns the directory name. If the default directory was
created, the method returns the full directory path.
get-list -> List (none)
The get-listmethod 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-filesmethod 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-subdirsmethod returns the sub directories. The method returns a list of
strings of sub-directories. 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-namemethod 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-pathmethod 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-namemethod 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-pathmethod 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-namemethod 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-pathmethod 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 Logteeclass 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 Logteeconstructor creates a default logger without an output stream
Logtee (Integer)
The Logteeconstructor creates a logger object with a specific size without an
output stream.
Logtee (Output)
The Logteeconstructor creates a logger object with an output stream.
Logtee (Integer Output)
The Logteeconstructor 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 Logteeconstructor 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-streammethod attaches the output stream to the logtee object.
get-output-stream -> Output (none)
The get-output-streammethod returns the logtee output stream.
set-tee -> none (Boolean)
The set-teemethod sets the logtee control flag. The control flag controls the
message display to the output stream.
get-tee -> Boolean (none)
The get-teemethod returns the logtee output stream.
NamedFifo
The NameFifoclass 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
StrvecNameable
Constructors
NamedFifo (none)
The NamedFifoconstructor creates a default named fifo without a backing name. In
this case the fifo cannot be read or written by stream.
NamedFifo (String)
The NamedFifoconstructor creates a named fifo by name. The name is used as a file
name for reading or writing the fifo.
NamedFifo (String Boolean)
The NamedFifoconstructor 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 readmethod reads the fifo file name and fill the fifo.
write -> none (none)
The writemethod writes the fifo contents to the fifo file name.
set-name -> none (String)
The set-namemethod sets the fifo file name.
FileInfo
The FileInfois 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 updatemethod.
Predicate
file-info-p
Inheritance
Nameable
Constructors
(String)
The FileInfoconstructor creates a file information by name. The string argument is
the file name to query.
Methods
length -> Integer (none)
The lengthmethod returns the file size information.
get-modification-time -> Integer (none)
The get-modification-timemethod returns the file modification time. The time can be
used as an argument to the Timeor Dateobject.
update -> none (none)
The updatemethod the file information data.