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

<!-- ====================================================================== -->
<!-- = chapter-1.xml                                                      = -->
<!-- = standard speadsheet 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="sps" number="1">
  <title>Standard spreadsheet concepts</title>
  
  <p>
  This chapter covers the spreadsheet fundamentals available in the
  <em>standard spreadsheet</em> module. The spreadsheet module provides
  a great interface to structure data in the form of record and
  sheets. Once structured, these data can be indexed, manipulated and
  exported into various formats.
  </p>

  <p>
  All <afnix/> spreadsheet objects are located in the
  <code>afnix-sps</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:sps</code> nameset.
  </p>
  
  <example>
  interp:library "afnix-sps"
  </example>

  <!-- section -->
  <section>
    <title>Spreadsheet concepts</title>

    <p>
    The sole purpose of using a spreadsheet is to collect various data
    and store them in such a way that they can be accessed
    later. Unlike standard spreadsheet system, the <afnix/> standard
    spreadsheet module does not place restrictions on the data
    organization.

    The spreadsheet module stores data in a hierarchical fashion. The
    basic data element is called a <em>cell</em>. A set of cells is
    a <em>record</em>. A set of records is a <em>sheet</em>. A set of
    sheets and records is a <em>folio</em>. 
    </p>

    <!-- cell and data -->
    <subsect>
      <title>Cell and data</title>

      <p>
      A <em>cell</em> is a data container. There is only one data
      element per cell. Eventually a name can be associated with a
      cell. The cell data can be any kind of literals. Such literals
      are integer, real, boolean, character or strings.
      </p>
    </subsect>

    <!-- record -->
    <subsect>
      <title>Record</title>

      <p>
      A <em>record</em> is a vector of cells. A record can be created
      by adding cell or simply by adding data. If the record has a
      predefined size, the cell or data can be set by indexing.
      </p>
    </subsect>

    <!-- sheet -->
    <subsect>
      <title>Sheet</title>

      <p>
      A <em>sheet</em> is a vector of records. A sheet can be created
      by adding record. Similarly, if the sheet has a predefined size,
      record cell or data can be added by indexing. A sheet can also
      be seen as a 2 dimensional array of cells. For the purpose of
      managing extra information, the sheet carry also several extra
      records, namely, the <em>marker record</em>, the <em>header
      record</em> and <em>footer record</em> as well as the <em>tag
      vector</em> and the <em>signature</em>.
      </p>
    </subsect>

    <!-- folio -->
    <subsect>
      <title>Folio</title>

      <p>
      A <em>folio</em> is a set of sheets and/or records. A folio
      of sheets permits to structure data in the form of tables. Since
      cell, record and table can have a name, it is possible to create
      link between various elements, thus creating a collection of
      structured data.
      </p>
    </subsect>
  </section>

  <!-- storage model -->
  <section>
    <title>Storage model</title>

    <p>
    There are several ways to integrate data. In the simplest form,
    data are integrated in a record list. A complex model can be built
    with a sheet. More complex models can also be designed by using a
    folio.
    </p>

    <!-- single record model -->
    <subsect>
      <title>Single record model</title>

      <p>
      With a single record model, the data are accumulated in a single
      array. This kind of data storing is particularly adapted for
      single list recording. As a single record, the basic search and
      sorting algorithm can be applied. For instance, a list name can
      be stored as a single record. With this view, there is no
      difference between a list, a vector and a record. The record can
      also be named.
      </p>
    </subsect>

    <!-- record importation -->
    <subsect>
      <title>Record importation</title>
      
      <p>
      Data are imported into the record, either by construction, list
      or stream. Since the record object is a serializeable object, the
      importation process is also performed automatically in the
      collection. The base record importation class implements a
      simple importation model based on blank separated
      literals. Complex importation models can be devised by
      derivation. A special case with a cons cell is also supported
      where the <em>car</em> is the cell name and the <em>cadr</em> is
      the cell object.
      </p>

      <example>
      # an example of file importation
      1   "a string" 'a'
      'b' ("cell name" 2) 123
      </example>

      <p>
      The previous example shows the file structure that can be used
      to import cell data. The fist line defines a record with 3
      cells. The second line defines also a record with 3 cells. The
      second cell is a named cell.
      </p>
    </subsect>

    <!-- record exportation -->
    <subsect>
      <title>Record exportation</title>

      <p>
      A record is an object that can be serialized. It can therefore
      be exported easily. However, in the serialized form, the record
      is in a binary form. It is also possible to walk through the
      record and exports, for each cell its literal form.
      </p>
    </subsect>
  </section>

  <!-- folio indexation -->
  <section>
    <title>Folio indexation</title>

    <p>
    There are various ways to access a folio by reference. Since a
    folio can contain several sheets, it seems natural to access them
    by tag. The other method is to index the cells in a
    cross-reference album in order to access rapidly.
    </p>

    <!-- sheet access model -->
    <subsect>
      <title>Sheet access model</title>

      <p>
      The sheet access model uses a tag to access one or several
      sheets in a folio. A tag is a string attached to a sheet. It is
      possible in a folio to have several sheet with the same tag. It
      is also possible to attach several tags to a sheet. When a folio
      is searched by tag, the first sheet that matches the tag is said
      to be the valid one. If all sheets that match the requested tag
      are needed, it is possible to create a derived folio with all
      sheets that match the requested tag.
      </p>
    </subsect>

    <!-- cell access model -->
    <subsect>
      <title>Cell access model</title>
      
      <p>
      The cell access model operates with a cross-reference table
      built with an index. An index is a multiple entry record that
      stores the cell location. A cell coordinate comprises the cell
      index in the record, the record index in the sheet and the sheet
      index in the folio. If an index contains multiple entries, this
      indicates that several cells are indexed. A cell cross-reference
      table is a collection of index. Generally the index name is the
      cell name. When the cross-reference table is built, all cell of
      interests are scanned and if a cell name exists, the cell is
      indexed in the cross-reference table. If there are several cells
      with the same name, the index length associated with the name is
      the number of cells with that name.
      </p>
    </subsect>

    <!-- search and access -->
    <subsect>
      <title>Search and access</title>

      <p>
      The methodology for searching is to decide whether a sheet or a
      cell should be accessible. If a sheet access is desired, the
      search by tag method is the preferred way. This method assumes
      that the requested sheet is structured in a particular way,
      known to the user. If a cell access seems more appropriate, a
      cross-reference table should be built first, and the search done
      from it. In the case of search by tag, the method is dynamic and
      operates well when sheets are added in a folio. When a
      cross-reference table is used, proper care should be taken to
      rebuild the cross-reference table when some sheets are added
      unless the user knows that there is no need for it.
      </p>
    </subsect>
  </section>
</chapter>
