# Special objects

This chapter is a reference of the reserved special objects with their respective built-in methods. Special objects are those objects which interact with the interpreter.

Object

The base object `Object` provides several methods which are common to all objects.

repr
String
none

The `repr` method returns the object name in the form of a string. The result string is called the representation string.

rdlock
none
none

The `rdlock` method try to acquire the object in read-lock mode. If the object is currently locked in write mode by another thread, the calling thread is suspended until the lock is released.

wrlock
none
none

The `wrlock` method try to acquire the object in write-lock mode. If the object is currently locked by another thread, the calling thread is suspended until the lock is released.

unlock
none
none

The `unlock` method try to unlock an object. An object will be unlocked if and only if the calling thread is the one who acquired the lock.

clone
Object
none

The `clone` method returns a clone of the calling object. If the object cannot be cloned, an exception is raised.

Interp

The `Interp` is the interpreter object which is automatically bounded for each executable program. There is no constructor for this object. The current interpreter is bounded to the `interp` reserved symbol.

interp-p
Runnable
argv

The `argv` data member holds the interpreter argument vector. The vector is initialized when the interpreter is created. Each argument is stored as a string object.

os-name

The `os-name` data member holds the operating system name. The data member evaluates as a string.

os-type

The `os-type` data member holds the operating system type. The data member evaluates as a string.

version

The `version` data member holds the full engine version. The data member evaluates as a string.

program-name

The `program-name` data member holds the interpreter program name. The data member evaluates as a string.

major-version

The `major-version` data member holds the interpreter major revision number. The data member evaluates as an integer.

minor-version

The `minor-version` data member holds the interpreter minor revision number. The data member evaluates as an integer.

patch-version

The `patch-version` data member holds the interpreter patch revision number. The data member evaluates as an integer.

afnix-uri

The `afnix-uri` data member holds the official uri. The data member evaluates as a string.

machine-size

The `machine-size` data member holds the interpreter machine size expressed in bits. Most of the time, the machine size is either 32 or 64 bits. If something else is returned, it certainly reflects an exotic platform.

loader

The `loader` data member holds the interpreter library loader. Under normal circumstances, the library loader should not be used and the standard `interp:library` form should be used.

resolver

The `resolver` data member holds the interpreter resolver. The resolver can be used to add dynamically a librarian or a directory to the interpreter module resolver.

load
Boolean
String

The `load` method opens a file those name is the method argument and executes each form in the file by doing a read-eval loop. When all forms have been executed, the file is closed and the method returns true. In case of exception, the file is closed and the method returns false.

library
Library
String

The `library` method opens a shared library and a returns a shared library object.

launch
Thread
form|thread form

The `launch` method executes the form argument in a normal thread. The normal thread is created by cloning the current interpreter. In the first form, a thread object is created by the method and return when the thread as been launched. In the second form, a thread is started by binding a form to the thread object.

set-epsilon
none
Real

The `set-epsilon` method sets the interpreter epsilon which corresponds to the real precision. The real precision is used by the `?=` operator to compare real values.

get-epsilon
Real
none

The `get-real precision` method returns the interpreter epsilon which correspond to the real precision. The real-precision is used by the `?=` operator to compare real values.

dup
Interp
none|Terminal

The `dup` method returns a clone of the current interpreter by binding the terminal steam argument. Without argument, a new terminal object is automatically created and bound to the newly created interpreter.

loop
Boolean
none

The `loop` method executes the interpreter main loop by reading the interpreter input stream. The loop is finished when the end-of-stream is reached with the input stream. The method returns a boolean flag to indicate whether or not the loop was successful.

set-primary-prompt
none
String

The `set-primary-prompt` method sets the interpreter terminal primary prompt which is used during the interpreter main loop.

set-secondary-prompt
none
String

The `set-secondary-prompt` method sets the interpreter terminal secondary prompt which is used during the interpreter main loop.

get-primary-prompt
String
none

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

get-secondary
String
none

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

Thread

The `Thread` object is a special object which acts as a thread descriptor. Such object is created with the `launch` reserved keyword.

thread-p
Object
Thread
none

The `Thread` constructor create a default thread object without any form bound to it. The object can be later used with the `launch` command.

end-p
none
none

The `end-p` predicate returns true if the thread argument has finished. This predicate indicates that the thread result is a valid one.

wait
none
none

The `wait` method suspends the calling thread until the thread argument as completed. The `wait` method is the primary mechanism to detect a thread completion.

result
Object
none

The `result` method returns the thread result. If the thread is not completed, the `nil` value is returned. However, this method should not be used to check if a thread has completed and the `wait` method must be used because a thread result might be `nil`.

Condvar

The condition variable `Condvar` object is a special object which provides a mean of synchronization between one and several threads. The condition is said to be false unless it has been marked. When a condition is marked, all threads waiting for that condition to become true are notified and one thread is activated with that condition.

condvar-p
Object
Condvar
none

The `Condvar` constructor creates a default condition variable.

lock
none
none

The `lock` method locks the condition variable mutex. If the mutex is already locked, the calling thread is suspended until the lock is released. When the method returns, the resumed thread owns the condition variable lock. It is the thread responsibility to reset the condition variable and unlock it.

mark
none
none

The `mark` method marks the condition variable and notify all pending threads of such change. The mark method is the basic notification mechanism.

wait
none
none

The `wait` method waits for a condition variable to be marked. When such condition occurs, the suspended thread is run. When the method returns, the resumed thread owns the condition variable lock. It is the thread responsibility to reset the condition variable and unlock it.

reset
none
none

The `reset` method acquires the condition variable mutex, reset the mark, and unlock it. If the lock has been taken, the calling thread is suspended.

unlock
none
none

The `unlock` method unlock the condition variable mutex. This method should be used after a call to `lock` or `wait`.

wait-unlock
none
none

The `wait-unlock` method wait until a condition variable is marked. When such condition occurs, the suspended thread is run. Before the method returns, the condition variable is reset and the mutex unlocked. With two threads to synchronize, this is the preferred method compared to `wait`.

Lexical

The `Lexical` object is a special object built by the reader. A lexical name is also a literal object. Although the best way to create a lexical name is with a form, the lexical object can also be constructed with a string name. A lexical name can be mapped to a symbol by using the `map` method.

lexical-p
Literal
Lexical
none

The `Lexical` constructor create an empty lexical object which evaluates to `nil`.

Lexical
String

The `Lexical` constructor create a lexical object using the string argument as the lexical name.

map
Object
none

The `map` method returns the object that is mapped by the lexical name. Most of the time, a symbol object is returned since it is the kind of object stored in a nameset. Eventually the mapping might returns an argument object if used inside a closure.

Qualified

The `Qualified` object is a special object built by the reader. A qualified object is similar to a lexical object. It is also a literal object. Like a lexical name, a qualified name can be created with a form or by direct construction with a name. Like a lexical name, the `map` method can be used to retrieve the symbol associated with that name.

qualified-p
Literal
Qualified
none

The `Qualifed` constructor create an empty qualified name object which evaluates to `nil`.

Qualified
String

The `Qualified` constructor create a qualified name object using the string argument as the qualified name. The name is parse for qualified name syntax adherence.

map
Object
none

The `map` method returns the object that is mapped by the qualified name. Most of the time, a symbol object is returned since it is the kind of object stored in a nameset. Eventually the mapping might returns an argument object if used inside a closure.

Symbol

The `Symbol` object is a special object used by nameset to map a name with an object. Generally a symbol is obtained by mapping a lexical or qualified name. As an object, the symbol holds a name, an object and a constant flag. The symbol name cannot be changed since it might introduce inconsistencies in the containing nameset. On the other hand, the constant flag and the object can be changed. A symbol is a literal object. A symbol that is not bounded to a nameset can be constructed dynamically. Such symbol is said to be not interned.

symbol-p
Literal
Symbol
String

The `Symbol` constructor create a symbol by name. The associated object is marked as `nil`.

Symbol
String Object

The `Symbol` constructor create a symbol by name and bind the object argument to the symbol.

get-const
Boolean
none

The `get-const` method returns the symbol const flag. If the flag is true, the symbol object cannot be changed unless that flags is reset with the `set-const` method.

set-const
none
Boolean

The `set-const` method set the symbol const flag. This method is useful to mark a symbol as const or to make a const symbol mutable.

get-object
Object
none

The `get-object` method returns the symbol object.

set-object
none
Object

The `set-object` method set the symbol object. The object can be obtained by evaluating the symbol.

Closure

The `Closure` object is a special object that represents a lambda or gamma expression. A closure is represented by a set of arguments, a set of closed variables and a form to execute. A boolean flag determines the type of closure. The closure predicate `lambda-p` returns true if the closure is a lambda expression. Closed variables can be defines and evaluated with the use of the qualified name mechanism. Closure mutation is achieved with the `add-argument` and `set-form` method. An empty closure can be defined at construction as well.

closure-p
Object
Closure
none

The `Closure` constructor create a default closure. When the closure is created, a local set of arguments and closed variables is generated. Note that such local set is dynamic. There is no restriction to reconfigure a particular lambda at run-time. The difference between a lambda and a gamma expression resides in the nameset binding when the closure is called. With a lambda, the closure nameset parent is the calling nameset. With a gamma expression, the parent nameset is always the top-level interpreter nameset. Note also, that the symbol `self` is automatically bounded for this closure.

Closure
Boolean

The `Closure` constructor create a closure which acts as lambda expression if the boolean argument is true. If the boolean argument is false, the closure will behave like a gamma expression.

gamma-p
Boolean
none

The `gamma-p` predicate returns true if the closure is a gamma expression. The predicate returns true for a lambda expression.

lambda-p
Boolean
none

The `lambda-p` predicate returns true if the closure is a lambda expression. The predicate returns false for a gamma expression.

get-form
Object
none

The `get-form` method returns the closure form object.

set-form
none
Object

The `set-form` method sets the closure form object.

add-argument
none
String|Lexical|form

The `add-argument` method adds an argument to the closure. The argument object can be either a string, a lexical object of a simple form that defines a constant lexical name.

Librarian

The `Librarian` object is a special object that read or write a librarian. Without argument, a librarian is created for writing purpose. With one file name argument, the librarian is created for reading.

librarian-p
Nameable
Librarian
none

The `Librarian` constructor creates a librarian for writing. Initially, the librarian is empty and files must be added with the `add` method.

Librarian
String

The `Librarian` constructor creates a librarian for reading using the name as the librarian file name.

add
none
String

The `add` method adds a file into the librarian. The librarian must have been opened in write mode.

write
none
String

The `write` method writes a librarian to a file those name is the argument.

length
Integer
none

The `length` method returns the number of file in the librarian. This method work, no matter how the librarian has been opened.

exists-p
Boolean
String

The `exists-p` predicate returns true if the file argument exists in the librarian.

extract
InputMapped
String

The `extract` method returns an input stream mapped to the file name argument.

Resolver

The `Resolver` object is a special object that gives the ability to open a file based on a file path resolver. The resolver maintains a list of valid path and returns an input stream for a file on demand.

resolver-p
Object
Resolver
none

The `Resolver` constructor creates a default resolver. Once created, the `add` method can be used to add path to the resolver.

add
none
String

The `add` method adds a path into the resolver. The path can points either to a directory or a librarian.

lookup
InputStream
String

The `lookup` method resolves the file name argument and returns an input stream for that file.

valid-p
Boolean
String

The `valid-p` predicate returns true if the file name argument can be resolved. If the file name can be resolved, the `lookup` method can be called to get an input stream.

PrintTable

The PrintTable class is a formatting class for tables. The table is constructed with the number of columns -- default to 1 -- and eventually the number of rows. Once the table is created, element are added to the table with the `add` method. Specific table element can be set with the `set` method. The class provide a `format` method those default is to print the table on the interpreter standard output. With an output stream argument or a buffer, the table is formatted to these objects. The table formatting includes an optional column width, a filling character and a filling direction flag. By default, the column width is 0. This means that the column width is computed as the maximum length of all column elements. If the column width is set with the `set-column-size` method, the string element might be truncated to the left or right -- depending on the filling flag -- to fit the column width.

print-table-p
Object
PrintTable
none

The `PrintTable` constructor creates a default table with one column.

PrintTable
Integer

The `PrintTable` constructor creates a table with a pre-defined number of columns specified in the constructor argument.

PrintTable
Integer Integer

The `PrintTable` constructor creates a table with a pre-defined number of columns and rows specified in the constructor arguments.

head-p
Boolean
none

The `head-p` predicate returns true if the table header is defined.

add-head
none
[String+]

The `add-head` method add to the table header the string arguments. The number of arguments must be equal to the number of columns.

get-head
String
Integer

The `get-head` method returns a table header element by column index. The integer argument is the header row index.

set-head
none
Integer String

The `set-head` method sets a table header element by column index. The first argument is the header column index and the second is the header string value to set.

add
Integer
none|[Literal...]

The `add` method serves several purposes. Without argument, a new row is added and the row index is returned. The row index can be later used with the `set` method to set a particular table element. With one or several literal arguments, those length must match the number of columns, a new row is created and those arguments added to the table. The row number is also returned.

get
String
Integer Integer

The `get` method returns a particular table element by row and column. The first argument is the table row index and the second is the table column index.

set
none
Integer Integer Literal

The `set` method sets a particular table element by row and column. The first argument is the table row index and the second is the table column index. The last argument is a literal object that is converted to a string prior its insertion.

dump
none|String
none|Integer|OutputStream|Buffer

The `dump` method dumps the table to an output stream or a buffer. Without argument, the default interpreter output stream is used. With an integer argument, the specified row is used and a string is returned. With a buffer or an output stream, the whole table is written and nothing is returned.

format
none|String
none|Integer|OutputStream|Buffer

The `format` method writes the formatted table to an output stream or a buffer. Without argument, the default interpreter output stream is used. With an integer argument, the specified row is used and a string is returned. With a buffer or an output stream, the whole table is written and nothing is returned.

get-rows
Integer
none

The `get-rows` method returns the number of rows in the table.

get-columns
Integer
none

The `get-columns` method returns the number of columns in the table.

set-column-size
none
Integer Integer

The `set-column-size` method sets the desired width for a particular column. The first argument is the column index and the second argument is the column width.If 0 is given, the column width is computed as the maximum of the column elements.

get-column-size
Integer
Integer

The `get-column-size` method returns the desired width for a particular column.

set-column-fill
none
Integer Character

The `set-column-fill` method sets the filling character for a particular column. The first argument is the column index and the second argument is a character to use when filling a particular column element. The default filling character is the blank character.

get-column-fill
Character
Integer

The `get-column-fill` method returns the filling character for a particular column.

set-column-direction
none
Integer Boolean

The `set-column-direction` method sets the direction flag for a particular column. The first argument is the column index and the second argument is a boolean. A false value indicates a filling by the left while a true value indicates a filling by the right. The column filling character is used for this operation.

get-column-direction
Boolean
Integer

The `get-column-direction` method returns the direction flag for a particular column.

Logger

The Looger class is a message logger that stores messages in a buffer with a level. The default level is the level 0. A negative level generally indicates a warning or an error message but this is just a convention which is not enforced by the class. A high level generally indicates a less important message. The messages are stored in a circular buffer. When the logger is full, a new message replace the oldest one. By default, the logger is initialized with a 256 messages capacity that can be resized.

logger-p
Object
Logger
none

The `Logger` constructor creates a default logger.

Logger
Integer

The `Logger` constructor creates a logger with a specific size specified as the constructor argument.

Logger
String

The `Logger` constructor creates a logger with an information argument. The information string is later used to format the logged messages.

Logger
Integer String

The `Logger` constructor creates a logger with a specific size and an information argument. The first argument is the logger size. The second argument is the information string. The information string is later used to format the logged messages.

add
none
String|String Integer

The `add` method adds a message in the logger. With one argument, the method take a single string message. with two arguments, the first arguments is the message and the second argument is the message level.

reset
none
none

The `reset` method reset the logger class by removing all messages.

length
Integer
none

The `length` method returns the number of messages stored in the logger object.

resize
none
Integer

The `resize` method resize the logger class by increasing the size of the message buffer. The old messages are kept during the resizing operation.

set-info
none
String

The `set-info` method sets the logger information string. The information string is used by the derived classes when a message is printed.

get-info
String
none

The `get-info` method returns the logger information string. The information string is used by the derived classes when a message is printed.

set-default-level
none
Integer

The `set-default-level` method sets the default level use for storing message. This parameter is used with the `add` method in conjunction with the message argument. When the message level is specified, the default message level is ignored.

get-default-level
Integer
none

The `get-default-level` method returns the default message level used by the logger. The default message level is used by the `add` method when the message level is not specified directly.

get-message
String
Integer

The `get-message` method returns a logger message by index. The integer argument is the message index.

get-full-message
String
Integer

The `get-full-message` method returns a fully formatted logger message by index. The integer argument is the message index. The message includes the time and contents.

get-message-time
Integer
Integer

The `get-message-time` method returns the logger message time by index. The integer argument is the message index.

get-message-level
Integer
Integer

The `get-message-level` method returns the logger message level by index. The integer argument is the message index.

set-output-stream
none
OutputStream|String

The `set-output-stream` method set the logger output stream. The output stream can be either an output stream or an output file name.

Counter

The Counter class is a mechanism designed to count integer both upward or downward. The counter is initialized with a start and end value. With a single value, the start value is set to 0 and the counter direction determined by the end value. The counter object is also a literal object, meaning that it can be directly printed. The object is also designed to be used directly in a loop.

counter-p
Literal
Counter
none

The `Counter` constructor creates a default counter. Since, both start and end values are initialized to 0, this object will never count.

Counter
Integer

The `Counter` constructor creates an upward counter. If the argument value, the initial counter value is the argument value and the counter will counter from the value to 0. If the argument value is positive, the final counter value is the argument value and the counter will count from 0 to this value.

Counter
Integer Integer

The `Counter` constructor creates a counter with an initial and final values. Depending on the initial and final value the counter might be an upward or a downward counter.

reset
none
none

The `reset` method reset the counter to its start value.

step-p
Boolean
none

The `step-p` predicate checks if the counter can be moved by one position. If the test is successful, the counter is moved upward or downward. the method returns the result of the test.

valid-p
Boolean
none

The `valid-p` predicate returns true if the counter can be moved by one position.

Former

The `Former` class is an abstract class used to derive form reader. The class defines only a method `parse` which returns a form. The method `getlnum` returns the form line number.

former-p
Object
parse
Form
none

The `parse` method returns the next available form.

get-line-number
Integer
none

The `get-line-number` method returns the form line number which is the current line number under processing.

Reader

The `Reader` class is the general purpose form reader which supports the writing system syntax. The reader is primarily used to parse file or be run interactively. The reader consumes tokens until a complete form can be built. The form does not have any particular meaning and must be post processed by the application.

reader-p
Former
Nameable
Reader
none

The `Reader` constructor creates a default reader.

Reader
String|InputStream

The `Reader` constructor creates a reader by string or input stream. In the first form, a string is mapped into a string stream which is used by the reader to parse form. In the second form, an input stream is bound to the reader to parse forms.

Loader

The `Loader` class is a library loader. The loader keep a list of loaded libraries. This class is bound to the interpreter and cannot be constructed. Use the `interp:loader` to access the interpreter loader. for safety reason, it is not possible to add a libray to the loader. The interpreter method `interp:library` is the prefered method to access the loader.

loader-p
Object
length
Integer
none

The `length` method returns the number of loaded libraries.

get
Library
Integer

The `get` method returns a library object by index.

exists-p
Boolean
String

The `exists-p` predicate returns true if a library is already loaded in the interpreter.