13
13
<!-- = incidental or special damages arising in any way out of the use = -->
14
14
<!-- = of this software. = -->
15
15
<!-- ====================================================================== -->
16
<!-- = copyright (c) 1999-2007 - amaury darsch = -->
16
<!-- = copyright (c) 1999-2011 - amaury darsch = -->
17
17
<!-- ====================================================================== -->
19
19
<chapter module="sys" number="1">
20
20
<title>Introduction</title>
23
This chapter covers the system services available in the
24
<afnix/> standard system service module. The basic operations that are
25
embedded in the interpreter gives system information. Complex
26
information, like the system time are provided via specific
31
All <afnix/> system service objects are located in the
32
<code>afnix-sys</code> module. This module must be loaded prior
33
any operation. Multiple calls to the module initialization routine
34
are harmless. The interpreter method <code>module</code> loads a
35
specific module by name. When the module has been loaded, the
36
object are available in the <code>afnix:sys</code> nameset.
40
interp:library "afnix-sys"
23
This chapter covers the system services available in the
24
standard system module.
43
27
<!-- interpreter information -->
45
29
<title>Interpreter information</title>
48
The <afnix/> interpreter provides a set reserved names that are
49
related to the system platform. Example <file>0501.als</file>
50
demonstrates the available information.
32
The interpreter provides a set reserved names that are
33
related to the system platform. Example <file>0501.als</file>
34
demonstrates the available information.
56
operating system name : linux
57
operating system type : unix
58
afnix official uri : http://www.afnix.org
40
operating system name : linux
41
operating system type : unix
42
afnix official uri : http://www.afnix.org
61
45
<!-- interpreter version -->
63
47
<title>Interpreter version</title>
66
The interpreter version is identified by 3 numbers called
67
<em>major</em>, <em>minor</em> and <em>patch</em> numbers. A
68
change in the major number represents a major change in the
69
<afnix/>language. The minor number indicates a major change in
70
the interface or libraries. A change in the patch number
71
indicates bug fixes. All values are accessed via the interpreter
72
itself. The <code>major-version</code>,
73
<code>minor-version</code>, <code>patch-version</code>
74
symbols are bound to these values.
50
The interpreter version is identified by 3 numbers called
51
<em>major</em>, <em>minor</em> and <em>patch</em> numbers. A
52
change in the major number represents a major change in the
53
writing system. The minor number indicates a major change in
54
the interface or libraries. A change in the patch number
55
indicates bug fixes. All values are accessed via the interpreter
56
itself. The <code>major-version</code>,
57
<code>minor-version</code>, <code>patch-version</code>
58
symbols are bound to these values.
78
println "major version number : " interp:major-version
79
println "minor version number : " interp:minor-version
80
println "patch version number : " interp:patch-version
62
println "major version number : " interp:major-version
63
println "minor version number : " interp:minor-version
64
println "patch version number : " interp:patch-version
120
104
<title>System services</title>
123
The <em>system services</em> module provides various functions
124
that cannot be classified into any particular category.
107
The <em>system services</em> module provides various functions
108
that cannot be classified into any particular category.
128
<title>System services functions</title>
129
<tr><th>Function</th><th>Description</th></tr>
130
<tr><td>exit</td> <td>terminate with an exit code</td></tr>
131
<tr><td>sleep</td> <td>pause for a certain time</td></tr>
132
<tr><td>get-random</td> <td>return a random integer number</td></tr>
133
<tr><td>get-random-real</td> <td>return a random real number</td></tr>
134
<tr><td>get-pid</td> <td>get the process identifier</td></tr>
135
<tr><td>get-env</td> <td>get an environment variable</td></tr>
136
<tr><td>get-host-name</td> <td>get the host name</td></tr>
137
<tr><td>get-user-name</td> <td>get the user name</td></tr>
112
<title>System services functions</title>
113
<tr><th>Function</th><th>Description</th></tr>
114
<tr><td>exit</td> <td>terminate with an exit code</td></tr>
115
<tr><td>sleep</td> <td>pause for a certain time</td></tr>
116
<tr><td>get-pid</td> <td>get the process identifier</td></tr>
117
<tr><td>get-env</td> <td>get an environment variable</td></tr>
118
<tr><td>get-host-name</td> <td>get the host name</td></tr>
119
<tr><td>get-user-name</td> <td>get the user name</td></tr>
141
The <code>exit</code> function terminates the program with an exit
142
code specified as the argument. The <code>sleep</code> function
143
pause the specific thread for a certain time. The time argument is
144
expressed in milliseconds. The <code>get-random</code> function
145
returns a random integer number. The <code>get-random-real</code>
146
returns a random real number. The <code>get-pid</code> function
147
returns the process identifier. The <code>get-env</code> function
148
returns the environment variable associated with the string argument.
149
The <code>get-host-name</code> function returns the host name. The
150
host name can be either a simple name or a canonical name with its
151
domain, depending on the system configuration. The
152
<code>get-user-name</code> function returns the current user
123
The <code>exit</code> function terminates the program with an exit
124
code specified as the argument. The <code>sleep</code> function
125
pause the specific thread for a certain time. The time argument is
126
expressed in milliseconds. The <code>get-pid</code> function
127
returns the process identifier. The <code>get-env</code> function
128
returns the environment variable associated with the string argument.
129
The <code>get-host-name</code> function returns the host name. The
130
host name can be either a simple name or a canonical name with its
131
domain, depending on the system configuration. The
132
<code>get-user-name</code> function returns the current user
159
139
<title>Time and date</title>
162
The <code>Time</code> and <code>Date</code> classes are classes
163
designed to manipulate time and date. The <afnix/> system operates
164
with the <afnix/> time coordinated or <em>ATC</em> which uses the
165
reference of Jan 1st 0000 in a modified proleptic gregorian
166
calendar. This proleptic feature means that the actual calendar
167
(gregorian) is extended beyond year 1582 (its introduction year)
168
and modified in order to support the year 0. This kind of calendar
169
is somehow similar to the astronomical gregorian calendar except
170
that the reference date is 0 for the atc system. This method
171
presents the advantage to support negative time. It should be
172
noted that the 0 reference does not means year 1BC since year 0 did
173
not exist at that time (the concept of zero is fairly new) and more
174
important, the date expressed in the form 1BC generally refers to
175
the Julian calendar since the date is before 1582. Although, the class
176
provides several methods to access the time and date fields, it is also
177
possible to get a string representation that conforms to ISO-8601
142
The <code>Time</code> and <code>Date</code> classes are classes
143
designed to manipulate time and date. The writing system operates
144
with a special coordinated time which uses the
145
reference of Jan 1st 0000 in a modified proleptic Gregorian
146
calendar. This proleptic feature means that the actual calendar
147
(Gregorian) is extended beyond year 1582 (its introduction year)
148
and modified in order to support the year 0. This kind of calendar
149
is somehow similar to the astronomical Gregorian calendar except
150
that the reference date is 0 for the writing system. This method
151
presents the advantage to support negative time. It should be
152
noted that the 0 reference does not means year 1BC since year 0 did
153
not exist at that time (the concept of zero is fairly new) and more
154
important, the date expressed in the form 1BC generally refers to
155
the Julian calendar since the date is before 1582. Although, the class
156
provides several methods to access the time and date fields, it is also
157
possible to get a string representation that conforms to ISO-8601
181
161
<!-- time and date construction -->
183
163
<title>Time and date construction</title>
186
By default, a time instance of current time is constructed. This
187
time reference is obtained form the machine time and adjusted for
188
the <afnix/> internal representation. One feature of this class
189
is that the time instance does not have to be bounded with 24
190
hours. The time stored is the absolute time, which should be
191
considered like a temporal reference -- or date -- those origin
192
is 0 in some calendar representation.
196
const time (afnix:sys:Time)
197
assert true (afnxi:sys:time-p time)
201
A simple time representation can also be built by hours, minutes
202
and seconds. In this case, the time is a time definition at day
203
0 in the reference calendar.
207
const time (afnix:sys:Time 12 23 54)
211
By default a date instance of the current date is constructed.
212
The current date is computed from the machine time and expressed
213
in a particular calendar. By default, the <afnix/> engine uses a
214
special gregorian calendar as explained before. The important
215
point here s that the date will show up like the user should
220
const date (afnix:sys:Date)
221
assert true (afnix:sys:date-p date)
225
A date instance can also be built with an absolute time expressed
226
in seconds or with specific elements. with one argument, the
227
date is expressed in seconds since the origin. Since the
228
<afnix/> internal representation is 64 bits, the date room is
229
quite large. For example, the absolute time to represent Jan 1st
230
1970 is 62167219200 seconds. This <em>epoch</em> is used to
231
adjust the system time on some UNIX system. Another way to
232
create a specific date is to use the date descriptor by year,
233
month and day. With 6 arguments, the time components can also be
234
given. This makes <code>Date</code> one of the constructor that
235
accept the largest number of arguments.
239
const date (afnix:sys:Date 1789 7 14 16 0 0)
240
assert true (afnix:sys:date-p date)
244
In the previous example, at 17:00 local time, 16:00Z although
245
the concept of time zone was not formalized, the Bastille
246
surrenders on July 14 1789. This example shows that extreme care
247
should be used when dealing with old dates. Note that a simpler
248
form could have been used to set that date. With 3 argument, the
249
date is set at time 00:00:00Z.
253
const date (afnix:sys:Date 1789 7 14)
254
assert true (afnix:sys:date-p date)
166
By default, a time instance of current time is constructed. This
167
time reference is obtained form the machine time and adjusted for
168
the internal representation. One feature of this class
169
is that the time instance does not have to be bounded with 24
170
hours. The time stored is the absolute time, which should be
171
considered like a temporal reference -- or date -- those origin
172
is 0 in some calendar representation.
176
const time (afnix:sys:Time)
177
assert true (afnxi:sys:time-p time)
181
A simple time representation can also be built by hours, minutes
182
and seconds. In this case, the time is a time definition at day
183
0 in the reference calendar.
187
const time (afnix:sys:Time 12 23 54)
191
By default a date instance of the current date is constructed.
192
The current date is computed from the machine time and expressed
193
in a particular calendar. By default, the engine uses a
194
special Gregorian calendar as explained before. The important
195
point here s that the date will show up like the user should
200
const date (afnix:sys:Date)
201
assert true (afnix:sys:date-p date)
205
A date instance can also be built with an absolute time expressed
206
in seconds or with specific elements. with one argument, the
207
date is expressed in seconds since the origin. Since the
208
internal representation is 64 bits, the date room is
209
quite large. For example, the absolute time to represent Jan 1st
210
1970 is 62167219200 seconds. This <em>epoch</em> is used to
211
adjust the system time on some UNIX system. Another way to
212
create a specific date is to use the date descriptor by year,
213
month and day. With 6 arguments, the time components can also be
214
given. This makes <code>Date</code> one of the constructor that
215
accept the largest number of arguments.
219
const date (afnix:sys:Date 1789 7 14 16 0 0)
220
assert true (afnix:sys:date-p date)
224
In the previous example, at 17:00 local time, 16:00Z although
225
the concept of time zone was not formalized, the Bastille
226
surrenders on July 14 1789. This example shows that extreme care
227
should be used when dealing with old dates. Note that a simpler
228
form could have been used to set that date. With 3 argument, the
229
date is set at time 00:00:00Z.
233
const date (afnix:sys:Date 1789 7 14)
234
assert true (afnix:sys:date-p date)
260
240
<title>Time and date representation</title>
263
Except for some special applications -- like the cookie maximum
264
age --, the date representation is quite standard and can be
265
found either in the form of ISO-8601 or RFC-2822.
269
const time (afnix:sys:Time 12 44 55)
270
println (time:format) # 12:44:55
271
println (time:to-iso) # 14:44:55
272
println (time:to-rfc) # 14:44:55 +0200
276
in the first form, the time is represented naturally by hour,
277
minutes and seconds. By default, it is the local time that is
278
given. With a flag set to true, the UTC time is displayed. In
279
the second form, the time is displayed in the ISO-8601 form
280
which is the same as before. In the third form, the time is
281
displayed in the RFC-2822 form. This form is always expressed
282
locally with the timezone difference associated with it. It
283
shall be noted that the ISO-8601 mandate to sue the suffix 'Z'
284
for the zulu time. This is the difference when using the
285
<code>true</code> flag with the <code>format</code> and
286
<code>to-iso</code> methods.
290
println (time:format true) # 12:44:55
291
println (time:to-iso true) # 12:44:55Z
295
The date representation also operates with 3 methods, namely
296
<code>format</code>, <code>to-iso</code> and
297
<code>to-rfc</code>. For example, if the time is 12:00 in Paris
298
on July 14th 2000, the date will be displayed like below.
302
const date (afnix:sys:Date 2000 7 14 12 0 0)
303
println (date:format) # Fri Jul 14 07:00:00 2000
304
println (date:to-iso) # 2000-07-14T07:00:00
305
println (date:to-rfc) # Fri, 14 Jul 2000 07:00:00 -0500
309
The example show the local time. With UTC display, only the
310
first two methods can be used.
314
const date (afnix:sys:Date 2000 7 14 12 0 0)
315
println (date:format true) # Fri Jul 14 12:00:00 2000
316
println (date:to-iso true) # 2000-07-14T12:00:00Z
243
Except for some special applications -- like the cookie maximum
244
age --, the date representation is quite standard and can be
245
found either in the form of ISO-8601 or RFC-2822.
249
const time (afnix:sys:Time 12 44 55)
250
println (time:format) # 12:44:55
251
println (time:to-iso) # 14:44:55
252
println (time:to-rfc) # 14:44:55 +0200
256
in the first form, the time is represented naturally by hour,
257
minutes and seconds. By default, it is the local time that is
258
given. With a flag set to true, the UTC time is displayed. In
259
the second form, the time is displayed in the ISO-8601 form
260
which is the same as before. In the third form, the time is
261
displayed in the RFC-2822 form. This form is always expressed
262
locally with the timezone difference associated with it. It
263
shall be noted that the ISO-8601 mandate to use the suffix 'Z'
264
for the zulu time. This is the difference when using the
265
<code>true</code> flag with the <code>format</code> and
266
<code>to-iso</code> methods.
270
println (time:format true) # 12:44:55
271
println (time:to-iso true) # 12:44:55Z
275
The date representation also operates with 3 methods, namely
276
<code>format</code>, <code>to-iso</code> and
277
<code>to-rfc</code>. For example, if the time is 12:00 in Paris
278
on July 14th 2000, the date will be displayed like below.
282
const date (afnix:sys:Date 2000 7 14 12 0 0)
283
println (date:format) # Fri Jul 14 07:00:00 2000
284
println (date:to-iso) # 2000-07-14T07:00:00
285
println (date:to-rfc) # Fri, 14 Jul 2000 07:00:00 -0500
289
The example show the local time. With UTC display, only the
290
first two methods can be used.
294
const date (afnix:sys:Date 2000 7 14 12 0 0)
295
println (date:format true) # Fri Jul 14 12:00:00 2000
296
println (date:to-iso true) # 2000-07-14T12:00:00Z
323
303
<title>Options parsing</title>
326
The <code>Options</code> class provides a convenient mechanism to
327
define a set of options and to parse them in a simple way. The
328
object is constructed by specifying which option is valid
329
and how it behaves. The arguments can be passed to the object
330
for subsequent analysis. An option can be either a unique option
331
or a string option. In this later case, multiple value for the
332
same option can be accepted. In that case, the option is said to
333
be a string vector option. An option can be also an option list. I
334
that case, the option is defined with a set of valid string. A
335
list option is associated with a boolean flag for each string defined
306
The <code>Options</code> class provides a convenient mechanism to
307
define a set of options and to parse them in a simple way. The
308
object is constructed by specifying which option is valid
309
and how it behaves. The arguments can be passed to the object
310
for subsequent analysis. An option can be either a unique option
311
or a string option. In this later case, multiple value for the
312
same option can be accepted. In that case, the option is said to
313
be a string vector option. An option can be also an option list. I
314
that case, the option is defined with a set of valid string. A
315
list option is associated with a boolean flag for each string defined
339
319
<!-- option creation -->
361
341
<title>Options definition</title>
364
The process of defining options is done by specifying the option
365
character, eventually an option string and an option message.
344
The process of defining options is done by specifying the option
345
character, eventually an option string and an option message.
369
options:add-unique-option 'h' "print this help message"
370
options:add-unique-option 'v' "print system version"
371
options:add-vector-option 'i' "add a resolver path"
372
options:add-string-option 'e' "force the encoding mode"
373
options:add-list-option 'f' "assert" "enable assertion checks"
374
options:add-list-option 'f' "nopath" "do not set initial path"
349
options:add-unique-option 'h' "print this help message"
350
options:add-unique-option 'v' "print system version"
351
options:add-vector-option 'i' "add a resolver path"
352
options:add-string-option 'e' "force the encoding mode"
353
options:add-list-option 'f' "assert" "enable assertion checks"
354
options:add-list-option 'f' "nopath" "do not set initial path"
378
The above example shows the option descriptors for the <afnix/>
379
interpreter. Since <option>i</option> is a vector option,
380
multiple occurrences of that option is allowed. It shall be noted
381
that the list option <option>f assert</option> is a debug option. This
382
means that this option is always set when the program is
383
compiled in debug mode.
358
The above example shows the option descriptors for the
359
interpreter. Since <option>i</option> is a vector option,
360
multiple occurrences of that option is allowed. It shall be noted
361
that the list option <option>f assert</option> is a debug option. This
362
means that this option is always set when the program is
363
compiled in debug mode.
389
369
<title>Options parsing and retrieval</title>
392
A string vector is parsed with the <code>parse</code>
393
method. Generally, the vector argument is the interpreter
394
argument vector defined in the qualified name
395
<code>interp:args</code>. When the vector has been successfully
396
parsed, it is possible to check the option that have been set.
372
A string vector is parsed with the <code>parse</code>
373
method. Generally, the vector argument is the interpreter
374
argument vector defined in the qualified name
375
<code>interp:args</code>. When the vector has been successfully
376
parsed, it is possible to check the option that have been set.
400
options:parse (Vector "-h")
401
if (options:get-unique-option 'h') {
380
options:parse (Vector "-h")
381
if (options:get-unique-option 'h') {
408
In the above example, the option vector is parsed with the
409
<code>parse</code> method. The <code>get-unique-option</code>
410
method returns true for the <option>h</option> thus triggering the
411
display of the usage message.
415
usage: axi [options] [file [arguments]]
416
[h] print this help message
417
[v] print system version
418
[i path] add a resolver path
419
[e mode] force the encoding mode
420
[f assert] enable assertion checks
421
[f nopath] do not set initial path
425
If the option is a string option, the
426
<code>get-string-option</code> will return the string associated
427
with that option. It shall be noted that the
428
<code>get-unique-option</code> method can be used to check if
429
the option has been set during the parsing process. If the
430
option is a vector option, the <code>get-vector-option</code>
431
method is more appropriate. In this case, a vector is returned
432
with all strings matching this option.
436
options:parse (Vector "-i" "../" "-i" "../.." -e "UTF-08" "hello")
388
In the above example, the option vector is parsed with the
389
<code>parse</code> method. The <code>get-unique-option</code>
390
method returns true for the <option>h</option> thus triggering the
391
display of the usage message.
395
usage: axi [options] [file [arguments]]
396
[h] print this help message
397
[v] print system version
398
[i path] add a resolver path
399
[e mode] force the encoding mode
400
[f assert] enable assertion checks
401
[f nopath] do not set initial path
405
If the option is a string option, the
406
<code>get-string-option</code> will return the string associated
407
with that option. It shall be noted that the
408
<code>get-unique-option</code> method can be used to check if
409
the option has been set during the parsing process. If the
410
option is a vector option, the <code>get-vector-option</code>
411
method is more appropriate. In this case, a vector is returned
412
with all strings matching this option.
416
options:parse (Vector "-i" "../" "-i" "../.." -e "UTF-08" "hello")
440
In the previous example, the vector option <option>i</option> is
441
set two times. The associated vector option has therefore a
442
length of 2. The string option <option>e</option> is set to
443
<tt>UTF-08</tt>. For this option <option>e</option>, the
444
<code>get-unique-option</code> method will return true. Finally,
445
the vector argument is filled with one string argument.
420
In the previous example, the vector option <option>i</option> is
421
set two times. The associated vector option has therefore a
422
length of 2. The string option <option>e</option> is set to
423
<tt>UTF-08</tt>. For this option <option>e</option>, the
424
<code>get-unique-option</code> method will return true. Finally,
425
the vector argument is filled with one string argument.
added
removed
src/mod/sys/doc/chapter-1.xml
