afnix-sys

sys(3)                            AFNIX Module                            sys(3)



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.



AFNIX                              2018-07-20                             sys(3)