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

<!-- ====================================================================== -->
<!-- = appendix-i.xml                                                     = -->
<!-- = standard pim module guide - appendix i                             = -->
<!-- ====================================================================== -->
<!-- = 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-2006 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="pim" number="i">
  <title>Standard pim reference</title>

  <p>
  This appendix is a reference of the <afnix/> standard pim module.
  </p>

  <table>
    <title>Standard pim module</title>
    <thead>
      <tr><td>Symbol</td> <td>Description</td></tr>
    </thead>
    <tbody>
      <tr><td>afnix-pim</td><td>module</td></tr>
      <tr><td>afnix:pim</td><td>nameset</td></tr>
    </tbody>
  </table>

  <!-- =================================================================== -->
  <!-- = slot object                                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:pim">
    <name>Slot</name>

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

    <!-- predicate -->
    <pred>slot-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Slot</name>
      <args>none</args>
      <p>
      The <code>Slot</code> constructor creates an empty slot
      initialized at time 0 with duration 0.
      </p>
    </ctor>

    <ctor>
      <name>Slot</name>
      <args>Integer Integer</args>
      <p>
      The <code>Slot</code> constructor creates a slot with a time and
      duration. The first argument is the slot time. The second
      argument is the slot duration.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the slot to time 0 with
      duration 0.
      </p>
    </method>

    <method>
      <name>set-time</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-time</code> method sets the slot time.
      </p>
    </method>

    <method>
      <name>get-time</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-time</code> method returns the slot time.
      </p>
    </method>

    <method>
      <name>set-duration</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-duration</code> method sets the slot duration.
      </p>
    </method>

    <method>
      <name>get-duration</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-duration</code> method returns the slot duration.
      </p>
    </method>

    <method>
      <name>set-slot</name>
      <retn>none</retn>
      <args>Integer Integer</args>
      <p>
      The <code>set-slot</code> method sets the slot time and duration
      at once. The first argument is the slot time. The second
      argument is the slot duration.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = appointer object                                                = -->
  <!-- =================================================================== -->

  <object nameset="afnix:pim">
    <name>Appointer</name>

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

    <!-- predicate -->
    <pred>appointer-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Appointer</name>
      <args>none</args>
      <p>
      The <code>Appointer</code> constructor creates a default appointer
      initialized at time 0. There is no rule installed by the constructor.
      </p>
    </ctor>

    <ctor>
      <name>Appointer</name>
      <args>Integer</args>
      <p>
      The <code>Appointer</code> 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.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the appointer slot number
      and daily slot counter. The rules are not touched by this method.
      </p>
    </method>

    <method>
      <name>set-time</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-time</code> method set the appointer time. During
      the next operation, the newly allocated slots have their time
      starting at least at this time.
      </p>
    </method>


    <method>
      <name>get-time</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-time</code> method returns the current appointer time.
      </p>
    </method>

    <method>
      <name>set-date</name>
      <retn>none</retn>
      <args>Date</args>
      <p>
      The <code>set-date</code> method set the appointer time
      by converting the date argument to a time.
      </p>
    </method>

    <method>
      <name>get-date</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-date</code> method returns the current appointer date.
      </p>
    </method>

    <method>
      <name>get-slot</name>
      <retn>Slot</retn>
      <args>Integer|Integer Integer</args>
      <p>
      The <code>get-slot</code> 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.
      </p>
    </method>

    <method>
      <name>get-slot-number</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-slot-number</code> method returns the total number
      of slots allocated by the appointer.
      </p>
    </method>

    <method>
      <name>set-blocked-day</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-blocked-day</code> 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.
      </p>
    </method>

    <method>
      <name>set-special-day</name>
      <retn>none</retn>
      <args>Integer Integer</args>
      <p>
      The <code>set-special-day</code> 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.
      </p>
    </method>

    <method>
      <name>set-maximum-slots</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-maximum-slots</code> method sets a daily maximum
      slots number. When the daily maximum slot number is reached, the
      slot allocation proceed to the next day.
      </p>
    </method>

    <method>
      <name>set-valid-block-time</name>
      <retn>none</retn>
      <args>Integer Integer</args>
      <p>
      The <code>set-valid-block-time</code> 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.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = appointer object                                                = -->
  <!-- =================================================================== -->

  <object nameset="afnix:pim">
    <name>Assistant</name>

    <p>
    The <code>Assistant</code> 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
    <code>Appointer</code> objects and distribute slot for all of
    them.
    </p>

    <!-- predicate -->
    <pred>assistant-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Assistant</name>
      <args>none</args>
      <p>
      The <code>Assistant</code> constructor creates a default assistant.
      </p>
    </ctor>

    <ctor>
      <name>Assistant</name>
      <args>String</args>
      <p>
      The <code>Assistant</code> constructor creates a default
      assistant by name.
      </p>
    </ctor>

    <ctor>
      <name>Assistant</name>
      <args>String String</args>
      <p>
      The <code>Assistant</code> constructor creates a default
      assistant by name and information. The first argument is the
      assistant name. the second argument is the assistant information
      string.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the assistant by. All
      objects attached to the assistant are reset by this method.
      </p>
    </method>

    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the assistant name.
      </p>
    </method>

    <method>
      <name>get-info</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-info</code> method returns the assistant
      information string.
      </p>
    </method>

    <method>
      <name>pushback</name>
      <retn>none</retn>
      <args>Slot</args>
      <p>
      The <code>pushback</code> 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.
      </p>
    </method>

    <method>
      <name>get-slot</name>
      <retn>Slot</retn>
      <args>Integer|Integer Integer</args>
      <p>
      The <code>get-slot</code> 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.
      </p>
    </method>

    <method>
      <name>add-appointer</name>
      <retn>none</retn>
      <args>Appointer</args>
      <p>
      The <code>add-appointer</code> method adds an appointer object
      to the assistant.
      </p>
    </method>

    <method>
      <name>get-appointer</name>
      <retn>Appointer</retn>
      <args>Integer</args>
      <p>
      The <code>get-appointer</code> method returns an appointer object
      by index. If the appointer object cannot be found, an exception
      is raised.
      </p>
    </method>

    <method>
      <name>length-appointer</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>length-appointer</code> method returns the number of
      appointers attached to the assistant.
      </p>
    </method>

    <method>
      <name>get-slot-number</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-slot-number</code> 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.
      </p>
    </method>

    <method>
      <name>get-appointer-time</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-appointer-time</code> 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.
      </p>
    </method>
  </object>
</appendix>
