sys(3)

✨ NAME ✨

sys — the standard system access module 💖

(btw this is sys(3) from the Library Functions Manual, and it's giving main character energy in the Afnix world, no cap.)

---

🌸 STANDARD SYSTEM ACCESS MODULE 🌸

okay so bestie, the Standard System Access module is an original implementation of a bunch of objects built to give you a specialized way to reach the underlying system. Most of those system accesses show up as functions that were designed to be as portable as humanly possible 🫶. One example of this? The time and date management objects, obviously. 💅

💫 Interpreter information 💫

The interpreter hands you a reserved set of names tied to the system platform. Example 0501.als shows off all the info you can get:

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 the major, minor and patch numbers, and they each mean something different, okay? 👑

• A change in the major number = a major change in the writing system.
• A change in the minor number = a major change in the interface or libraries.
• A change in the patch number = bug fixes.

All these 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. iykyk ✨

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

💜 Program information 💜

Program information is carried by two symbols that identify the program name and the official uri. The first one might actually 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 don't fit into any particular category. Not me calling them the "miscellaneous girlies" 💀

• 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

Now the details, because they matter:

The exit function terminates the program with an exit code specified as the argument. The sleep function pauses the specific thread for a certain time — and that time argument is expressed in milliseconds, so don't come at me with seconds ⏱️. 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, and heads up: that 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. Okay so what does proleptic even mean here? It means 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 the reference date is 0 for the writing system. The glow-up here? It supports negative time ✨.

It should be noted that the 0 reference does not mean year 1BC, since year 0 did not exist at that time (the concept of zero is fairly new, bestie) 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's also possible to get a string representation that conforms to ISO-8601 or to RFC-2822. Iconic.

💫 Time and date construction 💫

By default, a time instance of current time is constructed. This time reference is obtained from 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 — whose 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 constructors that accept the largest number of arguments, fr fr. 😭

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 arguments, 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's 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 uses 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 shows 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 latter case, multiple values for the same option can be accepted — and in that case, the option is said to be a string vector option. An option can also be an option list. In that case, the option is defined with a set of valid strings. A list option is associated with a boolean flag for each string defined with that option. So many flavors of option, honestly obsessed. 💅

💜 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 displays 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 are 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's possible to check the options 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

ok so if the option is a string option, then get-string-option hands you back the string chillin' with that option, periodt. quick side quest tho: you can also hit up get-unique-option to check whether that option was actually set during the parsing process. and if the option is a vector option? then get-vector-option is the one you want, bestie — it gives you back a vector with all the strings that matched that option. 💅

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

so in that lil example up there, the vector option i got set two times, which means the associated vector option has a length of 2. the string option e gets set to UTF-08, and for that option e, get-unique-option will return true. and finally, the vector argument gets filled with one string argument. slay, everything accounted for ✨

---

🌈 STANDARD SYSTEM ACCESS REFERENCE 🌈

🕰️ Time

The Time class is a lil simple class used to manipulate time. The AFNIX system operates with a special coordinated time that uses the reference of Jan 1st 0000 in a modified proleptic gregorian calendar. heads up: the time can be negative. Even though the class gives you a bunch of methods to access the time fields, you can also 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 creates a time object that's initialized with the current time. ✨
• Time (Integer) — the Time constructor creates a time object that's initialized with the time argument.
• Time (Integer Integer Integer) — the Time constructor creates a time object that's 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. useful for computing a time in the future, referencing the current time.
• add-hours -> none (Integer) — the add-hour method adds one or several hours to the current time value. same energy: future time, referenced off the current time. ⏳
• add-days -> none (Integer) — the add-days method adds one or several days to the current time value. future time, current time as the reference, you get it.
• set-time -> none (Integer) — the set-time method sets 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. returned value lives in 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. returned value is the range 0 to 23. (yes bestie, this one defaults local, not UTC — read it twice, it's not a typo 💀)
• format -> String (none|Boolean) — the format method returns a formatted representation of the time in the form 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 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 the reference date is 0 for special coordinated time. this method presents the advantage of supporting negative time. it should be noted that the 0 reference does not mean year 1BC, since year 0 did not exist at that time (the concept of zero is fairly new, bestie 😭) 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's 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 initialized with the current time.
• date (Integer) — the Date constructor creates a date object initialized with the time argument.
• Date (Integer Integer Integer) — the Date constructor creates a date object 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 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 gives you a formatted representation of the date. No argument? The time gets computed in reference to the local time. Hand it a boolean set to true and the time gets computed in reference to the UTC time. Pass false and it's local time again, bestie. 💅
• to-iso -> String (none|Boolean) — the to-iso method gives you a formatted representation of the date exactly as ISO-8601 specifies it. No argument? Local time. Boolean true? UTC time. Boolean false? Local time. Same little dance every time, and honestly? Consistent queen. ✨
• to-web -> String (none) — the to-web method gives you a formatted representation of the date as specified by RFC-1123. That's it, that's the whole vibe. 🦋
• to-rfc -> String (none|Boolean) — the to-rfc method gives you a formatted representation of the date as specified by RFC-2822. No argument = local time. true = UTC time. false = local time. Periodt. 🎀
• to-date -> String (none|Boolean) — the to-date method gives you a formatted representation of the date only, as specified by ISO-8601. And listen — with this one, the time value is not included in the representation. Just the date. No argument = the date is computed in reference to the local time, true = in reference to the UTC time, false = local time. 🌸
• to-time -> String (none|Boolean) — the to-time method gives you a formatted representation of the time exactly as returned by the Time format method. No argument = local time, true = UTC time, false = local time. Go off. ⭐
• add-years -> none (Integer) — the add-years method adds one or several years to the current date. Time travel but make it one integer at a time. 💜
• add-months -> none (Integer) — the add-months method adds one or several months to the current date. Same energy, different unit. 🌈

---

🎀 Options 🎀

The Options class is a simple little class used to define and retrieve user options. The object gets constructed by specifying which option is valid and how it behaves. The arguments can then be passed to the object for subsequent analysis.

An option can be either a unique option or a string option. In this latter case, multiple values for the same option can be accepted — and when that happens, the option is said to be a string vector option. An option can also be an option list. In that case, the option is defined with a set of valid strings, and a list option is associated with a boolean flag for each string defined with that option. It's giving very organized, very demure. 🫶

🔍 Predicate 🔍

options-p

🧬 Inheritance 🧬

Object

🌸 Constructors 🌸

• Options (none) — the Options constructor creates a default option object without a user message. Simple. Clean. No notes. 💅
• Options (String) — the Options constructor creates an empty option object with a user message. That user message is what the usage method uses later. ✨

💖 Methods 💖

• reset -> none (none) — the reset method resets the object data structure, but it does not remove the option descriptors. After a reset operation the class is ready to parse another string vector. Fresh start, same personality. 🦋
• 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 parses a vector and fills the option data structure. It's generally called with the interpreter argument vector, which is very main character of it. 👑
• empty-p -> Boolean (none) — the empty- predicate returns true if the argument vector is empty. That argument vector gets filled with the strings 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. First argument = the option character. Second argument = the option list string. Third argument = the option message. During the parsing process, the list option has a string argument which must match one string associated with the option character. No matching, no entry. 🙈
• get-unique-option -> Character String (none) — the add-unique-option method creates a new single option. The option is defined only by its character. First argument = the option character. Second argument = the option message. During the parsing process, a unique option does not have an argument. (Yes the header says get-unique-option while the prose says add-unique-option — we report, we don't judge. 💀)
• add-string-option -> none (Character String) — the add-string-option method creates a new string option. The option is defined only by its character. First argument = the option character. Second argument = the option message. During the parsing process, a string option does 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. First argument = the option character. Second argument = the option message. During the parsing process, a vector option has a string argument which gets accumulated in a vector. Stack 'em up, bestie. 🌈
• set-user-message -> none (String) — the set-user-message method sets the global option user message. That user message is used by the usage method. 💜
• get-user-message -> String (none) — the get-user-message method returns the global option user message. Again: that user message is used by the usage method. We love a recurring theme. ⭐
• get-unique-option -> Boolean (Character) — the get-unique-option method returns the flag associated with an option. If the option was detected during the parsing process, the method returns true. This method also works for a string option or a list option, to indicate whether the string has been set for that option. With a vector option it's simpler to get the vector and check the vector length. First argument = 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. To make sure a string option was properly set during the parsing process, it is recommended to use the get-unique-option method. First argument = 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. First argument = 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. All the leftovers, collected and handed to you on a platter. 🎀

🌟 Functions 🌟

• exit -> none (Integer) — the exit function terminates the executing program with the exit code specified as the argument. Dramatic exit, every single time. 💅
• sleep -> none (Integer) — the sleep function pauses the specific thread for a certain time. The time argument is expressed in milliseconds. This function returns nil. Nap time, but scheduled. 😴
• 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 a unique integer number. The returned number is unique across the session. One of a kind, fr fr. 👑
• 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-fqdn -> String (none) — the get-host-fqdn function 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-name function returns the host domain name. ⭐
• get-host-name -> String (none) — the get-host-name function returns the host name. If the host does not have a domain name, the host name is equal to the fully qualified domain name. Bestie said "I contain multitudes." ✨
• get-user-name -> String (none) — the get-user-name function returns the current user name. Yes, you. Hi. 💖

---

and that's a wrap on sys(3), bestie 🎀 this one's from the AFNIX Module manual set, tagged AFNIX, section sys(3) — go forth and parse, you absolute icon. 🫶💅✨