Man Linux: Main Page and Category List

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.