Provided by: afnix_2.8.1-2_amd64 bug

NAME

       sys - standard system access module

STANDARD SYSTEM ACCESS MODULE

       The Standard System Accessmodule is an original implementation of various objects designed
       to provide a specialized access to the underlying system. Most of the system accesses  are
       provided in the form of functions which have been designed to be portable as possible. One
       example of this, are the time and date management objects.

       Interpreter information
       The interpreter provides a set reserved names that are related  to  the  system  platform.
       Example 0501.alsdemonstrates the available information.

       zsh> axi 0501.als
       program name           : afnix
       operating system name  : linux
       operating system type  : unix
       afnix official uri     : http://www.afnix.org

       Interpreter version
       The  interpreter version is identified by 3 numbers called major, minorand patchnumbers. A
       change in the major number represents a major change in  the  writing  system.  The  minor
       number  indicates  a  major  change  in  the interface or libraries. A change in the patch
       number indicates bug fixes. All values are accessed via the interpreter itself. The major-
       version, minor-version, patch-versionsymbols are bound to these values.

       println "major version number   : "
       interp:major-version
       println "minor version number   : "
       interp:minor-version
       println "patch version number   : "
       interp:patch-version

       Operating system
       The  operating  system  is  uniquely identified by its name. The operating system type (or
       category) uniquely identifies the operating system flavor.

       println "operating system name  : "
       interp:os-name
       println "operating system type  : "
       interp:os-type

       Program information
       Program information are carried by two symbols that identifies the program  name  and  the
       official  uri.  While  the  first  might  be useful, the second one is mostly used by demo
       programs.

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

       System services
       The system servicesmodule provides various functions that cannot be  classified  into  any
       particular category.

       Function        Description

       exit            terminate with an exit code
       sleep           pause for a certain time
       get-pid         get the process identifier
       get-env         get an environment variable
       get-host-name   get the host name
       get-user-name   get the user name

       The  exitfunction  terminates the program with an exit code specified as the argument. The
       sleepfunction pause the specific thread for a certain time. The time argument is expressed
       in  milliseconds.  The get-pidfunction returns the process identifier. The get-envfunction
       returns the environment variable  associated  with  the  string  argument.  The  get-host-
       namefunction  returns  the  host  name.  The  host  name  can be either a simple name or a
       canonical name with its domain, depending  on  the  system  configuration.  The  get-user-
       namefunction returns the current user name.

       Time and date
       The  Timeand  Dateclasses  are  classes  designed to manipulate time and date. The writing
       system operates with a special coordinated time which uses the reference of Jan  1st  0000
       in  a  modified proleptic Gregorian calendar. This proleptic feature means that the actual
       calendar (Gregorian) is extended beyond year 1582 (its introduction year) and modified  in
       order  to support the year 0. This kind of calendar is somehow similar to the astronomical
       Gregorian calendar except that the reference date is 0 for the writing system. This method
       presents  the  advantage to support negative time. It should be noted that the 0 reference
       does not means year 1BC since year 0 did not exist at that time (the concept  of  zero  is
       fairly new) and more important, the date expressed in the form 1BC generally refers to the
       Julian calendar since the date is  before  1582.  Although,  the  class  provides  several
       methods  to  access  the  time  and  date  fields,  it  is  also  possible to get a string
       representation that conforms to ISO-8601 or to RFC-2822.

       Time and date construction
       By default, a time instance of  current  time  is  constructed.  This  time  reference  is
       obtained  form  the machine time and adjusted for the internal representation. One feature
       of this class is that the time instance does not have to be bounded  with  24  hours.  The
       time  stored is the absolute time, which should be considered like a temporal reference --
       or date -- those origin is 0 in some calendar representation.

       const  time (afnix:sys:Time)
       assert true (afnxi:sys:time-p time)

       A simple time representation can also be built by hours,  minutes  and  seconds.  In  this
       case, the time is a time definition at day 0 in the reference calendar.

       const  time (afnix:sys:Time 12 23 54)

       By  default  a  date  instance  of  the  current  date is constructed. The current date is
       computed from the machine time and expressed in a particular  calendar.  By  default,  the
       engine  uses  a special Gregorian calendar as explained before. The important point here s
       that the date will show up like the user should expect.

       const  date (afnix:sys:Date)
       assert true (afnix:sys:date-p date)

       A date instance can also be built with an absolute  time  expressed  in  seconds  or  with
       specific  elements.  with one argument, the date is expressed in seconds since the origin.
       Since the internal representation is 64 bits, the date room is quite large.  For  example,
       the  absolute  time to represent Jan 1st 1970 is 62167219200 seconds. This epochis used to
       adjust the system time on some UNIX system. Another way to create a specific  date  is  to
       use  the date descriptor by year, month and day. With 6 arguments, the time components can
       also be given. This makes Dateone of the constructor that accept  the  largest  number  of
       arguments.

       const  date (afnix:sys:Date 1789 7 14 16 0 0)
       assert true (afnix:sys:date-p date)

       In the previous example, at 17:00 local time, 16:00Z although the concept of time zone was
       not formalized, the Bastille surrenders on July 14 1789. This example shows  that  extreme
       care  should be used when dealing with old dates. Note that a simpler form could have been
       used to set that date. With 3 argument, the date is set at time 00:00:00Z.

       const  date (afnix:sys:Date 1789 7 14)
       assert true (afnix:sys:date-p date)

       Time and date representation
       Except for some special  applications  --  like  the  cookie  maximum  age  --,  the  date
       representation  is  quite  standard  and  can  be  found either in the form of ISO-8601 or
       RFC-2822.

       const time (afnix:sys:Time 12 44 55)
       println    (time:format) # 12:44:55
       println    (time:to-iso) # 14:44:55
       println    (time:to-rfc) # 14:44:55 +0200

       in the first form, the time is represented naturally by  hour,  minutes  and  seconds.  By
       default,  it  is  the  local  time that is given. With a flag set to true, the UTC time is
       displayed. In the second form, the time is displayed in the ISO-8601  form  which  is  the
       same  as  before. In the third form, the time is displayed in the RFC-2822 form. This form
       is always expressed locally with the timezone difference associated with it. It  shall  be
       noted  that  the  ISO-8601  mandate  to  use the suffix 'Z' for the zulu time. This is the
       difference when using the trueflag with the formatand to-isomethods.

       println (time:format true) # 12:44:55
       println (time:to-iso true) # 12:44:55Z

       The date representation also operates with 3 methods, namely format, to-isoand to-rfc. For
       example,  if the time is 12:00 in Paris on July 14th 2000, the date will be displayed like
       below.

       const date (afnix:sys:Date 2000 7 14 12 0 0)
       # Fri Jul 14 07:00:00 2000
       println (date:format)
       # 2000-07-14T07:00:00
       println (date:to-iso)
       # Fri, 14 Jul 2000 07:00:00 -0500
       println (date:to-rfc)

       The example show the local time. With UTC display, only the first two methods can be used.

       const date (afnix:sys:Date 2000 7 14 12 0 0)
       println (date:format true) # Fri Jul 14 12:00:00 2000
       println (date:to-iso true) # 2000-07-14T12:00:00Z

       Options parsing
       The Optionsclass provides a convenient mechanism to define a set of options and  to  parse
       them  in  a  simple way. The object is constructed by specifying which option is valid and
       how it behaves. The arguments can be passed to the  object  for  subsequent  analysis.  An
       option  can  be  either  a  unique option or a string option. In this later case, multiple
       value for the same option can be accepted. In that case, the option is said to be a string
       vector  option.  An  option can be also an option list. I that case, the option is defined
       with a set of valid string. A list option is associated  with  a  boolean  flag  for  each
       string defined with that option.

       Option creation
       An  Optionsis created by invoking the constructor with or without a user message. The user
       message is used by the usagemethod which display an information message.

       const options (
         afnix:sys:Options "axi [options] [file [arguments]]")

       Eventually, the set-user-messagemethod can be used to set the user message.

       Options definition
       The process of defining options is done by specifying the option character, eventually  an
       option string and an option message.

       options:add-unique-option 'h'
       "print this help message"
       options:add-unique-option 'v'
       "print system version"
       options:add-vector-option 'i'
       "add a resolver path"
       options:add-string-option 'e'
       "force the encoding mode"
       options:add-list-option   'f' "assert"
       "enable assertion checks"
       options:add-list-option   'f' "nopath"
       "do not set initial path"

       The  above  example  shows  the option descriptors for the interpreter. Since iis a vector
       option, multiple occurrences of that option is allowed. It shall be noted  that  the  list
       option  f  assertis  a  debug  option.  This means that this option is always set when the
       program is compiled in debug mode.

       Options parsing and retrieval
       A string vector is parsed with the parsemethod. Generally,  the  vector  argument  is  the
       interpreter argument vector defined in the qualified name interp:args. When the vector has
       been successfully parsed, it is possible to check the option that have been set.

       options:parse (Vector "-h")
       if (options:get-unique-option 'h') {
         options:usage
         afnix:sys:exit 0
       }

       In the above example, the option vector is parsed with the  parsemethod.  The  get-unique-
       optionmethod returns true for the hthus triggering the display of the usage message.

       usage: axi [options] [file [arguments]]
       [h]           print this help message
       [v]           print system version
       [i   path]    add a resolver path
       [e   mode]    force the encoding mode
       [f assert]    enable assertion checks
       [f nopath]    do not set initial path

       If  the  option is a string option, the get-string-optionwill return the string associated
       with that option. It shall be noted that the get-unique-optionmethod can be used to  check
       if  the  option has been set during the parsing process. If the option is a vector option,
       the get-vector-optionmethod is more appropriate. In this case, a vector is  returned  with
       all strings matching this option.

       options:parse (
         Vector "-i" "../" "-i" "../.." -e "UTF-08" "hello")

       In the previous example, the vector option iis set two times. The associated vector option
       has therefore a length of 2. The string option eis set to UTF-08. For this option  e,  the
       get-unique-optionmethod  will return true. Finally, the vector argument is filled with one
       string argument.

STANDARD SYSTEM ACCESS REFERENCE

       Time
       The Timeclass is a simple class used to manipulate time. The  AFNIX system operates with a
       special  coordinated time which uses the reference of Jan 1st 0000 in a modified proleptic
       gregorian calendar. Note that the time can  be  negative.  Although,  the  class  provides
       several  methods  to  access  the  time  fields,  it  is  also  possible  to  get a string
       representation that conforms to ISO-8601 or to RFC-2822. The  resolution  is  in  seconds.
       With  1  argument,  the  object is initialized with the time clock specified as an integer
       argument. With 3 arguments, the time is expressed with its different elements.

       Predicate

              time-p

       Inheritance

              Object

       Constructors

              Time (none)
              The Timeconstructor create a time object which  is  initialized  with  the  current
              time.

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

              Time (Integer Integer Integer)
              The Timeconstructor create a  time  object  which  is  initialized  with  the  time
              specific arguments, which are the hour, the minutes and the seconds.

       Methods

              add -> none (Integer)
              The  addmethod  adds  the  time  argument in seconds to the current time value This
              method is useful to compute a time in the future, in reference to the current time.

              add-minutes -> none (Integer)
              The add-minutesmethod adds one or several minutes to the current time  value.  This
              method is useful to compute a time in the future, in reference to the current time.

              add-hours -> none (Integer)
              The add-hourmethod adds one or several hours to the current time value. This method
              is useful to compute a time in the future, in reference to the current time.

              add-days -> none (Integer)
              The add-daysmethod adds one or several days to the current time value. This  method
              is useful to compute a time in the future, in reference to the current time.

              set-time -> none (Integer)
              The set-timemethod set the absolute time in seconds.

              get-time -> Integer (none|Boolean)
              The get-timemethod returns absolute time in seconds. Without argument, the absolute
              time is computed in reference to the UTC time. With a boolean argument set to true,
              the  time  is  computed in reference to the UTC time. If the argument is false, the
              local time is used.

              seconds -> Integer (none|Boolean)
              The secondsmethod returns the number of seconds after the minute. Without argument,
              the  number  of  seconds  is  computed in reference to the UTC time. With a boolean
              argument set to true, the number of seconds is computed in  reference  to  the  UTC
              time.  If  the argument is false, the local time is used. The returned value is the
              range 0 to 60.

              minutes -> Integer (none|Boolean)
              The minutesmethod returns the number of minutes after the hour.  Without  argument,
              the  number  of  minutes  is  computed in reference to the UTC time. With a boolean
              argument set to true, the number of minutes is computed in  reference  to  the  UTC
              time.  If  the argument is false, the local time is used. The returned value is the
              range 0 to 60.

              hours -> Integer (none|Boolean)
              The hoursmethod returns the number of hours since midnight. Without  argument,  the
              number of hours is computed in reference to the local time. With a boolean argument
              set to true, the number of hours is computed in reference to the UTC time.  If  the
              argument is false, the local time is used. The returned value is the range 0 to 23.

              format -> String (none|Boolean)
              The  formatmethod  returns  a  formatted  representation of the time in the form of
              hh:mm:ss. Without argument, the time is computed in reference to  the  local  time.
              With  a  boolean argument set to true, the time is computed in reference to the UTC
              time. If the argument is false, the local time is used.

              to-iso -> String (none|Boolean)
              The to-isomethod returns a formatted representation of the  time  as  specified  by
              ISO-8601.  Without  argument,  the time is computed in reference to the local time.
              With a boolean argument set to true, the time is computed in reference to  the  UTC
              time. If the argument is false, the local time is used.

              to-rfc -> String (none|Boolean)
              The  to-rfcmethod  returns  a  formatted representation of the time as specified by
              RFC-2822. Without argument, the time is computed in reference to  the  local  time.
              With  a  boolean argument set to true, the time is computed in reference to the UTC
              time. If the argument is false, the local time is used.

              get-base-day -> Integer (none)
              The get-base-daymethod returns the absolute time rounded to the  beginning  of  the
              day.

       Date
       The  Dateis a derived class designed to manipulate dates. The date computation is based on
       an modified proleptic gregoriancalendar. This proleptic  feature  means  that  the  actual
       calendar  (gregorian) is extended beyond year 1582 (its introduction year) and modified in
       order to support the year 0. This kind of calendar is somehow similar to the  astronomical
       gregorian  calendar except that the reference date is 0 for special coordinated time. This
       method presents the advantage to support negative time. It should  be  noted  that  the  0
       reference  does not means year 1BC since year 0 did not exist at that time (the concept of
       zero is fairly new) and more important, the date  expressed  in  the  form  1BC  generally
       refers  to the Julian calendar since the date is before 1582. Although, the class provides
       several methods to access the individual fields, it is  also  possible  to  get  a  string
       representation  that  conforms  to  ISO-8601  or to RFC-2822. With 1 argument, the date is
       initialized with the time clock specified as an integer argument. With 3 or  6  arguments,
       the date is expressed with its different elements.

       Predicate

              date-p

       Inheritance

              Time

       Constructors

              Date (none)
              The  Dateconstructor  creates  a  date object which is initialized with the current
              time.

              date (Integer)
              The Dateconstructor creates a date  object  which  is  initialized  with  the  time
              argument.

              Date (Integer Integer Integer)
              The  Dateconstructor  creates  a  date  object  which  is initialized with the date
              specific arguments, which are the year, the month and the day in the month.

              Date (Integer Integer Integer Integer Integer Integer)
              The Dateconstructor creates a date  object  which  is  initialized  with  the  date
              specific arguments, which are the year, the month, the day in the month, the hours,
              the minutes and the seconds.

       Methods

              year -> Integer (none|Boolean)
              The yearmethod returns the date year. the returned value is an absolute year  value
              which  can  be  negative.  Without  argument,  the  number  of years is computed in
              reference to the local time. With a boolean argument set to  true,  the  number  of
              years is computed in reference to the UTC time. If the argument is false, the local
              time is used.

              month -> Integer (none|Boolean)
              The monthmethod returns the month in the year. The returned value is the range 1 to
              12.  Without  argument,  the number of months is computed in reference to the local
              time. With a boolean argument set to true, the number  of  months  is  computed  in
              reference to the UTC time. If the argument is false, the local time is used.

              day -> Integer (none|Boolean)
              The  daymethod  returns  the day in the month. The returned value is the range 1 to
              31. Without argument, the number of days is computed  in  reference  to  the  local
              time.  With  a  boolean  argument  set  to  true, the number of days is computed in
              reference to the UTC time. If the argument is false, the local time is used.

              week-day -> Integer (none|Boolean)
              The week-daymethod returns the day in the week. The returned value is the  range  0
              to  6 in reference to Sunday. Without argument, the day is computed in reference to
              the local time. With a boolean argument  set  to  true,  the  day  is  computed  in
              reference to the UTC time. If the argument is false, the local time is used.

              year-day -> Integer (none|Boolean)
              The  year-daymethod  returns the day in the year. The returned value is the range 1
              to 366 in reference to January 1st.  Without  argument,  the  day  is  computed  in
              reference  to  the  local  time.  With  a  boolean argument set to true, the day is
              computed in reference to the UTC time. If the argument is false, the local time  is
              used.

              map-day -> String (none|Boolean)
              The  map-daymethod returns a formatted representation of the day. Without argument,
              the day is computed in reference to the local time. With a boolean argument set  to
              true,  the  day is computed in reference to the UTC time. If the argument is false,
              the local time is used.

              map-month -> String (none|Boolean)
              The map-monthmethod returns  a  formatted  representation  of  the  month.  Without
              argument,  the  month  is  computed  in reference to the local time. With a boolean
              argument set to true, the month is computed in reference to the UTC  time.  If  the
              argument is false, the local time is used.

              format -> String (none|Boolean)
              The  formatmethod returns a formatted representation of the date. Without argument,
              the time is computed in reference to the local time. With a boolean argument set to
              true,  the time is computed in reference to the UTC time. If the argument is false,
              the local time is used.

              to-iso -> String (none|Boolean)
              The to-isomethod returns a formatted representation of the  date  as  specified  by
              ISO-8601.  Without  argument,  the time is computed in reference to the local time.
              With a boolean argument set to true, the time is computed in reference to  the  UTC
              time. If the argument is false, the local time is used.

              to-web -> String (none)
              The  to-webmethod  returns  a  formatted representation of the date as specified by
              RFC-1123.

              to-rfc -> String (none|Boolean)
              The to-rfcmethod returns a formatted representation of the  date  as  specified  by
              RFC-2822.  Without  argument,  the time is computed in reference to the local time.
              With a boolean argument set to true, the time is computed in reference to  the  UTC
              time. If the argument is false, the local time is used.

              to-date -> String (none|Boolean)
              The  to-datemethod returns a formatted representation of the date only as specified
              by  ISO-8601.  With  this  method,  the  time  value  is  not   included   in   the
              representation.  Without  argument,  the date is computed in reference to the local
              time. With a boolean argument set to true, the date is computed in reference to the
              UTC time. If the argument is false, the local time is used.

              to-time -> String (none|Boolean)
              The to-timemethod returns a formatted representation of the time as returned by the
              Time formatmethod. Without argument, the time is computed in reference to the local
              time. With a boolean argument set to true, the time is computed in reference to the
              UTC time. If the argument is false, the local time is used.

              add-years -> none (Integer)
              The add-yearsmethod add one or several years to the current date.

              add-months -> none (Integer)
              The add-monthsmethod add one or several months to the current date.

       Options
       The Optionsclass is a simple class used to define and retrieve user options. The object is
       constructed  by  specifying which option is valid and how it behaves. The arguments can be
       passed to the object for subsequent analysis. An option can be either a unique option or a
       string  option. In this later case, multiple value for the same option can be accepted. In
       that case, the option is said to be a string vector option.  An  option  can  be  also  an
       option  list. I that case, the option is defined with a set of valid string. A list option
       is associated with a boolean flag for each string defined with that option.

       Predicate

              options-p

       Inheritance

              Object

       Constructors

              Options (none)
              The Optionsconstructor creates a default option object without a user message.

              Options (String)
              The Optionsconstructor creates an empty option object with a user message. The user
              message is used by the usagemethod.

       Methods

              reset -> none (none)
              The  resetmethod  resets  the  object  data  structure but do not remove the option
              descriptors. After a reset operation, the class is ready to  parse  another  string
              vector.

              usage -> none (none)
              The  usagemethod  prints  a  usage  message  with  a  user  message  and a one line
              description per option. removing all messages.

              parse -> Vector (none)
              The parsemethod parse a vector and fill the option data structure. The parse method
              is generally called with the interpreter argument vector.

              empty-p -> Boolean (none)
              The  empty-predicate  returns  true  if  the argument vector is empty. The argument
              vector is filled wit the string that are not options during the parsing process.

              add-list-option -> none (Character String String)
              The add-list-optionmethod creates a new list option. The list option is defined  by
              the  option  character  and  the  option  string.  The first argument is the option
              character. The second argument is the option list string. The third argument is the
              option  message. During the parsing process, the list option have a string argument
              which must match one string associated with the option character.

              get-unique-option -> Character String (none)
              The add-unique-optionmethod creates a new single option. The option is defined only
              by  its  character. The first argument is the option character. The second argument
              is the option message. During the parsing process, a unique option does not have an
              argument.

              add-string-option -> none (Character String)
              The add-string-optionmethod creates a new string option. The option is defined only
              by its character. The first argument is the option character. The  second  argument
              is  the  option  message. During the parsing process, a string option have a string
              argument.

              add-vector-option -> Character String (none)
              The add-vector-optionmethod creates a new vector option. The option is defined only
              by  its  character. The first argument is the option character. The second argument
              is the option message. During the parsing process, a vector option  have  a  string
              argument which is accumulated in a vector.

              set-user-message -> none (String)
              The set-user-messagemethod sets the global option user message. The user message is
              used by the usagemethod.

              get-user-message -> String (none)
              The get-user-messagemethod returns the global option user message. The user message
              is used by the usagemethod.

              get-unique-option -> Boolean (Character)
              The  get-unique-optionmethod  returns  the  flag  associated with an option. If the
              option has been detected during the parsing process, the method returns true.  This
              method  works  also  for string option or list option to indicate if the string has
              been set for that option. with a vector option, it is simpler to get the vector and
              check  for the vector length. The first argument is the option character to use for
              testing.

              get-string-option -> String (Character)
              The get-string-optionmethod returns the string associated with a string option.  In
              order  to  make  sure that a string option has been properly set during the parsing
              process, it is recommended to use the get-unique-optionmethod. The  first  argument
              is the option character to use for the string retrieval.

              get-vector-option -> Vector (Character)
              The get-vector-optionmethod returns the vector associated with a vector option. The
              first argument is the option character to use for the vector retrieval.

              get-vector-arguments -> Vector (none)
              The get-vector-argumentsmethod  returns  the  vector  arguments  built  during  the
              parsing process.

       Functions

              exit -> none (Integer)
              The  exitfunction  terminates the executing program with the exit code specified as
              the argument.

              sleep -> none (Integer)
              The sleepfunction pause the specific thread for a certain time. The  time  argument
              is expressed in milliseconds. This function returns nil.

              get-option -> String (Character)
              The  get-optionfunction  returns a formatted string equivalent to the system option
              as specified by the character argument.

              get-unique-id -> Integer (none)
              The get-unique-idfunction returns an unique integer number. The returned number  is
              unique across the session.

              get-pid -> Integer (none)
              The  get-pidfunction  returns the process identifier (pid). The returned value is a
              positive integer.

              get-env -> String (String)
              The get-envfunction returns the environment variable  associated  with  the  string
              argument. If the environment does not exist an exception is raised.

              get-host-fqdn -> String (none)
              The get-host-fqdnfunction returns the host fully qualified domain name. This is the
              combined host and domain names which is sometimes called the canonical name.

              get-domain-name -> String (none)
              The get-domain-namefunction returns the host domain name.

              get-host-name -> String (none)
              The get-host-namefunction returns the host name. If the host does not have a domain
              name, the host name is equal to the fully qualified domain name.

              get-user-name -> String (none)
              The get-user-namefunction returns the current user name.