NAME
pim - standard personnal information manager module
STANDARD PIM SERVICES
This chapter covers the pim facilities available in the standard
personal information management module. The basic operations are
related to time management. All AFNIX standard pim objects are
located in the afnix-pim module. This module must be loaded prior any
operation. Multiple calls to the module initialization routine are
harmless. The interpreter method module loads a specific module by
name. When the module has been loaded, the object are available in the
afnix:pim nameset.
interp:library "afnix-pim"
General concepts
The afnix-pim provides the support for manipulating information
management data. Information data are generally personal information
that are used to manage time and constraints. The concepts of agenda
and appointer fall into this category.
Slot
The concept of slot is central in the pim module. A slot is a
combination of time and duration. A slot is allocated by an appointer
to indicate the next available slot. For an agenda, the concept of slot
can be derived to describe an appointment.
Appointer
An appointer is a slot generator. The appointer can be designed to
respond automatically with respect to a certain number of rules. Common
rules found in an appointer are closed days like week-end and time
allocation period.
Assistant
An assistant is a combination of pim object like appointers. An
assistant can be used for example, to manage several appointers.
Appointer operations
The Appointer class is designed to allocate slots with respect to a
certain duration or from a certain time with a duration. The appointer
operates with rules which describe the operating calendar and daily
schedule. such rules are designed to mimic real-life situations like
week-end blocked days or Christmas vacation day.
Slot allocation
A slot is allocated with the get-slot method. This method is common to
the Appointer and Assistant classes.
# allocate a 1 hour slot
const slot (appt:get-slot 3600)
In the example above, a 1 hour slot is allocated at the current
appointer time. Note that the time and duration are always given in
seconds. If the slot needs to be allocated starting at a certain time,
the 2 arguments form can be used.
# allocate a 1 hour slot starting at 2AM
const slot (appt:get-slot 7200 3600)
In the presence of an Assistant object the get-slot is the same but
selects the appropriate appointer with the help of an internal index
which rotated after each call. This method permits an equal
distribution for all appointers within an assistant.
Appointer rules
There are basically, two types of appointer’s rules. The first type of
rule is used for blocking a day as a whole. The second type of rule is
designed to describe valid periods of allocation time. The first type
of rules is called the and rules since all rules must be valid in order
to allocate a slot at the requested time. The second type is a called
the or rules since only one rule needs to be valid in order to allocate
a slot.
# create a reference appointer
const appt (afnix:pim:Appointer)
# add a saturday and sunday blocked day rule
appt:set-blocked-day 6
appt:set-blocked-day 0
# set the special days
appt:set-special-day 1 1
appt:set-special-day 12 25
The example above defines an appointer object. The first 2 rules
defines Saturday and Sunday as blocked days. The other 2 rules, defines
Jan 1st and Dec 25th as special days. No slot can be allocated in a
blocked or special day.
# set a valid block time between 8AM to 12AM and 2PM to 6PM
const ambt (* 3600 8)
const amet (* 3600 12)
const pmbt (* 3600 14)
const pmet (* 3600 18)
appt:set-valid-block-time ambt amet
appt:set-valid-block-time pmbt pmet
the above example defines two valid periods for allocating time. The
first period runs from 8AM to 12AM and the second one runs from 2PM to
6PM. Note that the time is also expressed in second. The time arguments
are always rounded to the maximum number of seconds per day.
Assistant operations
An assistant object is build by adding object to it. In general, a
reference object is created, and several of them are added to the
assistant by cloning the reference object.
Assistant integration
Once an assistant object has been created, the object can be added by
cloning.
# create an assistant
const name "Mr Smith"
const info "The super assistant"
const asst (afnix:pim:Assistant name info)
# create a reference appointer
const appt (afnix:pim:Appointer)
# add 2 appointers by cloning
asst:add-appointer (appt:clone)
asst:add-appointer (appt:clone)
In the case of an Appointer object, the appointer is cloned with all
its rules attached to it. This method is particularly useful when an
assistant needs to be setup for several person that shares the same
calendar.
STANDARD PIM REFERENCE
This appendix is a reference of the AFNIX standard pim module.
Symbol Description
afnix-pim module
afnix:pim nameset
Slot
The Slot class is a base class designed to handle a basic time slot
event. The class is defined with a date and a duration. The slot class
is primarily used to build an agenda.
Predicate
slot-p
Inheritance
Object
Constructors
Slot (none)
The Slot constructor creates an empty slot initialized at time 0
with duration 0.
Slot (Integer Integer)
The Slot constructor creates a slot with a time and duration.
The first argument is the slot time. The second argument is the
slot duration.
Methods
reset -> none (none)
The reset method reset the slot to time 0 with duration 0.
set-time -> none (Integer)
The set-time method sets the slot time.
get-time -> Integer (none)
The get-time method returns the slot time.
set-duration -> none (Integer)
The set-duration method sets the slot duration.
get-duration -> Integer (none)
The get-duration method returns the slot duration.
set-slot -> none (Integer Integer)
The set-slot method sets the slot time and duration at once. The
first argument is the slot time. The second argument is the slot
duration.
Appointer
The Appointer class is a class design to allocate time slot in a
calendar in order to fill an agenda. The appointer do not store the
slot but rather acts as a generator. the appointer algorithm operates
with rules that permits to allocate the next available slot. The basic
rules permits to define regular blocked days and special blocked days.
Another rule permits to define an operating time period. Multiple time
periods are allowed. A maximum daily slots rule is also available.
Predicate
appointer-p
Inheritance
Object
Constructors
Appointer (none)
The Appointer constructor creates a default appointer
initialized at time 0. There is no rule installed by the
constructor.
Appointer (Integer)
The Appointer constructor creates an appointer with an initial
time. The time is set as he starting time to allocate slots.
There is no rule installed by the constructor.
Methods
reset -> none (none)
The reset method reset the appointer slot number and daily slot
counter. The rules are not touched by this method.
set-time -> none (Integer)
The set-time method set the appointer time. During the next
operation, the newly allocated slots have their time starting at
least at this time.
get-time -> Integer (none)
The get-time method returns the current appointer time.
set-date -> none (Date)
The set-date method set the appointer time by converting the
date argument to a time.
get-date -> Integer (none)
The get-date method returns the current appointer date.
get-slot -> Slot (Integer|Integer Integer)
The get-slot method returns a new slot allocated by the
appointer. with one argument the argument is taken as the slot
duration. With 2 arguments, the first arguments is the requested
slot time and the second argument is the slot duration. The slot
allocation algorithm operates by finding the appropriate day and
time which satisfies the appointer rules. If the slot cannot be
found within one week, the allocation is assumed to have failed.
get-slot-number -> Integer (none)
The get-slot-number method returns the total number of slots
allocated by the appointer.
set-blocked-day -> none (Integer)
The set-blocked-day method sets a regular weekly block day. The
method uses the week day index as its argument. Sunday has index
0 and Saturday has index 6. No slot is allocated in a blocked
day.
set-special-day -> none (Integer Integer)
The set-special-day method sets a special year day. The method
uses the year month and the month day index as its arguments.
The first argument is the year month which must be in the range
of 1 to 12. The second argument is the month day which must be
in the range of 1 to 31. No slot is allocated in a special day.
set-maximum-slots -> none (Integer)
The set-maximum-slots method sets a daily maximum slots number.
When the daily maximum slot number is reached, the slot
allocation proceed to the next day.
set-valid-block-time -> none (Integer Integer)
The set-valid-block-time method sets a valid block time in which
the slot can be allocated. By default, a slot can be allocated
anytime during the day. When this rule is set, at least once,
the slot is allocated in this block. Multiple valid block time
can be defined. The first argument is the valid block time lower
bound expressed in seconds from 12PM. The second argument is the
valid block time upper bound. All time are expressed in seconds
and rounded to a day second which is 84600 seconds in 24 hours.
For example, a valid block time is from 8AM to 12AM. Another
would be from 2PM to 6PM.
Assistant
The Assistant class class is a generic class designed to hold various
pim component and manage them like an assistant will do. For example,
the class can store several Appointer objects and distribute slot for
all of them.
Predicate
assistant-p
Inheritance
Object
Constructors
Assistant (none)
The Assistant constructor creates a default assistant.
Assistant (String)
The Assistant constructor creates a default assistant by name.
Assistant (String String)
The Assistant constructor creates a default assistant by name
and information. The first argument is the assistant name. the
second argument is the assistant information string.
Methods
reset -> none (none)
The reset method reset the assistant by. All objects attached to
the assistant are reset by this method.
get-name -> String (none)
The get-name method returns the assistant name.
get-info -> String (none)
The get-info method returns the assistant information string.
pushback -> none (Slot)
The pushback method pushbaks a slot in the appointer list. The
assistant manages internally an index which is used to select
the appointer where the slot is pushed-back.
get-slot -> Slot (Integer|Integer Integer)
The get-slot method returns he next available slot from the
appointer list. The assistant manages internally an index which
is used to select the appointer from which the slot is obtained.
With one argument, the method operates with a slot duration.
with 2 arguments, the method operates by time and duration. The
time is the minimum time for which the slot is allocated. If the
slot cannot be allocated, an exception is raised.
add-appointer -> none (Appointer)
The add-appointer method adds an appointer object to the
assistant.
get-appointer -> Appointer (Integer)
The get-appointer method returns an appointer object by index.
If the appointer object cannot be found, an exception is raised.
length-appointer -> Integer (none)
The length-appointer method returns the number of appointers
attached to the assistant.
get-slot-number -> Integer (none)
The get-slot-number method returns the total number of slot
allocated by the assistant at the time of the call. The number
is computed by summing all slot numbers for each appointers.
attached to the assistant.
get-appointer-time -> Integer (none)
The get-appointer-time method returns the average appointer time
for the attached appointers. At the time of the call, each
appointer has a time which corresponds to the next slot
available time. The average time for all appointers is the
result of this method which corresponds to the average time of
the next available slot.