# Fundamentals

This chapter covers the spreadsheet fundamentals available in the standard spreadsheet 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.

All spreadsheet objects are located in the `afnix-sps` 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:sps` nameset.

interp:library "afnix-sps"

## Spreadsheet concepts

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 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 cell. A set of cells is a record. A set of records is a sheet. A set of sheets and records is a folio.

### Cell and data

A cell 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.

### Record

A record 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.

### Sheet

A sheet 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 marker record, the header record and footer record as well as the tag vector and the signature.

### Folio

A folio 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.

## Storage model

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.

### Single record model

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.

### Record importation

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 car is the cell name and the cadr is the cell object.

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

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.

### Record exportation

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.

## Folio indexation

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.

### Sheet access model

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.

### Cell access model

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.

### Search and access

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.