Provided by: afnix_2.1.1-3_amd64 bug

NAME

       sys - standard system access module

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.

STANDARD SYSTEM ACCESS REFERENCE

       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

              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|Boolean)
              The  get-time  method  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 seconds method  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 minutes method 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 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|Boolean)
              The  to-rfc  method  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-day method returns the absolute time rounded to the beginning  of  the
              day.

       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

              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|Boolean)
              The year method 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 month method 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  day  method 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-day method 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-day method 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-day method 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-month method 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 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-web -> String (none)
              The  to-web  method  returns a formatted representation of the date as specified by
              RFC-1123.

              to-rfc -> String (none|Boolean)
              The to-rfc method 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-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.  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-time  method  returns a formatted representation of the time as returned by
              the Time format method. 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-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-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.