# Standard system services reference

This appendix is a reference of the standard system services module.

## Standard system services module

Symbol | Description
--- | ---
afnix-sys | module
afnix:sys | nameset

Time

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

time-p
Object
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.

add
none
Integer

The `add` method adds the time argument in seconds to the current time value This method is useful to compute a time in the future, in reference to the current time.

add-minutes
none
Integer

The `add-minutes` method adds one or several minutes to the current time value. This method is useful to compute a time in the future, in reference to the current time.

add-hours
none
Integer

The `add-hour` method adds one or several hours to the current time value. This method is useful to compute a time in the future, in reference to the current time.

add-days
none
Integer

The `add-days` method adds one or several days to the current time value. This method is useful to compute a time in the future, in reference to the current time.

set-time
none
Integer

The `set-time` method set the absolute time in seconds.

get-time
Integer
none

The `get-time` method returns absolute time in seconds

seconds
Integer
none|Boolean

The `seconds` method returns the number of seconds after the minute. Without argument, the number of seconds is computed in reference to the local time. With a boolean argument set to `true`, the number of seconds is computed in reference to the UTC time. If the argument is false, the local time is used. The returned value is the range 0 to 60.

minutes
Integer
none|Boolean

The `minutes` method returns the number of minutes after the hour. Without argument, the number of minutes is computed in reference to the local time. With a boolean argument set to `true`, the number of minutes is computed in reference to the UTC time. If the argument is false, the local time is used. The returned value is the range 0 to 60.

hours
Integer
none|Boolean

The `hours` method returns the number of hours since midnight. Without argument, the number of hours is computed in reference to the local time. With a boolean argument set to `true`, the number of hours is computed in reference to the UTC time. If the argument is false, the local time is used. The returned value is the range 0 to 23.

format
String
none|Boolean

The `format` method returns a formatted representation of the time in the form of hh:mm:ss. Without argument, the time is computed in reference to the local time. With a boolean argument set to `true`, the time is computed in reference to the UTC time. If the argument is false, the local time is used.

to-iso
String
none|Boolean

The `to-iso` method returns a formatted representation of the time as specified by ISO-8601. Without argument, the time is computed in reference to the local time. With a boolean argument set to `true`, the time is computed in reference to the UTC time. If the argument is false, the local time is used.

to-rfc
String
none

The `to-rfc` method returns a formatted representation of the time as specified by RFC-2822. The time is computed in reference to the local time.

Date

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

date-p
Time
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.

year
Integer
none

The `year` method returns the date year. the returned value is an absolute year value which can be negative.

month
Integer
none

The `month` method returns the month in the year. The returned value is the range 1 to 12.

day
Integer
none

The `day` method returns the day in the month. The returned value is the range 1 to 31.

week-day
Integer
none

The `week-day` method returns the day in the week. The returned value is the range 0 to 6 in reference to Sunday.

year-day
Integer
none

The `year-day` method returns the day in the year. The returned value is the range 1 to 366 in reference to January 1st.

map-day
String
none

The `map-day` method returns a formatted representation of the day.

map-month
String
none

The `map-month` method returns a formatted representation of the month.

format
String
none|Boolean

The `format` method returns a formatted representation of the date. Without argument, the time is computed in reference to the local time. With a boolean argument set to `true`, the time is computed in reference to the UTC time. If the argument is false, the local time is used.

to-iso
String
none|Boolean

The `to-iso` method returns a formatted representation of the date as specified by ISO-8601. Without argument, the time is computed in reference to the local time. With a boolean argument set to `true`, the time is computed in reference to the UTC time. If the argument is false, the local time is used.

to-rfc
String
none

The `to-rfc` method returns a formatted representation of the date as specified by RFC-2822. The time is computed in reference to the local time.

to-date
String
none

The `to-date` method returns a formatted representation of the date only as specified by ISO-8601. With this method, the time value is not included in the representation.

to-time
String
none|Boolean

The `to-time` method returns a formatted representation of the time as returned by the `Time format` method.

get-base-day
Integer
none

The `get-base-day` method returns the absolute time rounded to the beginning of the day.

add-years
none
Integer

The `add-years` method add one or several years to the current date.

add-months
none
Integer

The `add-months` method add one or several months to the current date.

Options

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

options-p
Object
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.

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.

exit
none
Integer

The `exit` function terminates the executing program with the exit code specified as the argument.

sleep
none
Integer

The `sleep` function pause the specific thread for a certain time. The time argument is expressed in milliseconds. This function returns nil.

get-option
String
Character

The `get-option` function returns a formatted string equivalent to the system option as specified by the character argument.

get-random
Integer
none|Integer

The `get-random` function returns a random integer number. Without argument, the integer range is machine dependent. With one integer argument, the resulting integer number is less than the specified maximum bound.

get-random-real
Real
none

The `get-random-real` function returns a random real number between 0.0 and 1.0.

get-unique-id
Integer
none

The `get-unique-id` function returns an unique integer number. The returned number is unique across the session.

get-pid
Integer
none

The `get-pid` function returns the process identifier (pid). The returned value is a positive integer.

get-env
String
String

The `get-env` function returns the environment variable associated with the string argument. If the environment does not exist an exception is raised.

get-host-name
String
none

The `get-host-name` function returns the host name. The host name can be either a simple name or a canonical name with its domain, depending on the system configuration.

get-user-name
String
none

The `get-user-name` function returns the current user name.