afnix-sys






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

     Interpreterinformation
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


     Interpreterversion
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


     Operatingsystem
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


     Programinformation
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









                             ‐2‐


programs.

println "program name           : "
interp:program‐name
println "afnix official uri     : "
interp:afnix‐uri


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

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

     dateTimeand
By default, a time instance of current time is constructed.









                             ‐3‐


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)


     dateTimeand
Except for some special applications ‐‐ like the cookie









                             ‐4‐


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


     Optionsparsing
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









                             ‐5‐


of valid string. A list option is associated with a boolean
flag for each string defined with that option.

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

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

     andOptionsparsing
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









                             ‐6‐


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.



     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









                             ‐7‐


     initialized with the current time.

     Time(Integer)
     The Timeconstructor create a time object which is
     initialized with the time argument.

     IntegerTime(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

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

     noneadd‐minutes‐>
     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.

     noneadd‐hours‐>
     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.

     noneadd‐days‐>
     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.

     noneset‐time‐>
     The set‐timemethod set the absolute time in seconds.

     Integerget‐time‐>
     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.

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

     Integerminutes‐>









                             ‐8‐


     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.

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

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

     Stringto‐iso‐>
     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.

     Stringto‐rfc‐>
     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.

     Integerget‐base‐day‐>
     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









                             ‐9‐


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.

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

     IntegerDate(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

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

     Integermonth‐>









                            ‐10‐


     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.

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

     Integerweek‐day‐>
     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.

     Integeryear‐day‐>
     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.

     Stringmap‐day‐>
     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.

     Stringmap‐month‐>
     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.

     Stringformat‐>
     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









                            ‐11‐


     UTC time. If the argument is false, the local time is
     used.

     Stringto‐iso‐>
     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.

     Stringto‐web‐>
     The to‐webmethod returns a formatted representation of
     the date as specified by RFC‐1123.

     Stringto‐rfc‐>
     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.

     Stringto‐date‐>
     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.

     Stringto‐time‐>
     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.

     noneadd‐years‐>
     The add‐yearsmethod add one or several years to the
     current date.

     noneadd‐months‐>
     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









                            ‐12‐


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

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

     noneusage‐>
     The usagemethod prints a usage message with a user
     message and a one line description per option. removing
     all messages.

     Vectorparse‐>
     The parsemethod parse a vector and fill the option data
     structure. The parse method is generally called with
     the interpreter argument vector.

     Booleanempty‐p‐>
     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.

     noneadd‐list‐option‐>
     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









                            ‐13‐


     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.

     Characterget‐unique‐option‐>
     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.

     noneadd‐string‐option‐>
     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.

     Characteradd‐vector‐option‐>
     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.

     noneset‐user‐message‐>
     The set‐user‐messagemethod sets the global option user
     message. The user message is used by the usagemethod.

     Stringget‐user‐message‐>
     The get‐user‐messagemethod returns the global option
     user message. The user message is used by the
     usagemethod.

     Booleanget‐unique‐option‐>
     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.

     Stringget‐string‐option‐>
     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.









                            ‐14‐


     Vectorget‐vector‐option‐>
     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.

     Vectorget‐vector‐arguments‐>
     The get‐vector‐argumentsmethod returns the vector
     arguments built during the parsing process.

     Functions

     noneexit‐>
     The exitfunction terminates the executing program with
     the exit code specified as the argument.

     nonesleep‐>
     The sleepfunction pause the specific thread for a
     certain time. The time argument is expressed in
     milliseconds. This function returns nil.

     Stringget‐option‐>
     The get‐optionfunction returns a formatted string
     equivalent to the system option as specified by the
     character argument.

     Integerget‐unique‐id‐>
     The get‐unique‐idfunction returns an unique integer
     number. The returned number is unique across the
     session.

     Integerget‐pid‐>
     The get‐pidfunction returns the process identifier
     (pid). The returned value is a positive integer.

     Stringget‐env‐>
     The get‐envfunction returns the environment variable
     associated with the string argument. If the environment
     does not exist an exception is raised.

     Stringget‐host‐fqdn‐>
     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.

     Stringget‐domain‐name‐>
     The get‐domain‐namefunction returns the host domain
     name.

     Stringget‐host‐name‐>
     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.










                            ‐15‐


     Stringget‐user‐name‐>
     The get‐user‐namefunction returns the current user
     name.