sio(3)

hey bestie 💖 welcome to the sio(3) page, straight out of the Library Functions Manual. it's giving standard input/output module, and we're gonna read it together, no cap. ✨

---

🎀 NAME 🎀

sio — standard input/output module. periodt. 💅

🌈 STANDARD INPUT/OUTPUT MODULE 🌈

okay so the Standard Input/Output module is an orginal implementation that provides objects for i/o operations. like, input and output files are the standard objects you'd expect, but the module also has facilities for directory access, path manipulation, and i/o event management. at the heart of this module is the concept of a stream associated with the transcoding object, which enables passage between one coding system and another. it's also this module that provides the stream selector object. 🦋

💧 Input and output streams 💧

The afnix-sio module is based on facilities provided by two base classes: InputStream stream and OutputStream stream. Both classes have associated predicates named input-stream-p and output-stream-p. The base class associated is the Stream class, whose 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 streams, like terminal, this behavior is changed depending on the current localization settings. For instance, if the current locale is operating with an UTF-8 codeset, the Terminal stream coding mode is automatically adjusted to reflect this situation. Since the US-ASCII codeset is predominant and the default steam coding mode is the byte mode, there should be no conflict during the read and write operations. 💅

🦋 Stream transcoding 🦋

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

Codeset crew, line by line, no skips:

• 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-streameos. With an integer argument, the read method returns a Buffer with at most the number of requested bytes. The readln method returns the next available line. When it is necessary to read characters instead of bytes, the getu is more appropriate since it returns an Unicode character. 😭

✍️ Output stream ✍️

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

✅ The valid-p predicate ✅

The input stream provides a general mechanism to test and read for bytes. The base method is the valid-p predicate that returns true if a byte can be read from the stream. It is important to understand its behavior which depends on the stream type. Without argument, the valid-p predicate checks for an available byte from the input stream. This predicate will block if no byte is available. On the other end, for a bounded stream like an input file, the method will not block at the end of file. With one integer argument, the valid-p predicate will timeout after the specified time specified in milliseconds. This second behavior is particularly useful with unbound stream like socket stream. 🔥

🛑 The eos-p predicate 🛑

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

📥 The read method 📥

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

🧺 Buffer read mode 🧺

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

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

📁 File stream 📁

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

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

🏷️ Stream information 🏷️

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

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

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

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

🔁 Reading and writing 🔁

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

# load the module and open the files
interp:library "afnix-sio"
const if (afnix:sio:InputFile "orig.txt")
const of (afnix:sio:OutputFile "copy.txt")
# loop in the input file and write
while (if:valid-p) (of:write (if:read))

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

# cat a file on the output terminal
# usage: axi 0601.als file
# get the io module
interp:library "afnix-sio"
# cat a file
const cat (name) {
  const f (afnix:sio:InputFile name)
  while (f:valid-p) (println (f:readln))
  f:close
}
# get the file
if (== 0 (interp:argv:length)) {
  errorln "usage: axi 0601.als file"
} {
  cat (interp:argv:get 0)
}

Multiplexing 💫

okay bestie, I/O multiplexing is literally the ability to manipulate several streams at the same time and process one at a time. no cap. Even though the use of threads reduces the needs for i/o multiplexing, there are 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. periodt. 💅

Selector object 🎛️

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

# create a selector
const slt (afnix:sio:Selector is)
# at this stage the selector has one stream
# the add method can add more streams
slt:add os

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

Waiting for i/o event ⏳

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

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

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

Marking mode 🏷️

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

Terminal streams 🖥️

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

Terminal class 🖊️

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

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

Using the error terminal 🚨

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

# cat a file on the error terminal
# get the io module
interp:library "afnix-sio"
# cat a file
const cat (name es) {
  const f (afnix:sio:InputFile name)
  while (f:valid-p) (es:writeln (f:readln))
  f:close
}

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.

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

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

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

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

# 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-path or the relative-path functions.

# 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-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 INPUT/OUTPUT REFERENCE 💖

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 constant you hand to the set-transcoding-mode method when you want the class transcoding mode that lines up with the ISO-8859-4 codeset. 🦋
• I8859-05 — same deal, but for the ISO-8859-5 codeset. Hand it to set-transcoding-mode to set that class transcoding mode.
• I8859-06 — the one you pass to set-transcoding-mode for the class transcoding mode matching the ISO-8859-6 codeset.
• I8859-07 — yep, set-transcoding-mode takes this one to set the class transcoding mode for the ISO-8859-7 codeset.
• I8859-08 — set-transcoding-mode + this constant = class transcoding mode for the ISO-8859-8 codeset. 🫶
• I8859-09 — for the ISO-8859-9 codeset, this is the constant that set-transcoding-mode wants.
• I8859-10 — you already know the drill: set-transcoding-mode, this constant, class transcoding mode, ISO-8859-10 codeset. ✨
• I8859-11 — same energy for ISO-8859-11. It's the constant set-transcoding-mode uses to specify the class transcoding mode.
• I8859-13 — yes bestie, there's no I8859-12 in this list, that's just how it is 😭 — this one is the set-transcoding-mode constant for the ISO-8859-13 codeset.
• I8859-14 — the class transcoding mode constant for ISO-8859-14, used by set-transcoding-mode.
• I8859-15 — the constant set-transcoding-mode uses to specify the class transcoding mode that corresponds to the ISO-8859-15 codeset.
• I8859-16 — and closing out the ISO parade, the set-transcoding-mode constant for the ISO-8859-16 codeset. 💜

---

🛠️ Constructors

• Transcoder (none) — makes you a default transcoder. It operates in default mode and it does that by using the identity function. Lowkey the chillest constructor alive.
• Transcoder (constant) — makes you a transcoder, and the argument is the mode it rolls with.

🎀 Methods

• set-transcoding-mode -> none (constant) — sets the class transcoding mode. That's the whole job, no notes. 💅
• get-transcoding-mode -> constant (none) — reads back the class transcoding mode for you.
• valid-p -> Byte|Character (Boolean) — the vibe-check predicate. It returns true if the character can be transcoded. Pass in a byte and it returns true if that byte can be transcoded to a character. Pass in a character and it returns true if that character can be transcoded to a byte.
• encode -> Byte (Character) — encodes a byte into a character. And if the character cannot be encoded? An exception is raised. No silent nonsense here. 🙈
• decode -> Character (Byte) — decodes a character into a byte. If the character cannot be decoded, an exception is raised. Same energy, opposite direction.

---

🌊 Stream

The Stream class is the base class for the standard streams. It gets constructed automatically by a derived class, and it hands out the common methods that all streams share. Main character of the class hierarchy, fr fr. 👑

Predicate

• stream-p

Inheritance

• Transcoder

Constants

• BYTE — the constant the set-coding-mode method uses 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 constant the set-coding-mode method uses 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) — sets the stream coding mode, which is the thing that affects how characters are read or written. In the enumeration form, the method only sets the stream coding mode, and that mode is either byte or UTF-8 mode. In the string mode, it 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 standard i/o module. It's automatically constructed by a derived class, and it provides the common methods for every input stream. Every input stream is associated with a timeout value, and that timeout is used for read operations. By default, the timeout is infinite, which means any read without data is going to be a blocking one. So if your program is just... sitting there... that's why. 😭

Predicate

• input-stream-p

Inheritance

• Stream

Methods

• flush -> none|Character (none) — flushes the input stream buffer. In the first form, with no 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) — returns the input stream timeout. Heads up: a negative value is a blocking timeout.
• set-timeout -> none (Integer) — sets the input stream timeout. A negative value is a blocking timeout. And important: changing the stream timeout does not cancel any pending read operation. It's not gonna rescue you from a read that's already happening, bestie.
• read -> Byte (none) — 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) — returns a buffer object with at most the number of bytes you passed as an argument. Use the buffer length method to check how many bytes actually got placed in the buffer. 👑
• readln -> String (none) — 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) — 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. And during the read process, if the character decoding operation fails, an exception is raised. 💀
• valid-p -> Boolean (none|Integer) — returns true if the input stream is in a valid state. And what do we mean by valid state? We mean 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. Choose your fighter. 🥊
• eos-p -> Boolean (none) — returns true if the input stream has been closed or all bytes consumed. end-of-stream check, no notes.
• pushback -> Integer (Byte|Character|String) — pushes a byte, a Unicode character or a string back into the input stream. Subsequent calls to read will return the last pushed bytes. Pushing a string is equivalent to pushing each encoded byte of the string. The method returns the number of bytes pushed back. It's giving rewind. ⏪
• consume -> Integer (none) — consumes an input stream and places the read characters into the stream buffer. Returns the number of consumed characters. This method is generally used in conjonction with the to-string method.
• get-buffer-length -> Integer (none) — returns the length of the push-back buffer.
• to-string -> String (none) — returns a string representation of the input stream buffer. 🌸

---

📂 InputFile

The InputFile class provides the facility for an input file stream. You create an input file instance 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

• InputStreamNameable

Constructors

• InputFile (String) — creates 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) — creates 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) — closes the input file and returns true on success, false otherwise. And in case of success, multiple calls return true. So yes, you can just keep closing it, it's fine.
• lseek -> none (Integer) — sets the input file position to the integer argument. Note that the push-back buffer is reset after this call. 🫶
• length -> Integer (none) — returns the length of the input file. The length is expressed in bytes.
• get-modification-time -> Integer (none) — returns the modification time of the file. The returned argument is suitable for the Time and Date system classes.

---

🗺️ InputMapped

The InputMapped class 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. And finally, without any information at all, an always valid null input stream is constructed. Zero info, still valid, iconic behaviour honestly. ✨

Predicate

• input-mapped-p

Inheritance

• InputStream

Constructors

• InputMapped (none) — builds you a null input stream, and bestie this thing is literally just a null character generator, it gives nothing and that's the point ✨
• InputMapped (String|Buffer) — builds a mapped input stream by name or by buffer. Form one: the string is a file name and gets mapped as an input stream. Form two: the buffer gets mapped as an input stream. Two vibes, one constructor 💅
• InputMapped (String Integer Integer) — builds 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. Slay, but make sure your numbers are right 🎀

Methods

• lseek -> none (Integer) — sets the input mapped file position to the integer argument. Heads up: the push-back buffer gets reset after this call, no cap 🫶
• length -> Integer (none) — returns the length of the input mapped file, and it's expressed in bytes.

---

🦋 InputString 🦋

The InputString class hands you the whole facility for an input string stream. You initialize it (or set it) with a string and then it just... behaves like a stream. Iconic behaviour, honestly. This class is very useful when you want to handle generic stream methods without knowing what kind of stream is hiding behind it — main character energy for abstractions 💖

Predicate

input-string-p

Inheritance

InputStream

Constructors

• InputString (none) — creates an empty input string. A little blank canvas, we love to see it 🌸
• InputString (String) — creates an input string by value.

Methods

• get -> Byte (none) — returns the next available byte from the input stream but does not remove it. Peeking, not taking 🙈
• set -> none (String) — 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 gives you the facility for an input terminal stream. The input terminal reads bytes 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. Like, you can rawdog it, but why 😭

Predicate

input-term-p

Inheritance

InputStreamOutputStream

Constructors

• InputTerm (none) — creates a default input terminal.

Methods

• set-ignore-eos -> none (Boolean) — sets the input terminal end-of-stream ignore flag. When the flag is on, any character that matches a ctrl-d is changed to the end-of-stream mapped character returned by a read. This method is useful to prevent a reader from exiting when the ctrl-d byte is generated. Protecting your reader's peace fr fr 🫶
• set-mapped-eos -> none (Byte) — sets 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. They're a duo, don't split them up 💜

---

💀 OutputStream 💀

The OutputStream class is a base class for the standard i/o module. The class is automatically constructed by a derived class and provides the common methods for all output streams. It's giving founding mother of the whole output family 👑

Predicate

output-stream-p

Inheritance

Stream

Methods

• write -> Integer (Literal+) — writes one or more literal arguments on the output stream. Returns the number of characters written.
• writeln -> none (Literal+) — writes one or more literal arguments to the output stream and finishes with a newline. Returns nil.
• errorln -> none (Literal+) — writes one or more literal arguments to the associated output error stream and finishes with a newline. Most of the time, the output stream and error stream are the same, except for an output terminal. Sneaky little exception, iykyk 👀
• newline -> none (none) — writes a new line byte to the output stream. Returns nil.
• write-soh -> none (none) — writes a start-of-heading character to the output stream.
• write-stx -> none (none) — writes a start-of-transmission character to the output stream.
• write-etx -> none (none) — writes an end-of-transmission character to the output stream.
• write-eos -> none (none) — writes an end-of-stream character to the output stream.

---

🎀 OutputFile 🎀

The OutputFile class gives you 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's 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 exists, the file is truncated to 0 ⚠️ (yes, your old contents, gone, say bye). Another constructor for the output file gives you more control over this behaviour. It takes two boolean flags that define the truncate and append mode. The t-flag is the truncate flag. The a-flag is the append flag.

Predicate

output-file-p

Inheritance

OutputStreamNameable

Constructors

• OutputFile (String) — creates 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) — creates 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) — creates 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. Choose your flags wisely bestie 💅

Methods

• close -> Boolean (none) — closes the output file and returns true on success, false otherwise. In case of success, multiple calls return true. Consistent queen 💖

---

🍓 OutputString 🍓

The OutputString class gives you the facility for an output string stream. The class is initially empty and acts as a buffer which accumulates the write method bytes. The to-string method can be used to retrieve the buffer content. It's a little jar collecting your words 🌸

Predicate

output-string-p

Inheritance

OutputStream

Constructors

• OutputString (none) — creates a default output string.
• OutputString (String) — creates an output string by value. The output string stream is initialized with the string value.

Methods

• flush -> none (none) — flushes the output stream by resetting the stream buffer. Clean slate energy ✨
• length -> Integer (none) — returns the length of the output string buffer.
• to-string -> String (none) — returns a string representation of the output string buffer.

---

🧚 OutputBuffer 🧚

The OutputBuffer class gives you the facility for an output byte stream. The class is initially empty and acts as a buffer which accumulates the write method bytes. The to-string method can be used to retrieve the buffer content as a string. The format method can be used to retrieve the buffer content as an octet string. content. (Yes, that's the note, and we are keeping it 💀)

Predicate

output-buffer-p

Inheritance

OutputStream

Constructors

• OutputBuffer (none) — creates a default output buffer.
• OutputBuffer (String) — creates an output buffer by value. The output buffer stream is initialized with the string value.

Methods

• flush -> none (none) — flushes the output stream by resetting the stream buffer.
• length -> Integer (none) — returns the length of the output buffer.
• to-string -> String (none) — returns a string representation of the output buffer.
• format -> String (none) — returns an octet string representation of the output buffer.

---

💜 OutputTerm 💜

The OutputTerm class gives you 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. Read the room, pick the right terminal 😌

Predicate

output-term-p

Inheritance

OutputStream

Constructors

• OutputTerm (none) — creates a default output terminal.
• ErrorTerm (none) — 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. Best of both worlds, periodt 🔥

Predicate

terminal-p

Inheritance

InputTermOutputTerm

Constructors

• Terminal (none) — creates a default terminal which combines an input and output terminal with line editing capabilities.

Methods

• set-primary-prompt -> none (String) — sets the terminal primary prompt, which is used when the read-line method is called.
• set-secondary-prompt -> none (String) — sets the terminal secondary prompt, which is used when the read-line method is called.
• get-primary-prompt -> String (none) — returns the terminal primary prompt.
• get-secondary -> String (none) — the get-secondary-prompt method returns the terminal secondary prompt.

💌 Intercom 💌

okay so the Intercom class is the interpreter communication class, bestie. She runs on two streams: one output stream does the sending of serialized data, and the input stream does the deserializing of data. Wanna send something? send method. Wanna receive? recv method. iconic division of labor fr fr 💅

Predicate

intercom-p

Inheritance

Object

Constructors

• Intercom (none) — makes you a default interpreter communication object. There is no stream attached to it, so she's just vibing with nothing to do. 🫶
• Intercom (InputStream|OutputStream) — makes an interpreter communication object that has either an input or an output stream. In the first form, the input stream object gets used by the recv method to read a data object. In the second form, the output stream object gets used by the send method to send a data object.
• Intercom (InputStream OutputStream) — makes an interpreter communication object that has both an input and an output stream. the full package. ✨

Methods

• send -> none (Object) — the send method serializes the object argument with the help of the output stream bound to the interpreter communication object. If there's no output stream? Nothing gets sent. literally nothing. 💀
• recv -> Object (none) — the recv method deserializes an object with the help of the input stream bound to the interpreter communication object. If there is no output stream, nil is returned.
• request -> Object (Object) — the request method performs an atomic send receive operation. one round trip, no in-between. 🔥
• set-input-stream -> none (InputStream) — binds an input stream to the interpreter communication object.
• get-input-stream -> InputStream (none) — hands you back the input stream bound to the interpreter communication object.
• set-output-stream -> none (OutputStream) — binds an output stream to the interpreter communication object.
• get-output-stream -> OutputStream (none) — hands you back the output stream bound to the interpreter communication object.

---

🦋 InputOutput 🦋

The InputOutput class implements an input-output stream with a buffer, and that buffer holds characters during the processing of transit between the output stream and the input stream. Here's the theory of operation, bestie, stay with me: the internal buffer gets filled with characters with the help of the output stream. Then the characters get consumed from the buffer with the help of the input stream (that's the read method, iykyk). If the buffer becomes empty, the eos-p predicate returns true, the valid-p predicate goes false, and the read method will return the eos character. 🌸

The InputOutput buffer can also be initialized with a buffer — which is a genuinely nice mechanism to use a buffer like an input stream, no cap.

⚠️ 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. so don't try it, she will not wake up for you 😭

Predicate

input-output-p

Inheritance

InputStreamOutputStream

Constructors

• InputOutput (none) — creates a default input/output stream.
• InputOutput (String) — creates an input/output stream initialized with the string argument. That string argument is used to fill the string buffer. 🎀

Methods

• get -> Byte (none) — returns the next available byte from the input stream, but does not remove it. peek, don't touch. 👀
• set -> none (String) — sets the input string by first resetting the push-back buffer and then initializing the input string with the argument value. order matters, bestie.

---

🌈 Selector 🌈

The Selector class provides some facilities to perform i/o multiplexing. The constructor takes 0 or several stream arguments. The class automatically manages the differentiation between InputStream and OutputStream objects — she just knows. Once the class is constructed, it's possible to get the first stream ready for reading or writing, or all of them. You can also add more streams after construction with the add method. 💅

When a call to the wait method succeeds, the method returns the first available stream. If the waitall method is called, it returns a vector with all ready streams. The selector can also be configured to operate in marking mode. In that mode, the selector can be marked as ready by a thread independently of the bounded streams — which is a genuinely useful mechanism you can use to cancel a select loop. The mark method is designed to mark the selector, while the marked-p predicate returns true if the stream has been marked. 👑

Predicate

selector

Inheritance

Object

Constructors

• Selector (none) — creates a default stream selector.
• Selector ([Boolean] [InputStream|OutputStream]*) — creates a stream selector with 0 or more stream arguments. If the first argument is a boolean, the selector is constructed in marked mode. 🎀

Methods

• add -> none (InputStream|OutputStream) — 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 that preference is not acceptable to you, the input-add or the output-add methods might be preferable. pick your fighter.
• input-add -> none (InputStream) — adds an input stream to the selector.
• output-add -> none (OutputStream) — adds an output stream to the selector.
• wait -> Stream (none|Integer) — waits for a status change in the selector and returns the first stream that has changed status. With one argument, the selector times out after the specified time in milliseconds. Note that at the time of the return, several streams may have changed status. sneaky.
• wait-all -> Vector (none|Integer) — waits for a status change in the selector and returns all streams that have changed status in a vector object. With one argument, the selector times out after the specified time in milliseconds. If the selector has timed-out, the vector is empty. 😶
• input-get -> InputStream (Integer) — returns the input streams in the selector by index. If the index is out of bound, an exception is raised. 🚨
• output-get -> OutputStream (Integer) — returns the output streams in the selector by index. If the index is out of bound, an exception is raised. 🚨
• input-length -> Integer (none) — returns the number of input streams in the selector.
• output-length -> Integer (none) — returns the number of output streams in the selector.
• mark -> none (none) — marks a selector object.
• marked-p -> Boolean (none) — returns true if the selector has been marked.

---

🍓 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 it can be activated with the set-tee method. so by default she's keeping it to herself, periodt. 💜

Predicate

logtee-p

Inheritance

Logger

Constructors

• Logtee (none) — creates a default logger without an output stream.
• Logtee (Integer) — creates a logger with a specific size, without an output stream. (the manpage just says terminal here at the end and honestly? relatable. we love a cryptic queen.)
• Logtee (OutputStream) — creates a logger with an output stream. The object is initialized to operate in write mode.
• Logtee (Integer OutputStream) — creates a logger with a specific size and an output stream. First argument is the logger size. Second argument is the output stream.
• Logtee (Integer String OutputStream) — creates a logger with a specific size, an information string, and an output stream. First argument is the logger size. Second argument is the information string. Third argument is the output stream. 🎀

Methods

• set-tee-stream -> none (OutputStream) — sets the tee output stream. Heads up bestie: this stream is different from the logger output stream.
• get-tee-stream -> OutputStream (none) — returns the object output stream.
• set-tee -> none (Boolean) — sets the object tee flag. When the flag is true, the logger writes the added message on the output stream.
• get-tee -> Boolean (none) — 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. She operates with a directory name and a file name — and 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. main character behavior, honestly.

Predicate

pathname-p

Inheritance

Object

Constructors

• Pathname (none) — creates a default path name without file and directory names.
• Pathname (String) — creates a path name with a file name. The first string argument is the file name.
• Pathname (String String) — 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) — resets the path name by removing all path and file information. clean slate, we love a fresh start. 🦋
• dir-p -> Boolean (none) — returns true if the path is a directory.
• file-p -> Boolean (none) — returns true if the path is a file.
• set-file-name -> none (String) — bestie, this sets the path name's file name. The string you hand over is the file name. That's it, that's the whole job. 💅
• get-file-name -> String (none) — hands you back the path name's file name. No args, no drama. ✨
• add-directory-name -> none (String) — adds the directory name onto the directory path component. The string argument is the directory name. 🎀
• set-directory-name -> none (String) — sets the directory name file name. The string argument is the directory name. (Yes, the original says it exactly like that, and we are not about to start guessing, so.) 🌸
• get-directory-name -> String (none) — returns the path name directory name. Boom. 🦋
• length -> Integer (none) — tells you how many directory path elements there are. A little headcount for your path. 🔢
• get-path -> String (Integer) — give it an index, it gives you back a directory path element. 🫶
• get-root -> String (none) — returns the root component of a directory name. The origin story. 👑
• get-full -> String (none) — returns the full path name by combining the directory name with the file name. Glow-up complete. 🌈
• add-path -> none (String) — adds a new path component by name. Here's the tea: the path gets separated into individual components and added to the directory path, unless it's a root path. If the file name is set, the file name gets added as a directory component. And if the path is a root path, a whole new path name is rebuilt — which is equivalent to a call to set-file-name. Yes, really. 😭
• normalize -> none (none) — rebuilds the path name by figuring out the full path nature if it possibly can. If it succeeds, the path structure reflects the actual path type. No cap. 🔥

---

💖 Pathlist 💖

The Pathlist class is a base class designed to make manipulating a file search path so much easier. It acts like a list of search paths, and it comes with a bunch of facilities for finding a valid path for a given name. You can manipulate the path list like any other list, fr fr.

🔍 Predicate

• pathlist-p

🧬 Inheritance

• Object

🎀 Constructors

• Pathlist (none) — makes a default path list. Simple, clean, iconic.
• Pathlist (Boolean|String) — makes a path list with either a local search flag or an initial path component. First form: a boolean argument controls the local search flag. Second form: a string argument is used as the initial path component. Two vibes, one constructor. ✨

💅 Methods

• reset -> none (none) — resets the path list by clearing the local search flag and removing all path components. Full factory reset, bestie. 🧼
• local-p -> Boolean (none) — returns true if the local search flag is set. Vibe check on the flag. 🚩
• set-local-search -> none (Boolean) — sets the local search flag. That's the whole thing. 🫶
• length -> Integer (none) — returns the number of directory path elements. 🔢
• get-path -> String (Integer) — returns a directory path element by index. 🎯
• add-path -> none (String) — adds a new path component by name. The string argument is the name to add. ✨
• file-p -> Boolean (String) — returns true if the file name argument can be resolved. If the local search flag is set, the local directory gets checked first. 👀
• resolve -> String (String) — returns a string representation of the resolved file path. And if the local search flag is set and the file name is found locally, you just get the initial name argument right back. Iconic behaviour, honestly. 💖

🧚 Functions

• dir-p -> Boolean (String) — returns true if the argument name is a directory name, false otherwise. 🗂️
• file-p -> Boolean (String) — returns true if the argument name is a regular file name, false otherwise. 📄
• tmp-name -> String (String?) — returns a name suitable for use as a temporary file name. With no argument, a default prefix builds the name. An optional string prefix can control the original name. 🍓
• tmp-path -> String (String?) — returns a path suitable for use as a temporary file name. With no argument, a default prefix builds the path. An optional string prefix can control the original name. 🛤️
• absolute-path -> String (String+) — returns an absolute path name from an argument list. With no argument, it returns the root directory name. With one or several arguments, the absolute path is computed from the root directory. 🌍
• relative-path -> String (String+) — returns a relative path name from an argument list. With one argument, it just returns it. With two or more, the relative path is computed by joining each argument with the previous one. Chain reaction, but make it file paths. 🔗
• rmfile -> none (String+) — removes one or several files specified as the arguments. > If one file fails to be removed, an exception is raised. No silent failures here. 💀
• mkdir -> none (String+) — creates one or several directories specified as the arguments. > If one directory fails to be created, an exception is raised. 😤
• mhdir -> none (String+) — creates hierarchically one or several directories specified as the arguments. > If one directory fails to be created, an exception is raised. Nested glow-up. 🌲
• rmdir -> none (String+) — 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) — 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. Periodt. 📛
• get-base-path -> String (String) — returns the base path from a path. The base path is a directory name. By definition — yes, again — a path is made of a base path and a base name. 🧭
• get-extension -> String (String) — returns the extension from a path. 🏷️
• remove-extension -> String (String) — returns the extension from a path. And heads up bestie: in order to get a base file name from a path, you have to call the get-base-name function first. Order matters! ⚠️

---

🌸 Directory 🌸

The Directory class gives you 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 it's built, you can retrieve its content. It's giving organized. 🗂️✨

🔍 Predicate

• directory-p

🧬 Inheritance

• Object

🎀 Constructors

• Directory (none) — creates a directory object whose location is the current directory. > If the directory cannot be opened, an exception is raised. 🚨
• Directory (String) — creates 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) — creates a new directory inside the current one. The full path is constructed by taking the directory name and adding the argument. Once it's created, the method returns a directory object of the newly constructed directory. > An exception is thrown if the directory cannot be created. New folder, who dis. 🎉
• rmdir -> none (String) — 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. (Empty only, bestie — don't come for me if there's stuff inside.) 🙈
• rmfile -> none (String) — 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) — returns the directory name. And if the default directory was created, it returns the full directory path instead. 🏷️
• get-list -> List (none) — returns the directory contents as a list of strings. The list contains all valid names at the time of the call, including the current directory and the parent directory. Yes, those two are invited to the party. 🎈
• get-files -> List (none) — returns the directory contents as a list of strings of files. The list contains all valid names at the time of the call. 📄
• get-subdirs -> List (none) — returns the sub directories as 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) — returns the next available name from the directory stream. This method is so useful when you're operating with a large number of elements. 🌀
• next-path -> String (none) — returns the next available path name from the directory stream. Also useful when operating with a large number of elements. 🛤️
• next-file-name -> String (none) — returns the next available file name from the directory stream. Useful when operating with a large number of elements, obviously. 📁
• next-file-path -> String (none) — returns the next available file path name from the directory stream. Useful when operating with a large number of elements. 🧭
• next-dir-name -> String (none) — returns the next available directory name from the directory stream. Useful when operating with a large number of elements. 🗺️
• next-dir-path -> String (none) — hands you the next available directory path name from the directory stream. lowkey the MVP when you're dealing with a huge number of elements — like, thousands of them. ✨

---

💖 Logtee

The Logtee class is a message logger facility that's attached to an output stream. The way it works: when you add a message to the logger object, that message also gets sent to the output stream — but only depending on the controlling flags, okay? And the name "logtee"? It's literally a glow-up of "logger" + "tee" mashed together, iconic. 🎀

One particularity of the class (and it's giving very special): if there's no stream, the class just behaves like a regular logger. No drama. 🦋

Predicate

• logtee-p

Inheritance

• Logger

Constructors

• Logtee (none) — makes a default logger with no output stream. Simple. Clean. 💅
• Logtee (Integer) — makes a logger object with a specific size and no output stream.
• Logtee (Output) — makes a logger object with an output stream.
• Logtee (Integer Output) — makes a logger object with a specific size and an output stream. First argument = the logger window size. Second argument = the output stream. 🫶
• Logtee (Integer String Output) — makes a logger object with a specific size, an information string, and an output stream. First argument = logger window size. Second argument = logger information string. Third argument = output stream. Three-for-three, slay. ✨

Methods

• set-output-stream -> none (Output) — attaches the output stream to the logtee object. 🎀
• get-output-stream -> Output (none) — returns the logtee output stream.
• set-tee -> none (Boolean) — sets the logtee control flag. That flag is what controls whether the message shows up on the output stream, so like… it matters. 💅
• get-tee -> Boolean (none) — returns the logtee output stream. (Yes, that's what it says, bestie. I'm just the messenger. 🙈)

---

🦋 NamedFifo

The NameFifo class is a string vector designed to operate as a stream fifo object. It gives you the facility to read or write the fifo content from a stream. And here's the cute part: the stream can be created by name for writing — in which case the named fifo operates as a backup object. No cap. 🔥

Predicate

• named-fifo-p

Inheritance

• StrvecNameable

Constructors

• NamedFifo (none) — makes a default named fifo with no backing name. And in that case? The fifo can't be read or written by stream. Periodt. 💀
• NamedFifo (String) — makes a named fifo by name. That name is used as a file name for reading or writing the fifo.
• NamedFifo (String Boolean) — makes a named fifo by name, 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) — reads the fifo file name and fills the fifo.
• write -> none (none) — writes the fifo contents to the fifo file name.
• set-name -> none (String) — sets the fifo file name.

---

🌈 FileInfo

The FileInfo is a file information class that holds the primary info related to a file — like its size, or its modification time. The file information gets set at construction, but you can update it later with the help of the update method. Bestie stays flexible. 💜

Predicate

• file-info-p

Inheritance

• Nameable

Constructors

• (String) — makes a file information by name. The string argument is the file name to query. 🔍

Methods

• length -> Integer (none) — returns the file size information.
• get-modification-time -> Integer (none) — returns the file modification time. And get this: that time can be used as an argument to the Time or Date object. Iconic crossover. ⭐
• update -> none (none) — updates the file information data.

---

And that's a wrap on sio(3) bestie!! 🎀 This page is the AFNIX Module manual, from AFNIX, and yeah — it's sio(3). Go forth and slay your streams, ily, mwah 💖🦋✨