27/9/2001

Intoduction

This document is to describe the behaviour of a free spread sheet to be distrivuted for the FreeDOS project. This document only describes how the final version will behave, and what features it will have, but the main project is not this document and it may or may not go the same way that this document describes.

In this document, I will explain how the program will behabe from the user point of view (the user interface) and from the progarmer pointof view (programer interface/API).

The UI

The spread sheet is devided to 4 main parts:

The Menubar
The menu bar, is the way of the user to comunicate with the aplication and tellig it what he want it to do: open a new file, print a chart pie, copy/cut/paste/delete some text etc. It will also have a small help menu which will guide the user.
The Cell Editor
The cell editor is a input line, that will display the contents of the selected cell. To edit the conents of the cell you will have to click it with the mouse. It will not render the contents of the cell. If the cell contents is: "5+5" it will not display "10" buit "5+5".
The Sheet Viewer
The sheet viewer, is a 2 dimentional matrix, in which you enter text values to be saved as cells. Each cell is represented by 2 coordinates: one a letter and a number. The leter representing the Y axis, or the rows, and the number representing the X axis or the collums. The numbering scheme is: left -> right, and top -> down. rows starting with the letter 'A' and endind with 'Z', and collums starying with '1' and ending with '100' or what ever is possible to use in this application. Ther are no negative index (for example -A or -3). For example: the first cell (row=1, collum=1), is located on the upper left screen point, on his right you will find (row=1, collum=2), and bellow it you will find (row=2, collum=1). Latter I will describe each cell beheavuoir .
You can move the focus of the selected cell with the keyboard using the cursor keys, home, end, page up and page down. Each key will select a new cell. When the rightest cell is selected and the user pressed thr right cursor key, all the display will be scrolled to the left, and you will see new collum visible. The same approach will be apllied for the left, up and down directions.
The Sheet Viewer will also have attached 2 scrool bars, each representing an axis. The scroll bars can be used for scrolling the Sheet Viewer and will be updated when the user scrolls the Sheet Viewer with the keybaodr. Note: the scroll bars position will be determinated by the first visible cell on the screen and not the active cell. The range will be 0..TOTAL_CELLS_ON_THE_SHEET - TOTAL_CELL_ON_SCREEN, of course each for it's own axis.
The Status Bar
The Status bar job is to supply more oinformation to the user about what is happenning in the program. It displays small messages, for a short period of time. For example when a cell value could not be evaluated into a number, it will display where is the error happened. If memory is running low, it will display the ammount, and will display short messages saying that the file was saved succesfully etc.

Cells

The Sheet Editor is a 2 dimentional matrix which conatins cells . The cell is a basic unit to store any kind of information: numbers, strings dates or any other type of information that you need. The content of a cell is called an expression. The expression can be a mathematical formula containing some other cells. There are 3 ways to address a cell content:

As most spread sheet recognize C8
As a C array: for example, to represent the cell at row 3, and collum 8: C[8]\
Using the AT() function: at(3,8) or at(C,8). (function will be described later).

Last 2 methods methods will give the user a lot of flexibility: for example dinamic indexing. Dinamic ixndexing means that the index for a cell can be the value/content of another cell. For example look in thease tables:

table 1: cell contents

	43rw1	2	3	4
A	at(b[2],c[3])
B		4
C			1
D	-99

table 2: rendered text values

	1	2	3	4
A	-99
B		4
C			1
D	-99

You see that A[1] needs for indexing both B[2] and C[3] . You can also see that there is a mixture of styles, both the C indexin and the AT() function can be mixtured in the same expression. In this example the value of A[1] is determinated by the value of D[1] (B[2]=4, C[3]=1). If you will change the content of cell D[4] also A[1]will changed. This is called dinamic indexing, becuase you can change the cell that will be read for geting the final expresion whitout changing the cell content, but other cell on which the first content depends on it.

Functions

An expression can contain strings, numbers, cells or functions. A function performs an action on a cell or a list of cells, depending of the function you are using. Some functions can also have a group of inputs: a[1]..a[5], will be evaluated into: a[1], a[2], a[3], a[4], a1..b2 will be a1, a2, b1, b2.

Here is a small explain about each function (all the examples use the values of table 1):

AT(): The function takes two arguments, and returns the content of the cell described by them, the first can be also a letter.

Example: AT( 1, 1 ) = -99
AVERAGE(): The function will return the average of all the arguments. It can contain group of cells.

Example: ARERAGE( 2, 5 , c[3]) = 3
MIN(): This function will return the lowest value of all the arguments passed.
Example: MIN( 42, b[2], a[1] ) = -99
MAX(): This function will return the highest of all the arguments passed

Example: MIN( 42, b[2], a[1] ) = 42
TODO: Finish this list.

Programmer Interface/API

This secction will discuse about how the program will be made. The current idea is to make it with Turbo Pascal 7, and SV GUI I made (TP7 is available from http://www.borland.fr , and SV is available at: http://dgi_il.tripod.com/sv ). This way the software can be defetly defined as open-source and free. With adition to the FreeDOS project this will end up beeing one of the most interesting Desktop-Computer avaiable for free thease days.

When SV will be ported to FreePascal ( http://www.freepascal.org ), the spread sheet can be also ported to that architecture (DOS32). Hopefully it will still be runnable under FreeDOS, and hopefully also FreeDOS32 (if that project is still available).

Cell's related procedures and functions: unit SHEET.PAS

The internal structure of how the cells are stored is not relevant to tha main program. The UI just needs some small procedures to get access to a cell located at(some_x, some_y).

The cells are saved internally as a single linked list. its pascal definition is like this:
TYPE PCELL = ^TCELL; TCELL = RECORD x, y: integer; content: string; next: PCELL; END;

This is the most memory conserving technice I found to make a double array. All need to do now is declare a list head and a list tail. In the implementatoin teh location can be made also by a record, and the content can be made a pointer to a string to allocate only the memory needed, the next membetr can be made private if the record is declared as OBJECT instead of RECORD. It will also be code-compatible with this code.

The interface of his unit will include also a few procedures/functions to deal with getting the address (pointer) to a cell:

FUNCTION Cell_At( x, y: integer ): PCell ;
Will return a pointer to the cell located at the desired location. It is possible to change the content of the cell from this pointer.
FUNCTION Text_At( x, y: integer ): PCell;
Will return athe content of the cell located at (x,y).
FUNCTION New_Cell( x,y: integer; cell: PCell ): PCell
Will insert a new cell, to a location. If in the desired location there is already a cell, the cell wil be deleted and the new one will be placed instead, otherwise the new cell will be inserted in the tail of the linked list and LIST_TAIL will now point to the new inserted cell.
PROCEDURE Delete_cell( x,y: integer )
Will delete the desired cell from the single linked list, updating LIST_TAIL and LIST_HEAD if necesary.

Cell Input Rendering

The content of the cell should be rendered to be displayed at the Sheet Viewer proparly. That means that for example A[1] conent is "B[2]*2" and B[2] content is "15", at the cell A[1] the sheet viewer should display "30". There is a function that should render the text contnet of a cell. It takes a string as a parameter, and returns a string wich is the result of the expression passed as a parameter. The rendering is done i n 2 parts:

First all cell references are removed from the string. First all all references to a C, variable are removed (A[24], C[2] etc). First the function looks for the lst '[' character, and then form the first ']'. All in between is removed from the string and replaces with the correct index. Now the first index is also deleted and then replaced with the content of the desired cell.
Next the other cell assigments are deleted.
After that the functions are replaced with the result of them. Again in the same way that the first cell references were delete, first by seeking the last closing barket, and then the first opening one, replaceing all in between with the evaluation of the deleted string.
Of course, every time an expression needs to be evaluated it calls the same function (recousy).
Now, the string consists only of a valid mathematical expression. For example: 1/(4+2*4*sin(2+18)). This string is then passed to another phraser function which knows only about qualified mathematical expressions. This function can be taken from another open source project.

The pharsing/rendering is made in two separated steps for a few reasons:

Modularity. The lower phraser function can be replaces easly, for getting a faster resullt, or just because a better code was found. This also means that there is another team/person who is the mantainer of this part, and not all the job is node by one man. Since it is independent of any other code, he does not need to know how the rest of the engine works, nor has to deal with UI problems, for example.
In case a bug is found it is faster to find it, since every part of the function is independent of each other.
Each functin can be made in another programming lenguage. For example the lower function can be made in C or ASSEMBLY.

In every step the validation of an expression is made, and if it is found invalid it is taken as a literal string. The operators that work on strings are described here:

Plus operator +: it will return the literal addition of two cells. For example is A[1]="Hello" and A[2]="World" and A[3]="A[1]+B[2]" it will be rendered as "Hello World", a space is inserted between each cell. If there are also numbers, they will be added as strings. In the last example, lets say that A[2]="2", A[3] will be rendered as "Hello 2".
Minus operator -: it will delete from the first string the second string if found. If not will return the first string. For example: A[1] = "Hello wolrd!", A[2] = "A[1]-world". In this example A[2] will be rendered as "Hello !".

Conclussion

This document is under construction and should not be used as a final or best way how a spread sheet sould behave. You can contrivute to this project by sending a mail to the author of this document and telling him what more is needed. I do not use any spread sheet on regular bases and so I will need help in understanding what is needed for this spread sheet to be really usable.

You can contact me in any way that you can my detail are in the bootm of this document. (my email is changing a lot in the last time, so I put here my hotmail address which according to the site should be for life.)

The latest version of this document can be found at: http://dgi_il.tripod.com/sv/spread_sheet_doc.html .

Diego G. Iastrubni (ICQ #28481600)
dgi_il@hotmail.com
http://dgi_il.tripod.com