NAME
sys - standard system services module
INTRODUCTION
This chapter covers the system services available in the AFNIX
standard system service module. The basic operations that are embedded
in the interpreter gives system information. Complex information, like
the system time are provided via specific classes. All AFNIX system
service objects are located in the afnix-sys module. This module must
be loaded prior any operation. Multiple calls to the module
initialization routine are harmless. The interpreter method module
loads a specific module by name. When the module has been loaded, the
object are available in the afnix:sys nameset.
interp:library "afnix-sys"
Interpreter information
The AFNIX interpreter provides a set reserved names that are related
to the system platform. Example 0501.als demonstrates 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, minor
and patch numbers. A change in the major number represents a major
change in the AFNIX language. 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-version symbols 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 AFNIX url. While the first might be
useful, the second one is mostly used by demo programs.
println "program name : " interp:program-name
println "afnix official url : " interp:afnix-url
System services
The system services module 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-random return a random integer number
get-random-real return a random real number
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 exit function terminates the program with an exit code specified as
the argument. The sleep function pause the specific thread for a
certain time. The time argument is expressed in milliseconds. The get-
random function returns a random integer number. The get-random-real
returns a random real number. The get-pid function returns the process
identifier. The get-env function returns the environment variable
associated with the string argument. The get-host-name function 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-name function returns the current user name.
Time and date
The Time and Date classes are classes designed to manipulate time and
date. The AFNIX system operates with the AFNIX time coordinated or
ATC 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 atc 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 AFNIX
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 AFNIX 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 AFNIX 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 epoch is 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 Date one 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 sue the suffix
’Z’ for the zulu time. This is the difference when using the true flag
with the format and to-iso methods.
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-iso and 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)
println (date:format) # Fri Jul 14 07:00:00 2000
println (date:to-iso) # 2000-07-14T07:00:00
println (date:to-rfc) # Fri, 14 Jul 2000 07:00:00 -0500
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 Options class 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 Options is created by invoking the constructor with or without a
user message. The user message is used by the usage method which
display an information message.
const options (afnix:sys:Options "axi [options] [file [arguments]]")
Eventually, the set-user-message method 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 AFNIX
interpreter. Since i is a vector option, multiple occurrences of that
option is allowed. It shall be noted that the list option f assert is 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 parse method. 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 parse
method. The get-unique-option method returns true for the h thus
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-option will return the
string associated with that option. It shall be noted that the get-
unique-option method 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-option method 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 i is set two times. The
associated vector option has therefore a length of 2. The string option
e is set to UTF-08. For this option e, the get-unique-option method
will return true. Finally, the vector argument is filled with one
string argument.
STANDARD SYSTEM SERVICES REFERENCE
This appendix is a reference of the AFNIX standard system services
module.
Symbol Description
afnix-sys module
afnix:sys nameset
Time
The Time class is a simple class used to manipulate time. The AFNIX
system operates with the afnix time coordinated or ATC 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 Time constructor create a time object which is initialized
with the current time.
Time (Integer)
The Time constructor create a time object which is initialized
with the time argument.
Time (Integer Integer Integer)
The Time constructor 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 add method 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-minutes method 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-hour method 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-days method 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-time method set the absolute time in seconds.
get-time -> Integer (none)
The get-time method returns absolute time in seconds
seconds -> Integer (none|Boolean)
The seconds method returns the number of seconds after the
minute. Without argument, the number of seconds is computed in
reference to the local 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 minutes method returns the number of minutes after the hour.
Without argument, the number of minutes is computed in reference
to the local 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 hours method 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 format method 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-iso method 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)
The to-rfc method returns a formatted representation of the time
as specified by RFC-2822. The time is computed in reference to
the local time.
Date
The Date is a derived class designed to manipulate dates. The date
computation is based on an 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 ATC system -- AFNIX time coordinated--. 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 Date constructor creates a date object which is initialized
with the current time.
date (Integer)
The Date constructor creates a date object which is initialized
with the time argument.
Date (Integer Integer Integer)
The Date constructor 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 Date constructor 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)
The year method returns the date year. the returned value is an
absolute year value which can be negative.
month -> Integer (none)
The month method returns the month in the year. The returned
value is the range 1 to 12.
day -> Integer (none)
The day method returns the day in the month. The returned value
is the range 1 to 31.
week-day -> Integer (none)
The week-day method returns the day in the week. The returned
value is the range 0 to 6 in reference to Sunday.
year-day -> Integer (none)
The year-day method returns the day in the year. The returned
value is the range 1 to 366 in reference to January 1st.
map-day -> String (none)
The map-day method returns a formatted representation of the
day.
map-month -> String (none)
The map-month method returns a formatted representation of the
month.
format -> String (none|Boolean)
The format method 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-iso method 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-rfc -> String (none)
The to-rfc method returns a formatted representation of the date
as specified by RFC-2822. The time is computed in reference to
the local time.
to-date -> String (none)
The to-date method 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.
to-time -> String (none|Boolean)
The to-time method returns a formatted representation of the
time as returned by the Time format method.
get-base-day -> Integer (none)
The get-base-day method returns the absolute time rounded to the
beginning of the day.
add-years -> none (Integer)
The add-years method add one or several years to the current
date.
add-months -> none (Integer)
The add-months method add one or several months to the current
date.
Options
The Options class 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 Options constructor creates a default option object without
a user message.
Options (String)
The Options constructor creates an empty option object with a
user message. The user message is used by the usage method.
Methods
reset -> none (none)
The reset method 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 usage method prints a usage message with a user message and
a one line description per option. removing all messages.
parse -> Vector (none)
The parse method 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-option method 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-option method 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-option method 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-option method 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-message method sets the global option user message.
The user message is used by the usage method.
get-user-message -> String (none)
The get-user-message method returns the global option user
message. The user message is used by the usage method.
get-unique-option -> Boolean (Character)
The get-unique-option method 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-option method 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-option method. The first argument is the
option character to use for the string retrieval.
get-vector-option -> Vector (Character)
The get-vector-option method 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-arguments method returns the vector arguments
built during the parsing process.
Functions
exit -> none (Integer)
The exit function terminates the executing program with the exit
code specified as the argument.
sleep -> none (Integer)
The sleep function 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-option function returns a formatted string equivalent to
the system option as specified by the character argument.
get-random -> Integer (none|Integer)
The get-random function returns a random integer number. Without
argument, the integer range is machine dependent. With one
integer argument, the resulting integer number is less than the
specified maximum bound.
get-random-real -> Real (none)
The get-random-real function returns a random real number
between 0.0 and 1.0.
get-unique-id -> Integer (none)
The get-unique-id function returns an unique integer number. The
returned number is unique across the session.
get-pid -> Integer (none)
The get-pid function returns the process identifier (pid). The
returned value is a positive integer.
get-env -> String (String)
The get-env function returns the environment variable associated
with the string argument. If the environment does not exist an
exception is raised.
get-host-name -> String (none)
The get-host-name function 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.
get-user-name -> String (none)
The get-user-name function returns the current user name.