Provided by: afnix_2.9.2-2build1_amd64 
NAME
sys - standard system access module
STANDARD SYSTEM ACCESS MODULE
The Standard System Accessmodule is an original implementation of various objects designed
to provide a specialized access to the underlying system. Most of the system accesses are
provided in the form of functions which have been designed to be portable as possible. One
example of this, are the time and date management objects.
Interpreter information
The interpreter provides a set reserved names that are related to the system platform.
Example 0501.alsdemonstrates the available information.
zsh> axi 0501.als
program name : afnix
operating system name : linux
operating system type : unix
afnix official uri : http://www.afnix.org
Interpreter version
The interpreter version is identified by 3 numbers called major, minorand patchnumbers. A
change in the major number represents a major change in the writing system. The minor
number indicates a major change in the interface or libraries. A change in the patch
number indicates bug fixes. All values are accessed via the interpreter itself. The major-
version, minor-version, patch-versionsymbols are bound to these values.
println "major version number : "
interp:major-version
println "minor version number : "
interp:minor-version
println "patch version number : "
interp:patch-version
Operating system
The operating system is uniquely identified by its name. The operating system type (or
category) uniquely identifies the operating system flavor.
println "operating system name : "
interp:os-name
println "operating system type : "
interp:os-type
Program information
Program information are carried by two symbols that identifies the program name and the
official uri. While the first might be useful, the second one is mostly used by demo
programs.
println "program name : "
interp:program-name
println "afnix official uri : "
interp:afnix-uri
System services
The system servicesmodule provides various functions that cannot be classified into any
particular category.
Function Description
exit terminate with an exit code
sleep pause for a certain time
get-pid get the process identifier
get-env get an environment variable
get-host-name get the host name
get-user-name get the user name
The exitfunction terminates the program with an exit code specified as the argument. The
sleepfunction pause the specific thread for a certain time. The time argument is expressed
in milliseconds. The get-pidfunction returns the process identifier. The get-envfunction
returns the environment variable associated with the string argument. The get-host-
namefunction returns the host name. The host name can be either a simple name or a
canonical name with its domain, depending on the system configuration. The get-user-
namefunction returns the current user name.
Time and date
The Timeand Dateclasses are classes designed to manipulate time and date. The writing
system operates with a special coordinated time which uses the reference of Jan 1st 0000
in a modified proleptic Gregorian calendar. This proleptic feature means that the actual
calendar (Gregorian) is extended beyond year 1582 (its introduction year) and modified in
order to support the year 0. This kind of calendar is somehow similar to the astronomical
Gregorian calendar except that the reference date is 0 for the writing system. This method
presents the advantage to support negative time. It should be noted that the 0 reference
does not means year 1BC since year 0 did not exist at that time (the concept of zero is
fairly new) and more important, the date expressed in the form 1BC generally refers to the
Julian calendar since the date is before 1582. Although, the class provides several
methods to access the time and date fields, it is also possible to get a string
representation that conforms to ISO-8601 or to RFC-2822.
Time and date construction
By default, a time instance of current time is constructed. This time reference is
obtained form the machine time and adjusted for the internal representation. One feature
of this class is that the time instance does not have to be bounded with 24 hours. The
time stored is the absolute time, which should be considered like a temporal reference --
or date -- those origin is 0 in some calendar representation.
const time (afnix:sys:Time)
assert true (afnxi:sys:time-p time)
A simple time representation can also be built by hours, minutes and seconds. In this
case, the time is a time definition at day 0 in the reference calendar.
const time (afnix:sys:Time 12 23 54)
By default a date instance of the current date is constructed. The current date is
computed from the machine time and expressed in a particular calendar. By default, the
engine uses a special Gregorian calendar as explained before. The important point here s
that the date will show up like the user should expect.
const date (afnix:sys:Date)
assert true (afnix:sys:date-p date)
A date instance can also be built with an absolute time expressed in seconds or with
specific elements. with one argument, the date is expressed in seconds since the origin.
Since the internal representation is 64 bits, the date room is quite large. For example,
the absolute time to represent Jan 1st 1970 is 62167219200 seconds. This epochis used to
adjust the system time on some UNIX system. Another way to create a specific date is to
use the date descriptor by year, month and day. With 6 arguments, the time components can
also be given. This makes Dateone of the constructor that accept the largest number of
arguments.
const date (afnix:sys:Date 1789 7 14 16 0 0)
assert true (afnix:sys:date-p date)
In the previous example, at 17:00 local time, 16:00Z although the concept of time zone was
not formalized, the Bastille surrenders on July 14 1789. This example shows that extreme
care should be used when dealing with old dates. Note that a simpler form could have been
used to set that date. With 3 argument, the date is set at time 00:00:00Z.
const date (afnix:sys:Date 1789 7 14)
assert true (afnix:sys:date-p date)
Time and date representation
Except for some special applications -- like the cookie maximum age --, the date
representation is quite standard and can be found either in the form of ISO-8601 or
RFC-2822.
const time (afnix:sys:Time 12 44 55)
println (time:format) # 12:44:55
println (time:to-iso) # 14:44:55
println (time:to-rfc) # 14:44:55 +0200
in the first form, the time is represented naturally by hour, minutes and seconds. By
default, it is the local time that is given. With a flag set to true, the UTC time is
displayed. In the second form, the time is displayed in the ISO-8601 form which is the
same as before. In the third form, the time is displayed in the RFC-2822 form. This form
is always expressed locally with the timezone difference associated with it. It shall be
noted that the ISO-8601 mandate to use the suffix 'Z' for the zulu time. This is the
difference when using the trueflag with the formatand to-isomethods.
println (time:format true) # 12:44:55
println (time:to-iso true) # 12:44:55Z
The date representation also operates with 3 methods, namely format, to-isoand to-rfc. For
example, if the time is 12:00 in Paris on July 14th 2000, the date will be displayed like
below.
const date (afnix:sys:Date 2000 7 14 12 0 0)
# Fri Jul 14 07:00:00 2000
println (date:format)
# 2000-07-14T07:00:00
println (date:to-iso)
# Fri, 14 Jul 2000 07:00:00 -0500
println (date:to-rfc)
The example show the local time. With UTC display, only the first two methods can be used.
const date (afnix:sys:Date 2000 7 14 12 0 0)
println (date:format true) # Fri Jul 14 12:00:00 2000
println (date:to-iso true) # 2000-07-14T12:00:00Z
Options parsing
The Optionsclass provides a convenient mechanism to define a set of options and to parse
them in a simple way. The object is constructed by specifying which option is valid and
how it behaves. The arguments can be passed to the object for subsequent analysis. An
option can be either a unique option or a string option. In this later case, multiple
value for the same option can be accepted. In that case, the option is said to be a string
vector option. An option can be also an option list. I that case, the option is defined
with a set of valid string. A list option is associated with a boolean flag for each
string defined with that option.
Option creation
An Optionsis created by invoking the constructor with or without a user message. The user
message is used by the usagemethod which display an information message.
const options (
afnix:sys:Options "axi [options] [file [arguments]]")
Eventually, the set-user-messagemethod can be used to set the user message.
Options definition
The process of defining options is done by specifying the option character, eventually an
option string and an option message.
options:add-unique-option 'h'
"print this help message"
options:add-unique-option 'v'
"print system version"
options:add-vector-option 'i'
"add a resolver path"
options:add-string-option 'e'
"force the encoding mode"
options:add-list-option 'f' "assert"
"enable assertion checks"
options:add-list-option 'f' "nopath"
"do not set initial path"
The above example shows the option descriptors for the interpreter. Since iis a vector
option, multiple occurrences of that option is allowed. It shall be noted that the list
option f assertis a debug option. This means that this option is always set when the
program is compiled in debug mode.
Options parsing and retrieval
A string vector is parsed with the parsemethod. Generally, the vector argument is the
interpreter argument vector defined in the qualified name interp:args. When the vector has
been successfully parsed, it is possible to check the option that have been set.
options:parse (Vector "-h")
if (options:get-unique-option 'h') {
options:usage
afnix:sys:exit 0
}
In the above example, the option vector is parsed with the parsemethod. The get-unique-
optionmethod returns true for the hthus triggering the display of the usage message.
usage: axi [options] [file [arguments]]
[h] print this help message
[v] print system version
[i path] add a resolver path
[e mode] force the encoding mode
[f assert] enable assertion checks
[f nopath] do not set initial path
If the option is a string option, the get-string-optionwill return the string associated
with that option. It shall be noted that the get-unique-optionmethod can be used to check
if the option has been set during the parsing process. If the option is a vector option,
the get-vector-optionmethod is more appropriate. In this case, a vector is returned with
all strings matching this option.
options:parse (
Vector "-i" "../" "-i" "../.." -e "UTF-08" "hello")
In the previous example, the vector option iis set two times. The associated vector option
has therefore a length of 2. The string option eis set to UTF-08. For this option e, the
get-unique-optionmethod will return true. Finally, the vector argument is filled with one
string argument.
STANDARD SYSTEM ACCESS REFERENCE
Time
The Timeclass is a simple class used to manipulate time. The AFNIX system operates with a
special coordinated time which uses the reference of Jan 1st 0000 in a modified proleptic
gregorian calendar. Note that the time can be negative. Although, the class provides
several methods to access the time fields, it is also possible to get a string
representation that conforms to ISO-8601 or to RFC-2822. The resolution is in seconds.
With 1 argument, the object is initialized with the time clock specified as an integer
argument. With 3 arguments, the time is expressed with its different elements.
Predicate
time-p
Inheritance
Object
Constructors
Time (none)
The Timeconstructor create a time object which is initialized with the current
time.
Time (Integer)
The Timeconstructor create a time object which is initialized with the time
argument.
Time (Integer Integer Integer)
The Timeconstructor create a time object which is initialized with the time
specific arguments, which are the hour, the minutes and the seconds.
Methods
add -> none (Integer)
The addmethod adds the time argument in seconds to the current time value This
method is useful to compute a time in the future, in reference to the current time.
add-minutes -> none (Integer)
The add-minutesmethod adds one or several minutes to the current time value. This
method is useful to compute a time in the future, in reference to the current time.
add-hours -> none (Integer)
The add-hourmethod adds one or several hours to the current time value. This method
is useful to compute a time in the future, in reference to the current time.
add-days -> none (Integer)
The add-daysmethod adds one or several days to the current time value. This method
is useful to compute a time in the future, in reference to the current time.
set-time -> none (Integer)
The set-timemethod set the absolute time in seconds.
get-time -> Integer (none|Boolean)
The get-timemethod returns absolute time in seconds. Without argument, the absolute
time is computed in reference to the UTC time. With a boolean argument set to true,
the time is computed in reference to the UTC time. If the argument is false, the
local time is used.
seconds -> Integer (none|Boolean)
The secondsmethod returns the number of seconds after the minute. Without argument,
the number of seconds is computed in reference to the UTC time. With a boolean
argument set to true, the number of seconds is computed in reference to the UTC
time. If the argument is false, the local time is used. The returned value is the
range 0 to 60.
minutes -> Integer (none|Boolean)
The minutesmethod returns the number of minutes after the hour. Without argument,
the number of minutes is computed in reference to the UTC time. With a boolean
argument set to true, the number of minutes is computed in reference to the UTC
time. If the argument is false, the local time is used. The returned value is the
range 0 to 60.
hours -> Integer (none|Boolean)
The hoursmethod returns the number of hours since midnight. Without argument, the
number of hours is computed in reference to the local time. With a boolean argument
set to true, the number of hours is computed in reference to the UTC time. If the
argument is false, the local time is used. The returned value is the range 0 to 23.
format -> String (none|Boolean)
The formatmethod returns a formatted representation of the time in the form of
hh:mm:ss. Without argument, the time is computed in reference to the local time.
With a boolean argument set to true, the time is computed in reference to the UTC
time. If the argument is false, the local time is used.
to-iso -> String (none|Boolean)
The to-isomethod returns a formatted representation of the time as specified by
ISO-8601. Without argument, the time is computed in reference to the local time.
With a boolean argument set to true, the time is computed in reference to the UTC
time. If the argument is false, the local time is used.
to-rfc -> String (none|Boolean)
The to-rfcmethod returns a formatted representation of the time as specified by
RFC-2822. Without argument, the time is computed in reference to the local time.
With a boolean argument set to true, the time is computed in reference to the UTC
time. If the argument is false, the local time is used.
get-base-day -> Integer (none)
The get-base-daymethod returns the absolute time rounded to the beginning of the
day.
Date
The Dateis a derived class designed to manipulate dates. The date computation is based on
an modified proleptic gregoriancalendar. This proleptic feature means that the actual
calendar (gregorian) is extended beyond year 1582 (its introduction year) and modified in
order to support the year 0. This kind of calendar is somehow similar to the astronomical
gregorian calendar except that the reference date is 0 for special coordinated time. This
method presents the advantage to support negative time. It should be noted that the 0
reference does not means year 1BC since year 0 did not exist at that time (the concept of
zero is fairly new) and more important, the date expressed in the form 1BC generally
refers to the Julian calendar since the date is before 1582. Although, the class provides
several methods to access the individual fields, it is also possible to get a string
representation that conforms to ISO-8601 or to RFC-2822. With 1 argument, the date is
initialized with the time clock specified as an integer argument. With 3 or 6 arguments,
the date is expressed with its different elements.
Predicate
date-p
Inheritance
Time
Constructors
Date (none)
The Dateconstructor creates a date object which is initialized with the current
time.
date (Integer)
The Dateconstructor creates a date object which is initialized with the time
argument.
Date (Integer Integer Integer)
The Dateconstructor creates a date object which is initialized with the date
specific arguments, which are the year, the month and the day in the month.
Date (Integer Integer Integer Integer Integer Integer)
The Dateconstructor creates a date object which is initialized with the date
specific arguments, which are the year, the month, the day in the month, the hours,
the minutes and the seconds.
Methods
year -> Integer (none|Boolean)
The yearmethod returns the date year. the returned value is an absolute year value
which can be negative. Without argument, the number of years is computed in
reference to the local time. With a boolean argument set to true, the number of
years is computed in reference to the UTC time. If the argument is false, the local
time is used.
month -> Integer (none|Boolean)
The monthmethod returns the month in the year. The returned value is the range 1 to
12. Without argument, the number of months is computed in reference to the local
time. With a boolean argument set to true, the number of months is computed in
reference to the UTC time. If the argument is false, the local time is used.
day -> Integer (none|Boolean)
The daymethod returns the day in the month. The returned value is the range 1 to
31. Without argument, the number of days is computed in reference to the local
time. With a boolean argument set to true, the number of days is computed in
reference to the UTC time. If the argument is false, the local time is used.
week-day -> Integer (none|Boolean)
The week-daymethod returns the day in the week. The returned value is the range 0
to 6 in reference to Sunday. Without argument, the day is computed in reference to
the local time. With a boolean argument set to true, the day is computed in
reference to the UTC time. If the argument is false, the local time is used.
year-day -> Integer (none|Boolean)
The year-daymethod returns the day in the year. The returned value is the range 1
to 366 in reference to January 1st. Without argument, the day is computed in
reference to the local time. With a boolean argument set to true, the day is
computed in reference to the UTC time. If the argument is false, the local time is
used.
map-day -> String (none|Boolean)
The map-daymethod returns a formatted representation of the day. Without argument,
the day is computed in reference to the local time. With a boolean argument set to
true, the day is computed in reference to the UTC time. If the argument is false,
the local time is used.
map-month -> String (none|Boolean)
The map-monthmethod returns a formatted representation of the month. Without
argument, the month is computed in reference to the local time. With a boolean
argument set to true, the month is computed in reference to the UTC time. If the
argument is false, the local time is used.
format -> String (none|Boolean)
The formatmethod returns a formatted representation of the date. Without argument,
the time is computed in reference to the local time. With a boolean argument set to
true, the time is computed in reference to the UTC time. If the argument is false,
the local time is used.
to-iso -> String (none|Boolean)
The to-isomethod returns a formatted representation of the date as specified by
ISO-8601. Without argument, the time is computed in reference to the local time.
With a boolean argument set to true, the time is computed in reference to the UTC
time. If the argument is false, the local time is used.
to-web -> String (none)
The to-webmethod returns a formatted representation of the date as specified by
RFC-1123.
to-rfc -> String (none|Boolean)
The to-rfcmethod returns a formatted representation of the date as specified by
RFC-2822. Without argument, the time is computed in reference to the local time.
With a boolean argument set to true, the time is computed in reference to the UTC
time. If the argument is false, the local time is used.
to-date -> String (none|Boolean)
The to-datemethod returns a formatted representation of the date only as specified
by ISO-8601. With this method, the time value is not included in the
representation. Without argument, the date is computed in reference to the local
time. With a boolean argument set to true, the date is computed in reference to the
UTC time. If the argument is false, the local time is used.
to-time -> String (none|Boolean)
The to-timemethod returns a formatted representation of the time as returned by the
Time formatmethod. Without argument, the time is computed in reference to the local
time. With a boolean argument set to true, the time is computed in reference to the
UTC time. If the argument is false, the local time is used.
add-years -> none (Integer)
The add-yearsmethod add one or several years to the current date.
add-months -> none (Integer)
The add-monthsmethod add one or several months to the current date.
Options
The Optionsclass is a simple class used to define and retrieve user options. The object is
constructed by specifying which option is valid and how it behaves. The arguments can be
passed to the object for subsequent analysis. An option can be either a unique option or a
string option. In this later case, multiple value for the same option can be accepted. In
that case, the option is said to be a string vector option. An option can be also an
option list. I that case, the option is defined with a set of valid string. A list option
is associated with a boolean flag for each string defined with that option.
Predicate
options-p
Inheritance
Object
Constructors
Options (none)
The Optionsconstructor creates a default option object without a user message.
Options (String)
The Optionsconstructor creates an empty option object with a user message. The user
message is used by the usagemethod.
Methods
reset -> none (none)
The resetmethod resets the object data structure but do not remove the option
descriptors. After a reset operation, the class is ready to parse another string
vector.
usage -> none (none)
The usagemethod prints a usage message with a user message and a one line
description per option. removing all messages.
parse -> Vector (none)
The parsemethod parse a vector and fill the option data structure. The parse method
is generally called with the interpreter argument vector.
empty-p -> Boolean (none)
The empty-predicate returns true if the argument vector is empty. The argument
vector is filled wit the string that are not options during the parsing process.
add-list-option -> none (Character String String)
The add-list-optionmethod creates a new list option. The list option is defined by
the option character and the option string. The first argument is the option
character. The second argument is the option list string. The third argument is the
option message. During the parsing process, the list option have a string argument
which must match one string associated with the option character.
get-unique-option -> Character String (none)
The add-unique-optionmethod creates a new single option. The option is defined only
by its character. The first argument is the option character. The second argument
is the option message. During the parsing process, a unique option does not have an
argument.
add-string-option -> none (Character String)
The add-string-optionmethod creates a new string option. The option is defined only
by its character. The first argument is the option character. The second argument
is the option message. During the parsing process, a string option have a string
argument.
add-vector-option -> Character String (none)
The add-vector-optionmethod creates a new vector option. The option is defined only
by its character. The first argument is the option character. The second argument
is the option message. During the parsing process, a vector option have a string
argument which is accumulated in a vector.
set-user-message -> none (String)
The set-user-messagemethod sets the global option user message. The user message is
used by the usagemethod.
get-user-message -> String (none)
The get-user-messagemethod returns the global option user message. The user message
is used by the usagemethod.
get-unique-option -> Boolean (Character)
The get-unique-optionmethod returns the flag associated with an option. If the
option has been detected during the parsing process, the method returns true. This
method works also for string option or list option to indicate if the string has
been set for that option. with a vector option, it is simpler to get the vector and
check for the vector length. The first argument is the option character to use for
testing.
get-string-option -> String (Character)
The get-string-optionmethod returns the string associated with a string option. In
order to make sure that a string option has been properly set during the parsing
process, it is recommended to use the get-unique-optionmethod. The first argument
is the option character to use for the string retrieval.
get-vector-option -> Vector (Character)
The get-vector-optionmethod returns the vector associated with a vector option. The
first argument is the option character to use for the vector retrieval.
get-vector-arguments -> Vector (none)
The get-vector-argumentsmethod returns the vector arguments built during the
parsing process.
Functions
exit -> none (Integer)
The exitfunction terminates the executing program with the exit code specified as
the argument.
sleep -> none (Integer)
The sleepfunction pause the specific thread for a certain time. The time argument
is expressed in milliseconds. This function returns nil.
get-option -> String (Character)
The get-optionfunction returns a formatted string equivalent to the system option
as specified by the character argument.
get-unique-id -> Integer (none)
The get-unique-idfunction returns an unique integer number. The returned number is
unique across the session.
get-pid -> Integer (none)
The get-pidfunction returns the process identifier (pid). The returned value is a
positive integer.
get-env -> String (String)
The get-envfunction returns the environment variable associated with the string
argument. If the environment does not exist an exception is raised.
get-host-fqdn -> String (none)
The get-host-fqdnfunction returns the host fully qualified domain name. This is the
combined host and domain names which is sometimes called the canonical name.
get-domain-name -> String (none)
The get-domain-namefunction returns the host domain name.
get-host-name -> String (none)
The get-host-namefunction returns the host name. If the host does not have a domain
name, the host name is equal to the fully qualified domain name.
get-user-name -> String (none)
The get-user-namefunction returns the current user name.