<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = chapter-1.xml                                                      = -->
<!-- = standard pim module guide - chapter 1                              = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter module="pim" number="1">
  <title>Standard pim services</title>
  
  <p>
  This chapter covers the pim facilities available in the
  <em>standard personal information management</em> module. The
  basic operations are related to time management.
  </p>

  <p>
  All <afnix/> standard <em>pim</em> objects are located in the
  <code>afnix-pim</code> module. This module must be loaded prior
  any operation. Multiple calls to the module initialization routine
  are harmless. The interpreter method <code>module</code> loads a
  specific module by name. When the module has been loaded, the
  object are available in the <code>afnix:pim</code> nameset.
  </p>
  
  <example>
  interp:library "afnix-pim"
  </example>

  <!-- general concepts -->
  <section>
    <title>General concepts</title>

    <p>
    The <code>afnix-pim</code> 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.
    </p>

    <!-- slot -->
    <subsect>
      <title>Slot</title>
      
      <p>
      The concept of slot is central in the <em>pim</em> module. A
      slot is a combination of time and duration. A slot is allocated
      by an appointer to indicate the next available <em>slot</em>. 
      For an agenda, the concept of slot can be derived to describe an
      appointment.
      </p>
    </subsect>

    <!-- appointer -->
    <subsect>
      <title>Appointer</title>
      
      <p>
      An <em>appointer</em> 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.
      </p>
    </subsect>

    <!-- assistant -->
    <subsect>
      <title>Assistant</title>
      
      <p>
      An <em>assistant</em> is a combination of pim object like
      appointers. An assistant can be used for example, to manage
      several appointers.
      </p>
    </subsect>
  </section>

  <!-- appointers operations -->
  <section>
    <title>Appointer operations</title>

    <p>
    The <code>Appointer</code> 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.
    </p>

    <!-- slot allocation -->
    <subsect>
      <title>Slot allocation</title>
      
      <p>
      A slot is allocated with the <code>get-slot</code> method. This
      method is common to the <code>Appointer</code> and
      <code>Assistant</code> classes.
      </p>

      <example>
      # allocate a 1 hour slot
      const slot (appt:get-slot 3600)
      </example>

      <p>
      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.
      </p>

      <example>
      # allocate a 1 hour slot starting at 2AM
      const slot (appt:get-slot 7200 3600)
      </example>
      
      <p>
      In the presence of an <code>Assistant</code> object the
      <code>get-slot</code> 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.
      </p>
    </subsect>

    <!-- appointer rules -->
    <subsect>
      <title>Appointer rules</title>

      <p>
      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 <em>and rules</em>
      since all rules must be valid in order to allocate a slot at the
      requested time. The second type is a called the <em>or
      rules</em> since only one rule needs to be valid in order to
      allocate a slot.
      </p>

      <example>
      # 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
      </example>
      
      <p>
      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.
      </p>

      <example>
      # 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
      </example>

      <p>
      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.
      </p>
    </subsect>
  </section>

  <!-- assistant operations -->
  <section>
    <title>Assistant operations</title>

    <p>
    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.
    </p>

    <subsect>
      <title>Assistant integration</title>

      <p>
      Once an assistant object has been created, the object can be
      added by cloning.
      </p>

      <example>
      # 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)
      </example>

      <p>
      In the case of an <code>Appointer</code> 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.
      </p>
    </subsect>
  </section>
</chapter>
