| sys(3) | Library Functions Manual | sys(3) |
sys - standard system access module
The Standard System Access module 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.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
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-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 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 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-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-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 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 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 use 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) # 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 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 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.
Time
The Time class 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
Inheritance
Constructors
Methods
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 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
Inheritance
Constructors
Methods
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
Inheritance
Constructors
Methods
Functions
| AFNIX | AFNIX Module |