NAME
vol-2 - afnix reference manual
RESERVED KEYWORDS
This chapter contains a summary of the AFNIX reserved keywords with
their syntax.
assert
The assert reserved keyword check for equality between two operands.
Both objects must be of the same type. If the equality test fails, the
reserved keyword print a message and abort the execution. By default,
the assertion checking is turned off. The interpreter option -f assert
enables the assertion checking. When the interpreter is compiled in
debug mode, the assertion checking is turned on by default.
Syntax
assert "form 1" "form 2"
Example
assert true (== 1 1) assert 3 (+ 2 1)
block
The block reserved keyword defines a new nameset for sequential
execution of regular form or implicit form. When the block form is
evaluated, the block nameset is linked to its parent nameset. When all
forms have been executed, the block nameset is destroyed and the result
of the last evaluation in the block is considered to be the result of
the block evaluation.
Syntax
block "regular form" block "block form"
Example
trans a 1 block {
assert a 1
trans a (+ 1 1)
assert a 2
assert ..:a 1 } assert 1 a
class
The class reserved keyword creates a new class object. Without
argument, an instance of that class is created without data members.
With a list of arguments, the instance is created with a set of data
member initialized to nil.
Syntax
class class "data member-list"
Example
const Color (class) trans Color:initialize (red green blue) {
const this:red red
const this:green green
const this:blue blue } const red (Color 255 0 0) const
green (Color 0 255 0) const blue (Color 0 0 255)
const
The const reserved keyword binds a symbol with an object and marks it
as a constant symbol. When used with three or four argument, a gamma
expression is automatically created. const can also be used to bind
class or instance members.
Syntax
const symbol "object" const symbol "argument" "body" const
symbol "argument" "closed variables" "body"
Example
const number 123 const max (x y) (if (> x y) x y)
daemon
The daemon reserved keyword creates a new thread by executing the form
argument in a daemon thread. The created thread is executed by creating
a clone of the interpreter and starting immediately the execution of
the form with the cloned interpreter. The command returns the thread
object in the calling thread. When the thread terminates, the thread
object holds the result of the last executed form. The main thread does
not wait for a daemon thread to terminate.
Syntax
daemon "form"
Example
daemon (println "hello world")
delay
The delay reserved keyword delays the evaluation of the form argument
by creating a Promise object. The promise evaluate to itself until a
call to force the evaluation has been made. When the promise has been
forced, the evaluation result is stored. Further call to force will
produce the same result.
Syntax
delay "form"
Example
trans y 3 const l ((lambda (x) (+ x y)) 1) assert 4 (force l)
trans y 0 assert 4 (force l)
do
The do reserved keyword is used to build loop with forward condition.
The loop construct accepts either 2 or 3 arguments. With 2 argument,
the first argument is the loop body and the second argument is the loop
condition which must evaluates to a boolean object. With 3 arguments,
the first argument is the initial condition that is executed only once.
Syntax
do "body" "condition" do "initial" "body" "condition"
Example
const number-of-digits (s) {
const len (s:length)
trans index 0
trans count 0
do {
trans c (s:get index)
if (c:digit-p) (count:++)
} (< (index:++) len)
eval count }
enum
The enum reserved keyword creates an enumeration from a list of
literal. The result object is an Enum object that holds the enumerated
items. An item evaluation results with an Item object that is bound to
the enumeration object.
Syntax
enum "literal" ...
Example
const e (enum E1 E2 E3)
errorln
The errorln reserved keyword prints on the interpreter error stream a
set of arguments. Each arguments have to be a literal which are
converted to a string. When all arguments have been printed a new line
character is printed. The error reserved keyword behaves like errorln
excepts that a new line character is not printed at the end of the
arguments.
Syntax
errorln errorln "nil" errorln "literal list"
Example
errorln errorln "hello millennium" ’ ’ 2000
eval
The eval reserved keyword simply evaluates the object argument. The
form is useful when returning an argument from a lambda or gamma
expression using an implicit form.
Syntax
eval "object"
Example
const ret (x) (eval x) eval (protect (+ 1 2))
for
The for reserved keyword provides a facility to iterate on iterable
objects. The Cons, List and Vector objects are typical iterable
objects. For each iterable objects, a symbol is set after each
iteration. Each object symbol value can be used for further
computation. The iteration stops when one of the objects iterator is at
the end position.
Syntax
for "symbol list" "iterable object list" "body"
Example
# compute the scalar product of two vectors const scalar-product
(u v) {
trans result 0
for (x y) (u v) (result:+= (* x y))
eval result }
force
The force reserved keyword forces the evaluation of its argument. If
the argument evaluates to a promise object, the promise evaluation is
forced. If the argument is not a promise, force keyword behaves like
eval. When a promise has been forced, further call to force will not
change the evaluation result.
Syntax
force "object"
Example
trans y 3 const l ((lambda (x) (+ x y)) 1) assert 4 (force l)
trans y 0 assert 4 (force l)
if
The if reserved keyword executes a form based on the evaluation of a
boolean expression. In its first representation, if executes a form if
the condition is evaluated to true. An alternate form can be specified
and is executed if the boolean expression evaluates to false. It is an
error to use a conditional form which does not evaluate to a boolean
object.
Syntax
if "condition" "true form" if "condition" "true form" "else
form"
Example
const max (x y) (if (> x y) x y)
lambda
The lambda reserved keyword creates a new closure object with
eventually a set of arguments and a set of closed variables. In its
first form, the closure is declared with a set of arguments or nil to
indicate no argument. In its second form, the closure is declared with
a set of arguments and a set of closed variables. The closed variables
are evaluated at the construction of the closure and become part of the
closure object. When the closure is called, a new nameset is created
and linked with the parent nameset. The set of calling arguments are
bounded in that nameset with the formal argument list to become the
actual arguments. The set of closed variables is linked at runtime to
the closure nameset. A lambda or gamma expression can have its argument
declared as const argument.
Syntax
lambda "nil" "body" lambda "argument list" "body" lambda
"argument list" "closed variables list" "body"
Example
const no-args (lambda nil (+ 1 1)) const add (lambda ((const
x) (const y)) (+ x y)) const closed (lambda (x) (y) (+ x y))
launch
The launch reserved keyword creates a new thread by executing the form
argument in a normal thread. The created thread is added in the normal
thread list by creating a clone of the interpreter and starting
immediately the execution of the form with the cloned interpreter. The
command returns the thread object in the calling thread. When the
thread terminates, the thread object holds the result of the last
executed form. The main thread is suspended until all normal threads
have completed their execution.
Syntax
launch "form"
Example
launch (println "hello world")
loop
The loop reserved keyword executes a loop based on an initial
condition, an exit condition and a step form. The initial condition is
only executed one time. The exit condition is tested at each loop
iteration. The loop reserved keyword creates its own nameset since the
initial condition generally binds symbol locally for the loop.
Syntax
loop "init form" "exit form" "step" "form"
Example
loop (trans i 0) (< i 10) (i:++) (println i)
nameset
The nameset reserved keyword creates a new nameset. With no argument, a
new nameset is created and no parent is binded to this nameset. With
one argument, the argument must evaluate to a nameset and that nameset
is used as the parent one. If a nameset has to be created with the
global nameset as the parent, the symbol ... can be used to reference
the top level nameset. The symbol . references the current nameset. The
symbol .. references the parent nameset of the current nameset.
Syntax
nameset nameset "parent nameset"
Example
const local-nameset-not-bound (nameset) const local-nameset-
bounded (nameset ...) const ...:global-nameset (nameset)
println
The println reserved keyword prints on the interpreter output stream a
set of arguments. Each arguments have to be a literal which is
converted to a string. When all arguments have been printed a new line
character is printed. The print reserved keyword behaves like println
excepts that a new line character is not printed at the end of the
arguments.
Syntax
println println "nil" println "literal list"
Example
println println "hello millennium" ’ ’ 2000
protect
The protect reserved keyword take a single argument and returns it
without evaluation. Protect is mainly use to get a symbol or form
object.
Syntax
protect "object"
Example
const cons (protect (+ 1 2))
return
The return reserved keyword causes the current expression to stop its
evaluation and returns the argument or nil. The return keyword is
primarily used in lambda or gamma expressions. If used in a top level
block, the block execution is stopped and the control is transferred to
the top level.
Syntax
return "object"
Example
return (+ 1 2)
sync
The sync reserved keyword is a form synchronizer. Within a multi-
threaded environment, the AFNIX engine guarantees that only one
thread will execute the form. The other threads are suspended until the
form has been completed.
Syntax
sync "form"
Example
const print-message (code mesg) (
sync {
errorln "error : " code
errorln "message: " mesg
} )
switch
The switch reserved keyword is a form selector. The first argument is
the object to switch. The second argument is a list of forms with an
object matcher and an execution form. The else reserved keyword can be
used as default matcher.
Syntax
switch "selector" "list of conditions"
Example
const get-primary-color (color value) (
switch color (
("red" (return (value:substr 0 2))
("green" (return (value:substr 2 4))
("blue" (return (value:substr 4 6))
)
)
throw
The throw reserved keyword throws an exception. Without argument, an
exception of type user-exception is thrown. With one argument, the
exception id is set. With two arguments, the exception id and exception
reason are set. With three arguments, the exception id, exception
reason and exception object are set. An exception object represented by
the symbol what can also be thrown. This is the method used to re-throw
an exception.
Syntax
throw throw what throw "id" throw "id" "reason" throw "id"
"reason" "object"
Example
throw throw "type-error" throw "type-error" "invalid argument"
trans
The trans reserved keyword creates or sets a symbol with an object.
trans searches in the current nameset only. If a symbol is found, it is
set with the object. If the symbol is not found, it is created in the
current nameset. The trans keyword can also be used with qualified
names. With 3 or 4 arguments, trans creates automatically a lambda
expression.
Syntax
trans symbol "object" trans symbol "argument" "body" trans
symbol "argument" "closed variables" "body"
Example
trans a 1 trans fact (n) (if (< n 1) 1 (* n (fact (- n 1))))
try
The try reserved keyword catch an exception in the current execution
nameset. The first argument is a form to execute. The optional second
argument is the exception handler to be called in case of exception. If
there is no exception handler, all exceptions are caught. The result of
execution is either the result of the form execution, or the exception
object in case of exception, or nil if the exception is a native one.
If there is an exception handler, the handler is executed with a new
nameset and the special symbol what is bound to the exception. If the
exception is nil, the symbol what is undefined.
Syntax
try "form" try "form" " exception handler"
Example
try (+ 1 2) try (throw) try (throw "hello") try (throw "hello"
"world") try (throw "hello" "world" "folks")
while
The while reserved keyword is used to build loop with backward
condition. The loop construct accepts either 2 or 3 arguments. With 2
argument, the first argument is the loop condition and the second
argument is the loop body that must evaluate to a boolean. With 3
arguments, the first argument is the initial condition that is executed
only once.
Syntax
while "condition" "body" while "initial" "condition" "body"
Example
const gcd (u v) {
while (!= v 0) {
trans r (u:mod v)
u:= v
v:= r
}
eval u }
RESERVED OBJECTS
This chapter is a reference of the AFNIX reserved objects with their
respective builtin methods. The AFNIX reserved objects are those
objects defined in the global interpreter nameset and bind as reserved
names. All literal have a string representation. The to-string method
is always available for these reserved objects. A literal object has a
default constructor. Generally, it can also be constructed by a same
type object or by a string object.
Literal
The Literal object is a base object for all literal object. The sole
purpose of a literal object is to provide to methods named to-string
and to-literal that return a string representation of the literal
object.
Predicate
literal-p
Inheritance
Serial
Methods
to-string -> String (none)
The to-string method returns a string representation of the
literal. The string is expected to represent at best the
literal.
to-literal -> String (none)
The to-literal method returns a string representation of the
literal. The string differs from the to-string method in the
sense that the string is a literal representation. For example
the literal representation of a string is the quoted string.
Nameable
The Nameable object is a base object that support name definition. The
sole purpose of a literal object is to provide to method named get-name
that returns the object name.
Predicate
nameable-p
Inheritance
Object
Methods
get-name -> String (none)
The get-name method returns the associated object name. The
object name defined here is a name that the class wishes to
associate with the object. For example, the InputFile is a
nameable class and the name is the file name.
Item
The Item reserved object is an enumeration item. The item is bound to
an enumeration object. An item object is created during the evaluation
of an enumeration object. An enumeration item cannot be constructed
directly.
Predicate
item-p
Inheritance
Literal
Operators
== -> Boolean (Boolean)
The == operator returns true if the calling object is equal to
the boolean argument.
!= -> Boolean (Boolean)
The == operator returns true if the calling object is not equal
to the boolean argument.
Methods
get-enum -> Enum (none)
The get-enum method returns the enumeration object bound to the
item. The item must be a dynamic item or an exception is thrown.
Boolean
The Boolean reserved object implements the behavior of a native boolean
type. Two builtin symbols, namely true and false are used to represent
the value of a boolean instance. The Boolean type is primarily used for
test expression.
Predicate
boolean-p
Inheritance
Literal
Constructors
Boolean (none)
The Boolean constructor create a boolean object those default
value is false.
Boolean (Boolean)
The Boolean constructor create a boolean object with the boolean
object argument.
Boolean (String)
The Boolean constructor create a boolean object with the string
object argument. The string "true" denotes the true value while
the string "false" denotes the false value.
Operators
== -> Boolean (Boolean)
The == operator returns true if the calling object is equal to
the boolean argument.
!= -> Boolean (Boolean)
The == operator returns true if the calling object is not equal
to the boolean argument.
Integer
The Integer reserved object implements the behavior of a native 64 bits
signed integer type. Standard decimal notation is used to construct
integer object from a literal. The integer object can also be
constructed from a string. Standard operators are provided for this
class.
Predicate
integer-p
Inheritance
Literal
Constructors
Integer (none)
The Integer constructor create an integer object those default
value is 0.
Integer (Real)
The Integer constructor create an integer object with the real
object argument those value is truncated to an integer value.
Integer (Integer)
The Integer constructor create an integer object with the
integer object argument.
Integer (Character)
The Integer constructor create an integer object with the
character object argument. The character encoding value is used
as the integer value.
Operators
== -> Boolean (Integer|Real)
The == operator returns true if the calling object is equal to
the integer or real argument.
!= -> Boolean (Integer|Real)
The != operator returns true if the calling object is not equal
to the integer or real argument.
+ -> Integer (Integer|Real)
The + operator returns the sum of the calling integer with an
integer or a real object.
- -> Integer (Integer|Real)
The - operator returns the subtraction of the calling integer
with an integer or a real object.
* -> Integer (Integer|Real)
The * operator returns the multiplication of the calling integer
with an integer or a real object.
/ -> Integer (Integer|Real)
The / operator returns the division of the calling integer with
an integer or a real object.
< -> Boolean (Integer|Real)
The < operator returns true if the calling integer is less than
the integer or real object.
<= -> Boolean (Integer|Real)
The <= operator returns true if the calling integer is less
equal than the integer or real object.
> -> Boolean (Integer|Real)
The > operator returns true if the calling integer is greater
than the integer or real object.
>= -> Boolean (Integer|Real)
The >= operator returns true if the calling integer is greater
equal than the integer or real object.
++ -> Integer (Integer|Real)
The ++ operator increments the calling integer by 1.
-- -> Integer (Integer|Real)
The -- operator decrements the calling integer by 1.
+= -> Integer (Integer|Real)
The += operator add and assign the calling integer with an
integer or real argument object.
-= -> Integer (Integer|Real)
The -= operator subtracts and assign the calling integer with an
integer or real argument object.
*= -> Integer (Integer|Real)
The *= operator multiply and assign the calling integer with an
integer or real argument object.
/= -> Integer (Integer|Real)
The += operator divide and assign the calling integer with an
integer or real argument object.
Methods
or -> Integer (Integer)
The or method returns the binary or between the integer and the
integer argument.
abs -> Integer (none)
The abs method returns the absolute value of the calling integer
instance.
not -> Integer (none)
The not method returns the binary negation of the calling
integer instance.
shl -> Integer (Integer)
The shl method returns a new integer corresponding to the
calling integer instance shifted left by the integer argument.
shr -> Integer (Integer)
The shr method returns a new integer corresponding to the
calling integer instance shifted right by the integer argument.
and -> Integer (Integer)
The and method returns a new integer corresponding to the binary
and between the calling integer instance and the integer
argument.
xor -> Integer (Integer)
The xor method returns a new integer corresponding to the binary
xor between the calling integer instance and the integer
argument.
mod -> Integer (Integer)
The mod method returns the modulo between the integer instance
and the integer argument. A type-error exception is raised if
the argument is not an argument.
odd-p -> Boolean (none)
The odd-p method returns true if the integer instance is odd,
false otherwise.
even-p -> Boolean (none)
The even-p method returns true if the integer instance is even,
false otherwise.
zero-p -> Boolean (none)
The zero-p method returns true if the integer instance is null,
false otherwise.
Relatif
The Relatif reserved object implements the behavior of an unlimited
signed integer type. Standard decimal notation followed by the ’r’ or
’R’ character is used to construct relatif object from a literal. The
relatif object can also be constructed from a string. This class is
similar to the Integer class.
Predicate
relatif-p
Inheritance
Literal
Constructors
Relatif (none)
The Relatif constructor create a relatif object those default
value is 0.
Relatif (Real)
The Relatif constructor create an relatif object with the real
object argument those value is truncated to an integer value.
Relatif (Relatif)
The Relatif constructor create an relatif object with the
relatif object argument.
Relatif (Integer)
The Relatif constructor create an relatif object with the
integer object argument.
Relatif (Character)
The Relatif constructor create an relatif object with the
character object argument. The character encoding value is used
as the relatif value.
Operators
== -> Boolean (Relatif|Integer)
The == operator returns true if the calling object is equal to
the relatif or integer argument.
!= -> Boolean (Relatif|Integer)
The == operator returns true if the calling object is not equal
to the relatif or integer argument.
+ -> Relatif (Relatif|Integer)
The + operator returns the sum of the calling relatif with an
relatif or a integer object.
- -> Relatif (Relatif|Integer)
The - operator returns the subtraction of the calling relatif
with an relatif or a integer object.
* -> Relatif (Relatif|Integer)
The * operator returns the multiplication of the calling relatif
with an relatif or a integer object.
/ -> Relatif (Relatif|Integer)
The / operator returns the division of the calling relatif with
an relatif or a integer object.
< -> Boolean (Relatif|Integer)
The < operator returns true if the calling relatif is less than
the relatif or integer object.
<= -> Boolean (Relatif|Integer)
The <= operator returns true if the calling relatif is less
equal than the relatif or integer object.
> -> Boolean (Relatif|Integer)
The > operator returns true if the calling relatif is greater
than the relatif or integer object.
>= -> Boolean (Relatif|Integer)
The >= operator returns true if the calling relatif is greater
equal than the relatif or integer object.
++ -> Relatif (Relatif|Integer)
The ++ operator increments the calling relatif by 1.
-- -> Relatif (Relatif|Integer)
The -- operator decrements the calling relatif by 1.
+= -> Relatif (Relatif|Integer)
The += operator add and assign the calling relatif with an
relatif or integer argument object.
-= -> Relatif (Relatif|Integer)
The -= operator subtracts and assign the calling relatif with an
relatif or integer argument object.
*= -> Relatif (Relatif|Integer)
The *= operator multiply and assign the calling relatif with an
relatif or integer argument object.
/= -> Relatif (Relatif|Integer)
The += operator divide and assign the calling relatif with an
relatif or integer argument object.
Methods
or -> Relatif (Relatif)
The or method returns the binary or between the relatif and the
relatif argument.
abs -> Relatif (none)
The abs method returns the absolute value of the calling relatif
instance.
not -> Relatif (none)
The not method returns the binary negation of the calling
relatif instance.
shl -> Relatif (Integer)
The shl method returns a new relatif corresponding to the
calling relatif instance shifted left by the integer argument.
shr -> Relatif (Integer)
The shr method returns a new relatif corresponding to the
calling relatif instance shifted right by the integer argument.
and -> Relatif (Relatif)
The and method returns a new relatif corresponding to the binary
and between the calling relatif instance and the relatif
argument.
xor -> Relatif (Relatif)
The xor method returns a new relatif corresponding to the binary
xor between the calling relatif instance and the relatif
argument.
mod -> Relatif (Relatif|Integer)
The mod method returns the modulo between the relatif instance
and the relatif or integer argument. A type-error exception is
raised if the argument is invalid.
odd-p -> Boolean (none)
The odd-p method returns true if the relatif instance is odd,
false otherwise.
even-p -> Boolean (none)
The even-p method returns true if the relatif instance is even,
false otherwise.
zero-p -> Boolean (none)
The zero-p method returns true if the relatif instance is null,
false otherwise.
Real
The Real reserved object implements the behavior of a double floating
point number type. Standard decimal dot notation or scientific notation
is used to construct real object from a literal. The real object can
also be constructed from an integer, a character or a string.
Predicate
real-p
Inheritance
Literal
Constructors
Real (none)
The Real constructor create an real object those default value
is 0.0.
Real (Real)
The Real constructor create an real object with the real object
argument.
Real (Integer)
The Real constructor create an real object with the integer
object argument.
Real (Character)
The Real constructor create an real object with the character
object argument. The character encoding value is used as the
integer value.
Operators
== -> Boolean (Integer|Real)
The == operator returns true if the calling object is equal to
the integer or real argument.
!= -> Boolean (Integer|Real)
The == operator returns true if the calling object is not equal
to the integer or real argument.
+ -> Real (Integer|Real)
The + operator returns the sum of the calling real with an
integer or a real object.
- -> Real (Integer|Real)
The - operator returns the subtraction of the calling real with
an integer or a real object.
* -> Real (Integer|Real)
The * operator returns the multiplication of the calling real
with an integer or a real object.
/ -> Real (Integer|Real)
The / operator returns the division of the calling real with an
integer or a real object.
< -> Boolean (Integer|Real)
The < operator returns true if the calling real is less than the
integer or real object.
<= -> Boolean (Integer|Real)
The <= operator returns true if the calling real is less equal
than the integer or real object.
> -> Boolean (Integer|Real)
The > operator returns true if the calling real is greater than
the integer or real object.
>= -> Boolean (Integer|Real)
The >= operator returns true if the calling real is greater
equal than the integer or real object.
++ -> Real (Integer|Real)
The ++ operator increments the calling real by 1.
-- -> Real (Integer|Real)
The -- operator decrements the calling real by 1.
+= -> Real (Integer|Real)
The += operator add and assign the calling real with an integer
or real argument object.
-= -> Real (Integer|Real)
The -= operator subtracts and assign the calling real with an
integer or real argument object.
*= -> Real (Integer|Real)
The *= operator multiply and assign the calling real with an
integer or real argument object.
/= -> Real (Integer|Real)
The += operator divide and assign the calling real with an
integer or real argument object.
Methods
nan-p -> Boolean (none)
The nan-p method returns true if the calling real number
instance is not-a-number (nan).
ceiling -> Real (none)
The ceiling method returns the ceiling of the calling real
number instance.
floor -> Real (none)
The floor method returns the floor of the calling real number
instance.
abs -> Real (none)
The abs method returns the absolute value of the calling real
number instance.
pow -> Real (Real|Integer)
The pow method returns the power of the calling real with the
argument. The exponent argument can be either an integer or a
real number.
sqrt -> Real (none)
The sqrt method returns the square root of the calling real
number instance.
log -> Real (none)
The log method returns the natural logarithm of the calling real
number instance.
exp -> Real (none)
The exp method returns the exponential of the calling real
number instance.
sin -> Real (none)
The sin method returns the sine of the calling floating point
instance. The angle is expressed in radian.
cos -> Real (none)
The cos method returns the cosine of the calling floating point
instance. The angle is expressed in radian.
tan -> Real (none)
The tan method returns the tangent of the calling floating point
instance. The angle is expressed in radian.
asin -> Real (none)
The asin method returns the arc sine of the calling floating
point instance. The result is in radian.
acos -> Real (none)
The acos method returns the arc cosine of the calling floating
point instance. The result is in radian.
atan -> Real (none)
The atan method returns the arc tangent of the calling floating
point instance. The result is in radian.
sinh -> Real (none)
The sinh method returns the hyperbolic sine of the calling real
number instance.
cosh -> Real (none)
The cosh method returns the hyperbolic cosine of the calling
real number instance.
tanh -> Real (none)
The atan method returns the hyperbolic tangent of the calling
real number instance.
asinh -> Real (none)
The asinh method returns the hyperbolic arc sine of the calling
real number instance.
acosh -> Real (none)
The acosh method returns the hyperbolic arc cosine of the
calling real number instance.
atanh -> Real (none)
The atanh method returns the hyperbolic arc tangent of the
calling real number instance.
zero-p -> Boolean (none)
The zero-p method returns true if the calling real instance is
null, false otherwise.
format -> String (Integer)
The format method format the calling real instance with n digits
after the decimal point. The number of digits is the format
argument.
Character
The Character reserved object implements the behavior of an Unicode
character type. A character can be constructed from a literal quoted
notation, with a string or with the U+ hexadecimal notation. The
character class is designed to handle the full range of the Unicode
character space by using an internal 32 bit quad representation with 31
bit valid. The Character class conform also with the ISO 10646
character representation.
Predicate
character-p
Inheritance
Literal
Constructors
Character (none)
The Character constructor create a character object those
default value is the null character.
Character (String)
The Character constructor create a character object with the
string object argument.
Character (Integer)
The Character constructor create a character object with the
integer object argument.
Character (Character)
The Character constructor create a character object with the
character object argument.
Operators
== -> Boolean (Character)
The == operator returns true if the calling object is equal to
the character argument.
!= -> Boolean (Character)
The != operator returns true if the calling object is not equal
to the character argument.
< -> Boolean (Character)
The < operator returns true if the calling character is less
than the character object.
<= -> Boolean (Character)
The <= operator returns true if the calling character is less
equal than the character object.
> -> Boolean (Character)
The > operator returns true if the calling character is greater
than the character object.
>= -> Boolean (Character)
The >= operator returns true if the calling character is greater
equal than the character object.
++ -> Character (Character)
The ++ operator increments the calling character by the next one
in lexicographic order.
-- -> Character (Character)
The -- operator decrements the calling character by the previous
one in lexicographic order.
+= -> Character (Integer)
The += operator add the integer argument to the calling
character.
-= -> Character (Integer)
The -= operator subtracts the integer argument to the calling
character.
Methods
letter-p -> Boolean (none)
The letter-p method returns true if character is a letter
character, false otherwise.
digit-p -> Boolean (none)
The digit-p method returns true if character is a digit
character, false otherwise.
alpha-p -> Boolean (none)
The alpha-p method returns true if character is an alphanumeric
character, false otherwise.
blank-p -> Boolean (none)
The blank-p method returns true if character is a blank or tab
character, false otherwise.
eol-p -> Boolean (none)
The eol-p method returns true if character is an end of line
character, false otherwise.
eof-p -> Boolean (none)
The eof-p method returns true if character is an end of file
character, false otherwise.
nil-p -> Boolean (none)
The nil-p method returns true if character is the nil character,
false otherwise.
to-integer -> Integer (none)
The to-integer method returns an integer representation of the
character.
Byte
The Byte reserved object implements the behavior of an 8 bit character
type. A byte can be constructed from a integer or from another byte.
The Byte class is similar to the Character class but is not a literal
object because it does not have a literal representation. Most of the
time, a byte object is created by another object like a stream, when
using the read method for example.
Predicate
byte-p
Inheritance
Serial
Constructors
Byte (none)
The Byte constructor create a byte object those default value is
the null byte.
Byte (Integer)
The Byte constructor create a byte object with the integer
object argument. The integer value must be in the range of 0x00
to 0xFF.
Byte (Byte)
The Byte constructor create a byte object with the byte object
argument.
Operators
== -> Boolean (Byte)
The == operator returns true if the calling object is equal to
the byte argument.
!= -> Boolean (Byte)
The != operator returns true if the calling object is not equal
to the byte argument.
< -> Boolean (Byte)
The < operator returns true if the calling byte is less than the
byte object.
<= -> Boolean (Byte)
The <= operator returns true if the calling byte is less equal
than the byte object.
> -> Boolean (Byte)
The > operator returns true if the calling byte is greater than
the byte object.
>= -> Boolean (Byte)
The >= operator returns true if the calling byte is greater
equal than the byte object.
++ -> Byte (Byte)
The ++ operator increments the calling byte by one.
-- -> Byte (Byte)
The -- operator decrements the calling byte by one.
+= -> Byte (Integer)
The += operator adds the integer argument to the calling byte.
-= -> Byte (Integer)
The -= operator subtracts the integer argument to the calling
byte.
Methods
eof-p -> Boolean (none)
The eof-p method returns true if the byte is an end of file
byte, false otherwise.
nil-p -> Boolean (none)
The nil-p method returns true if the byte is the nil byte, false
otherwise.
to-integer -> Integer (none)
The to-integer method returns an integer representation of the
byte.
to-char -> Character (none)
The to-char method returns a character representing the byte.
String
The String reserved object implements the behavior of an internal
character array. The double quote notation is the literal notation for
a string. A string can also be constructed from the standard AFNIX
objects. Strings can be compared, transformed or extracted with the
help of the methods listed below. Internally, the string is represented
as an array of Unicode characters.
Predicate
string-p
Inheritance
Literal
Constructors
String (none)
The String constructor create a string object those default
value is the null string.
String (Literal)
The String constructor create a string object with the literal
object argument.
Operators
== -> Boolean (String)
The == operator returns true if the calling object is equal to
the string argument.
!= -> Boolean (String)
The != operator returns true if the calling object is not equal
to the string argument.
< -> Boolean (String)
The < operator returns true if the calling string is less than
the string argument.
<= -> Boolean (String)
The <= operator returns true if the calling string is less equal
than the string argument.
> -> Boolean (String)
The > operator returns true if the calling string is greater
than the string argument.
>= -> Boolean (String)
The >= operator returns true if the calling string is greater
equal than the string argument.
+ -> String (String)
The + operator returns the sum of the calling string with an
string object.
+= -> String (String)
The += operator add and assign the calling string with the
string argument.
Methods
length -> Integer (none)
The length method returns the length of the string.
first -> Character (none)
The first method returns the first character in the string.
last -> Character (none)
The last method returns the last character in the string.
strip-left -> String (none|String)
The strip-left method removes the leading blanks and tabs and
returns a new string. With a string argument, each character in
the string is taken as a character separator that should be
stripped.
strip-right -> String (none|String)
The strip-right method removes the trailing blanks and tabs and
returns a new string.With a string argument, each character in
the string is taken as a character separator that should be
stripped.
strip -> String (none|String)
The strip method removes the leading, trailing blanks and tabs
and returns a new string. With a string argument, each character
in the string is taken as a character separator that should be
stripped.
split -> Vector (none|String)
The split method split the string into one or more string
according to break sequence. If no argument is passed to the
call, the break sequence is assumed to be a blank, tab and eol
characters.
extract -> Vector (Character)
The extract method extracts one or more string which are
enclosed by a control character passed as an argument. The
method returns a vector of strings.
to-upper -> String (none)
The to-upper converts all string characters to upper case and
returns a new string.
to-lower -> String (none)
The to-lower method converts all string characters to lower case
and returns a new string.
get -> Character (Integer)
The get method returns a the string character at the position
given by the argument. If the index is invalid, an exception is
raised.
sub-left -> String (Integer)
The sub-left method returns the left sub string of the calling
string up-to the argument index. If the index is out of range,
the string is returned.
sub-right -> String (Integer)
The sub-right method returns the right sub string of the calling
string starting at the argument index. If the index is out of
range, the string is returned.
fill-left -> String (Character Integer)
The fill-left method returns a string filled on the left with
the character argument. The second argument is the desired
length of the resulting string. If the calling is too long, the
string is returned.
fill-right -> String (Character Integer)
The fill-left method returns a string filled on the right with
the character argument. The second argument is the desired
length of the resulting string. If the calling is too long, the
string is returned.
substr -> String (Integer Integer)
The substr method returns a string starting at the first
argument index and ending at the second argument index. If the
indexes are out of range, an exception is raised.
Regex
The Regex object is a special object which is automatically
instantiated by the interpreter when using the delimiter character [
and ]. The regex syntax involves the use of standard characters, meta
characters and control characters. Additionally, a string can be use to
specify a series of characters. In its first form, the [ and ]
characters are used as syntax delimiters. The lexical analyzer
automatically recognizes this token as a regex and built the equivalent
Regex object. The second form is the explicit construction of the Regex
object. Note also that the [ and ] characters are also used as regex
block delimiters. Any character, except the one used as operators can
be used in a regex. The $ character is used as a meta-character -- or
control character -- to represent a particular set of characters. For
example, [hello world] is a regex which match only the "hello world"
string. The [$d+] regex matches one or more digits. The following
control characters are builtin in the regex engine.
Character Description
$a matches any letter or digit
$b matches any blank characters
$d matches any digit
$e matches eol, cr and eof
$l matches any lower case letter
$n matches eol or cr
$s matches any letter
$u matches any upper case letter
$v matches any valid afnix constituent
$w matches any word constituent
$x matches any hexadecimal characters
The uppercase version is the complement of the corresponding lowercase
character set. A character which follows a $ character and that is not
a meta character is treated as a normal character. For example $[ is
the [ character. A quoted string can be used to define character
matching which could otherwise be interpreted as control characters or
operator. A quoted string also interprets standard escaped sequences
but not meta characters.
Character Description
$A any character except letter or digit
$B any character except blank characters
$D any character except digit
$E any character except eol, cr and eof
$L any character except lower case letter
$N any character except eol or cr
$S any character except letter
$U any character except upper case letter
$V any character except afnix constituent
$W any character except word constituent
$X any character except hex characters
A character set is defined with the < and > characters. Any enclosed
character defines a character set. Note that meta characters are also
interpreted inside a character set. For example, <$d+-> represents any
digit or a plus or minus. If the first character is the ^ character in
the character set, the character set is complemented with regards to
its definition. The following unary operators can be used with single
character, control characters and sub-expressions.
Operator Description
* match 0 or more times
+ match 1 or more times
? match 0 or 1 time
| alternation
Alternation is an operator which work with a secondary expression. Care
should be taken when writing the right sub-expression. For example the
following regex [$d|hello] is equivalent to [[$d|h]ello]. In other
word, the minimal first sub-expression is used when compiling the
regex.
Predicate
regex-p
Inheritance
Literal
Constructors
Regex (none)
The Regex constructor create a regex object those default value
is the null regex.
Regex (String)
The Regex constructor create a regex object with the string
object argument. The string argument is the regex specification.
Operators
== -> Boolean (String)
The == operator returns true if the argument is matched by the
regex.
!= -> Boolean (String)
The != operator returns true if the argument is not matched by
the regex.
< -> Boolean (String)
The < operator returns true if the argument is partially matched
by the regex.
Methods
length -> Integer (none)
The length method returns the length of the group vector when a
regex match has been successful.
get -> String (Integer)
The get method returns by index the group sub-string when a
regex match has been successful.
match -> String (String)
The match method returns the first matching string of the
argument string.
replace -> String (String String)
The replace method returns a string constructed by replacing all
matching sub-string -- from the first argument -- with the
second argument string.
CONTAINER OBJECTS
This chapter is a reference of the AFNIX reserved container objects
with their respective builtin methods. Some of these container objects
are iterable objects. When an object is iterable, an iterator
constructor constructor is provided. The iterable-p predicate returns
true if the container is an iterable object. The get-iterator method
can be used to construct an object iterator. For a given iterator, the
predicates end-p and valid-p can be used to check for the end or a
valid iterator position. The next method move the iterator to its next
position. The prev method move the iterator -- if possible -- to its
previous position. The get-object method returns the object at the
current iterator position.
Cons
A Cons instance or simply a cons cell is a simple element used to build
linked list. The cons cell holds an object and a pointer to the next
cons cell. The cons cell object is called car and the next cons cell is
called the cdr. Historically, car means Current Address Register and
cdr means Current Data Register. We retain in AFNIX this notation for
the sake of tradition.
Predicate
cons-p
Inheritance
SerialIterable
Constructors
Cons (none)
The Cons constructor create a default cons cell with the car and
cdr set to nil.
Cons (Objects...)
The Cons constructor create a list of cons cells with the object
arguments. Each argument object is assigned to the car of the
cons cell while the cdr is used to link the cell together.
Methods
get-car -> Object (none)
The get-car method returns the car of the calling cons cell.
get-cdr -> Cons (none)
The get-cdr method returns the cdr of the calling cons cell.
get-cadr -> Object (none)
The get-cadr method returns the car of the cdr of the calling
cons cell or nil if the cdr is nil.
get-caddr -> Object (none)
The get-caddr method returns the car of the cdr of the cdr of
the calling cons cell or nil if the cdr is nil.
get-cadddr -> Object (none)
The get-cadddr method returns the car of the cdr of the cdr of
the cdr of the calling cons cell or nil if the cdr is nil.
length -> Integer (none)
The length method returns the length of the cons cell. The
minimum length returned is always 1.
nil-p -> Boolean (none)
The nil-p predicate returns true if the car of the calling cons
cell is nil, false otherwise.
block-p -> Boolean (none)
The block-p predicate returns true if the cons cell is of type
block, false otherwise.
get-iterator -> Iterator (none)
The get-iterator returns a forward iterator for this cons cell.
No backward methods are supported for this object.
set-car -> Object (Object)
The set-car set the car of the calling cons cell. The object
argument is returned by the method.
set-cdr -> Cons (Cons)
The set-cdr set the cdr of the calling cons cell. The cons cell
argument is returned by the method.
append -> Object (Object)
The append method appends an object at the end of the cons cell
chain by creating a new cons cell and linking it with the last
cdr. The object argument is returned by this method.
link -> Object (Object)
The link method is similar to the append except that a new cons
cell is not created if the car is nil. Instead the car is set
with the calling object. The object argument is returned by this
method.
get -> Object (Integer)
The get method returns the car of the cons cell chain at a
certain position specified by the integer index argument.
Enum
The Enum builtin object is an enumeration object. The enumeration is
constructed with the reserved keyword enum and a list of literals or by
string name with a constructor.
Predicate
enum-p
Inheritance
Object
Constructors
Enum (none)
The Enum constructor create an empty enumeration.
Enum (String...)
The Enum constructor create an enumeration from a list of string
arguments.
Methods
reset -> none (none)
The reset method resets the enumeration and makes it empty.
length -> Integer (none)
The length method returns the number of items in the
enumeration.
exists-p -> Boolean (String)
The exists-p predicate returns true if the name argument exists
as an item. The name argument must be a lexical name or an
exception is thrown.
add -> none (String)
The add method adds a new item to the enumeration by name. This
method returns nil.
get -> String (Integer)
The get method returns an item string representation by index.
The integer argument is the item index.
List
The List builtin object provides the facility of a double-link list.
The List object is another example of iterable object. The List object
provides support for forward and backward iteration.
Predicate
list-p
Inheritance
Iterable
Constructors
List (none)
The List constructor create an empty list.
List (Object...)
The List constructor create a list from a list of object
arguments.
Methods
length -> Integer (none)
The length method returns the length of the list. The minimum
length is 0 for an empty list.
get-iterator -> Iterator (none)
The get-iterator returns a forward/backward iterator for this
list.
append -> Object (Object)
The append method appends an object at the end of the list. The
object argument is returned by this method.
insert -> Object (Object)
The insert method inserts an object at the beginning of the
list. The object argument is returned by this method.
get -> Object (Integer)
The get method returns the object in the list at a certain
position specified by the integer index argument.
Vector
The Vector builtin object provides the facility of an index array of
objects. The Vector object is another example of iterable object. The
Vector object provides support for forward and backward iteration.
Predicate
vector-p
Inheritance
SerialIterable
Constructors
Vector (none)
The Vector constructor create an empty vector.
Vector (Object...)
The Vector constructor create a vector from a list of object
arguments.
Methods
reset -> none (none)
The reset method reset the vector. When the method is complete,
the vector is empty.
length -> Integer (none)
The length method returns the length of the vector. The minimum
length is 0 for an empty vector.
empty-p -> Boolean (none)
The empty-p predicate returns true if the vector is empty.
get -> Object (Integer)
The get method returns the object in the vector at a certain
position specified by the integer index argument.
set -> Object (Integer Object)
The set method set a vector position with an object. The first
argument is the vector index. The second argument is the object
to set. The method returns the object to set.
first -> Object (none)
The first method returns the first element in the vector.
last -> Object (none)
The first method returns the last element in the vector.
back-track -> Object (none)
The back-track method removes the last element in the vector and
returns it.
pop -> Object (none)
The pop method removes the first element in the vector and
returns it.
find -> Integer (Object)
The find method try to find an object in the vector. If the
object is found, the vector index is returned as an Integer
object, else nilp is returned.
append -> Object (Object|Object Integer)
The append method appends an object at the end of the vector or
at a certain index. In the first form, the object argument is
added at the end of the vector. In the second form, the object
argument is inserted in the vector at the specified index. In
both cases, the object argument is returned by this method.
exists-p -> Boolean (Object)
The exists-p method returns true if the object argument exists
in the vector. This method is useful to make sure that only one
occurrence of an object is added to a vector.
clean -> none (Integer)
The clean method removes an object from the vector by index and
repack the vector.
remove -> none (Object)
The remove method removes an object from the vector and repack
the vector. If duplicate exists in the file, only one is
removed.
get-iterator -> Iterator (none)
The get-iterator returns a forward/backward iterator for this
vector.
HashTable
The HashTable builtin object is a container object which maps an object
with a name. The hash table is dynamic and get resized automatically
when needed. The lookup method throw an exception if the name is not
found. The get method returns nilp if the object is not found.
Predicate
hashtable-p
Inheritance
Object
Constructors
HashTable (none)
The HashTable constructor create an empty table.
HashTable (Integer)
The HashTable constructor create a table with a specific size.
Methods
add -> none (String Object)
The add method adds a new object in the table by key. The first
argument is the key used to associate the object in the table.
The second argument is the object to add.
length -> Object (none)
The length returns the number of objects in the table.
empty-p -> Boolean (none)
The empty-p predicate returns true if the table is empty.
reset -> none (none)
The reset method resets the table so that it becomes empty.
get -> Object (String)
The get method returns the object associated with a key. If the
key is not found, nil is returned.
lookup -> Object (String)
The lookup method returns the object associated with a key. If
the key is not found, an exception is raised.
get-key -> String (Integer)
The get-key method returns the key associated with an entry in
the table by index. If the index is out of range, an exception
is raised.
get-object -> Object (Integer)
The get-object method returns the object associated with an
entry in the table by index. If the index is out of range, an
exception is raised.
Set
The Set builtin object provides the facility of a uniform set of
objects. The Set object is another example of iterable object. The Set
object provides support for forward and backward iteration.
Predicate
set-p
Inheritance
SerialIterable
Constructors
Set (none)
The Set constructor create an empty set.
Set (Object...)
The Set constructor create a set from a list of object
arguments.
Methods
reset -> none (none)
The reset method reset the set. When the method is complete, the
set is empty.
length -> Integer (none)
The length method returns the number of elements in the set. The
minimum length is 0 for an empty set.
add -> Object (Object)
The append method appends an object in the set. If the object
already exists in the set, it is not added twice. This is the
main difference between a set and a vector. The object argument
is returned by this method.
get -> Object (Integer)
The get method return object by index.
exists -> Boolean (Object)
The exists method returns true if the object argument exists in
the set.
merge -> none (Set)
The merge method merges the set argument into the calling set.
If an element already exists in the set, it is not added.
remix -> none (Integer)
The remix method mixes the set by randomly swapping all the
elements. This method is useful when the set has been filled
with a certain order by the access must be done randomly.
remove -> Boolean (Object)
The remove method removes the object argument from the set. if
the object is removed, the method returns true. If the object is
not in the set, the method returns false.
get-random-subset -> Set (Integer)
The get-random-subset method returns a subset those cardinal is
at least the size argument with a set of randomly chosen
elements. The result set might have a cardinal less than the
requested size if the calling set cardinal is less than the
requested size.
get-iterator -> Iterator (none)
The get-iterator returns an iterator for this set. The iterator
supports forward and backward iteration.
Queue
The Queue builtin object is a container used to queue and dequeue
objects. The order of entry in the queue defines the order of exit from
the queue. The queue is constructed either empty or with a set of
objects.
Predicate
queue-p
Inheritance
Object
Constructors
Queue (none)
The Queue constructor create an empty queue.
Queue (Object...)
The Queue constructor create a queue with a list of object
arguments
Methods
enqueue -> Object (Object)
The enqueue adds an object in the queue and returns the queued
object.
dequeue -> Object (none)
The dequeue dequeue an object in the order it was queued.
length -> Object (none)
The length returns the number of queued objects.
empty-p -> Boolean (none)
The empty-p method returns true if the queue is empty.
flush -> none (none)
The flush method flushes the queue so that it is empty.
Heap
The Heap builtin object is an object based heap class that organizes
object with respect to a key. The heap is organized as a binary tree
those root element is either the object with the highest or the lowest
key. A flag controls whether the heap is operating in ascending or
descending mode. By default, the heap operates in ascending mode, which
means that the root node is the lowest one. The heap is self-resizable.
The object insertion is also controlled by a minimum and maximum key.
if the key is below the minimum key or above the maximum key, the
object is not inserted.
Predicate
heap-p
Inheritance
Object
Constructors
Heap (none)
The Heap constructor create an empty heap. By default the heap
operates in ascending mode.
Heap (Integer)
The Heap constructor create a heap with a specific size. By
default the heap operates in ascending mode.
Heap (Boolean)
The Heap constructor create a heap with a specific mode. If the
mode is true, the heap operates in ascending order. If the mode
is false, the heap operates in descending order. In ascending
order, the first object is the object with the lowest key.
Heap (Integer Boolean)
The Heap constructor create a heap with a specific size and
mode. The first argument is the heap size. The second argument
is the heap mode. If the mode is true, the heap operates in
ascending order. If the mode is false, the heap operates in
descending order. In ascending order, the first object is the
object with the lowest key.
Methods
add -> none (Integer Object)
The add method adds a new object in the heap by key. The first
argument is the key used to set the object position in the heap.
The second argument is the object to add.
pop -> Object (none)
The pop pops the first available in the heap. If the heap is
empty, an exception is raised.
length -> Object (none)
The length returns the number of objects in the heap.
empty-p -> Boolean (none)
The empty-p method returns true if the heap is empty.
reset -> none (none)
The reset method reset the heap so that it becomes empty.
get-key -> Integer (Integer)
The get-key method returns the key associated with an entry in
the heap by index. If the index is out of range, an exception is
raised.
get-object -> Object (Integer)
The get-object method returns the object associated with an
entry in the heap by index. If the index is out of range, an
exception is raised.
get-mode -> Boolean (none)
The get-mode method returns the heap operating mode. If the mode
is true, the heap operates in ascending order. If the mode is
false, the heap operates in descending order. In ascending
order, the first object is the object with the lowest key.
min-key-p -> Boolean (none)
The min-key-p predicate returns true if a minimum key has been
set. The get-min-key method can be used to retrieve the minimum
key value.
max-key-p -> Boolean (none)
The max-key-p predicate returns true if a maximum key has been
set. The get-max-key method can be used to retrieve the maximum
key value.
reset-min-key -> none (none)
The reset-min-key method resets the minimum key flag and value.
reset-max-key -> none (none)
The reset-max-key method resets the maximum key flag and value.
set-min-key -> none (Integer)
The set-min-key method sets the minimum key value.
get-min-key -> Integer (none)
The get-min-key method returns the minimum key value.
set-max-key -> none (Integer)
The set-max-key method sets the maximum key value.
get-max-key -> Integer (none)
The get-max-key method returns the maximum key value.
resize -> none (none)
The resize method resize the heap with a new size. if the size
is lower than the number of elements, the procedure does
nothing.
BitSet
The BitSet builtin object is a container for multi bit storage. The
size of the bitset is determined at construction. With the use of an
index, a particular bit can be set, cleared and tested.
Predicate
bitset-p
Inheritance
Object
Constructors
BitSet (none)
The BitSet constructor create an empty bitset.
BitSet (Integer)
The Bitset constructor create a bitset those size is given by
the integer argument.
Methods
get -> Boolean (Integer)
The get method returns the bit value by the index argument.
set -> none (Integer Boolean)
The set method set the bit value by the index argument with the
boolean second argument.
mark -> none (Integer)
The mark method marks a bit by the index argument.
clear -> none (Integer)
The clear method clears a bit by the index argument.
length -> Integer (none)
The length method returns the length of the bitset.
Buffer
The Buffer builtin object is a byte buffer that is widely used with i/o
operations. The buffer can be constructed with or without literal
arguments. The standard methods to add or push-back byte or characters
are available. One attractive method is the write method which can
write a complete buffer to an output stream specified as an argument.
By default, the buffer operates in resize mode. If the buffer is
configured to operate in non-resize mode, an exception is raised when
trying to add a character when the buffer is full.
Predicate
buffer-p
Inheritance
Object
Constructors
Buffer (none)
The Buffer constructor create an empty buffer. The buffer is
configured to operate in resize mode.
Buffer (Literal...)
The Buffer constructor create a buffer with a list of literal
object arguments. Each literal argument is used to produce a
byte representation which is added into the buffer.
Methods
add -> none (Byte|Literal|Buffer)
The add method adds a byte, a literal object or a buffer to the
calling buffer. The object argument is automatically converted
to a sequence of bytes. For a buffer, the entire content is
copied into the buffer.
get -> Byte (none)
The get method returns the next available byte in the buffer but
do not remove it.
read -> Byte (none)
The read method returns the next available character and remove
it from the buffer.
reset -> none (none)
The reset method reset the entire buffer and destroy its
contents.
length -> Integer (none)
The length method returns the length of the buffer.
write -> none (Output)
The write method writes the buffer contents to the output stream
argument.
full-p -> Boolean (none)
The full-p predicate return true if the buffer is full. If the
buffer is re-sizeable, the method always return false.
empty-p -> Boolean (none)
The empty-p predicate return true if the buffer is empty.
resize-p -> Boolean (none)
The resize-p predicate return true if the buffer is re-sizeable.
to-string -> String (none)
The to-string method returns a string representation of the
buffer.
pushback -> none (Byte|Literal|Buffer)
The pushback method push back a byte, a literal object or a
buffer in the calling buffer. The object argument is
automatically converted to a sequence of bytes. For a buffer,
the entire content is copied into the buffer.
get-word -> Integer (none)
The get-word method reads a word from the buffer and convert it
to an integer. The word is assumed to be in network byte order
and is converted to the host format before becoming an integer.
get-quad -> Integer (none)
The get-quad method reads a quad from the buffer and convert it
to an integer. The quad is assumed to be in network byte order
and is converted to the host format before becoming an integer.
get-octa -> Integer (none)
The get-quad method reads an octa from the buffer and convert it
to an integer. The octa is assumed to be in network byte order
and is converted to the host format before becoming an integer.
set-resize -> none (Boolean)
The set-resize method set the resize flag for a particular
buffer. This method can be used at any time.
Property
The Property builtin object is container for a name/value pair.
Generally, the property object is used within a property list.
Predicate
property-p
Inheritance
Serial
Constructors
Property (none)
The Property constructor create an empty property.
Property (String)
The Property constructor create a property by name. The first
argument is the property name.
Property (String Literal)
The Property constructor create a property by name and value.
The first argument is the property name. The second argument is
the property value, which is a literal converted to its string
representation.
Methods
set -> none (String Literal)
The set method sets the property name and value. The first
argument is the property name. The second argument is the
property value, which is a literal converted to its string
representation.
set-name -> none (String)
The set-name method sets the property name.
get-name -> String (none)
The get-name method returns the property name.
set-value -> none (Literal)
The set-value method sets the property value. The literal
argument is converted to its string representation.
get-value -> String (none)
The get-value method returns the property value.
Plist
The Plist builtin object is a base container class used to manage
property objects in an ordered way. The property list operates by
maintaining a vector of property object along with a hash table that
permits to find the object quickly.
Predicate
plist-p
Inheritance
SerialIterable
Constructors
Plist (none)
The Plist constructor create an empty property list.
Methods
add -> none (Property | String Literal)
The add method add a property by object or name and value in the
property list. In its first form the object is a property
object. In the second form, the first argument is the property
name and the second argument is the property value, which is a
literal converted to its string representation. If the property
already exists an exception is raised.
set -> none (String Literal)
The set method add or sets the property name and value in the
property list. The first argument is the property name. The
second argument is the property value, which is a literal
converted to its string representation. If the property already
exists, the property value is changed.
get -> Property (Integer)
The get method returns a property by index.
reset -> none (none)
The reset method resets the property lists
empty-p -> Boolean (none)
The emptyp- predicate returns true if the property list is
empty.
length -> Integer (none)
The length method returns the number of properties in the
property list.
exists-p -> Boolean (String)
The exists-p method returns true if a property exists. The
string argument is the property name.
find -> Property (String)
The find method finds a property by name. The string argument is
the property name. If the property does not exists, nil is
returned.
lookup -> Property (String)
The lookup method finds a property by name. The string argument
is the property name. If the property does not exists, an
exception is raised.
get-value -> String (String)
The get-value method returns the property value. The string
argument is the property name. If the property does not exist,
an exception is raised.
SPECIAL OBJECTS
This chapter is a reference of the AFNIX 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.
Methods
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.
shared-p -> Boolean (none)
The shared-p method returns true if the object is shared, false
otherwise.
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.
Predicate
interp-p
Inheritance
Runnable
Constants
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 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.
Methods
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)
The launch method executes the form argument in a normal thread.
The normal thread is created by cloning the current interpreter.
daemon -> Thread (form)
The daemon method executes the form argument in a daemon thread.
The normal thread is created by cloning the current interpreter.
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 or daemon reserved
keywords. Note that the thread object does not have a constructor.
Predicate
thread-p
Inheritance
Object
Constants
result
The result data member holds the thread result which is set at
the thread termination. The data member evaluates as an object.
Methods
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.
normal-p -> Boolean (none)
The normal-p method returns true if the thread argument is a
normal thread.
daemon-p -> Boolean (none)
The daemon-p method returns true if the thread argument is a
normal thread.
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.
Predicate
condvar-p
Inheritance
Object
Constructors
Condvar (none)
The Condvar constructor creates a default condition variable.
Methods
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 AFNIX 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.
Predicate
lexical-p
Inheritance
Literal
Constructors
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.
Methods
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 AFNIX 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.
Predicate
qualified-p
Inheritance
Literal
Constructors
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.
Methods
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.
Predicate
symbol-p
Inheritance
Literal
Constructors
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.
Methods
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.
Predicate
closure-p
Inheritance
Object
Constructors
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.
Methods
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.
Predicate
librarian-p
Inheritance
Nameable
Constructors
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.
Methods
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.
Predicate
resolver-p
Inheritance
Object
Constructors
Resolver (none)
The Resolver constructor creates a default resolver. Once
created, the add method can be used to add path to the resolver.
Methods
add -> none (String)
The add method adds a path into the resolver. The path can
points either to a directory or a librarian.
lookup -> Input (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.
Predicate
print-table-p
Inheritance
Object
Constructors
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.
Methods
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|Output|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|Output|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.
Predicate
logger-p
Inheritance
Object
Constructors
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.
Methods
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 (Output|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.