The First Steps

Now that you have an idea what TEAPOT is about, it is probably a good time to take your first steps with it. This section will show you how to create and save a sheet which contains two numbers and their sum. Start the program without any arguments:

teapot

You see an empty sheet with the cell cursor being at the upper left corner. Further, the status line tells you that this cell is really empty:

E @(0,0,0)=

The E means that you can edit the sheet. A V would mean that you could only view its contents. The meaning of @() will be explained soon. You are now in the command mode of TEAPOT. Press the Enter key to edit this cell. A complete list of command mode operations will be given later. A prompt will appear below the status line:

Cell contents: 1

Now the cell at position 0,0,0 has the integer constant 1. The status line shows you the cell contents, whereas in the sheet you see its value. Since constants are identical with their values, both are 1. Now move the cell cursor down one row and edit that cell, giving it the integer constant 41.

Now that you have two numbers, move the cell cursor to cell 0,2,0 and give that cell the following contents:

Cell contents: @(0,0,0)+@(0,1,0)

If you were confused about the difference between contents and value of a cell, it should become more clear now: The status line shows the contents, which is the arithmetic expression to calculate the sum of two cells, whereas in the sheet you see the value of that expression: 42, which was to be expected. @(x,y,z) is a function which takes three coordinates and returns the value of the cell at the given position.

As you can see, the arithmetic expression is not too readable. If you would move cells around, it would not even work any more. For these reasons, you can use symbolic names instead of coordinates, called labels. When used in an expression, a label is like a pointer to a cell, its data type is location. Move to cell 0,0,0 and use / (slash) in command mode to get into the main menu. Depending on your screen size, you may not see all of it. In this case, move the highlighted block right (or left) to scroll through it and to see all items. Now change its label attribute: A)ttributes, L)abel:

Cell label: Paper

Then go one cell down and change its label to Tapes. After, move again one cell down and change the expression to:

Cell contents: @(Paper)+@(Tapes)

As you see, you can call the function @ with three integer values or with one location value. Now the expression is more understandable, at least to you. To someone else, the sheet only contained three numbers, so a little text should be added. To accomplish that, a new column needs to be inserted: B)lock, I)insert, C)olumn, W)hole column. The last menu item means that you want to insert a whole new column, not only a partial column. If you move the cursor around, you will see that everything is still fine, because you used labels. Go to cell 0,0,0 and edit it:

Cell contents: Paper:

This is how you enter strings. A string is a data type on its own, don't confuse this with labels. If you feel like it, leave the quotes and the colon away, and you will see the difference, because the result will not be a string, but the value of the label Paper, which is &(1,0,0). Now change the cells below to Tapes: and Result:. This is something that is understandable to others, too.

As the last step, save your work sheet to a file: F)ile, S)ave. The native file format is Teapot ASCII, so choose that. Up to now, your sheet does not have a name, so you will be prompted for one:

New file name: firststep

Unless you see an error message after, your sheet is written to a file.

If you have come this far, quit (from the main menu) and you have successfully completed your first steps on using TEAPOT. Now you know cells, the difference between contents and values, you learned that labels are a good thing and you can do simple cell modifications as well as saving your work. This is enough for most applications. If the capabilities described in the next section confuse you, then it is unlikely that you need them really. Just skip that section and don't worry about it.

You may wonder what happens if you have circular dependencies, i.e. you have a cell which evaluates to its own value plus one. Well, the answer is that it depends on the order in which you create this cell. If you first give it the value 1 and after edit it to contain the expression which refers to itself plus 1, then you will find that each recalculation, like after editing other cells, will increase the value. While this may be funny, it is certainly not useful as you can not reset the cell and you have little control of its development.

What you really want is a base value and an iterative expression along with a way to control the recalculations. TEAPOT supports this by allowing two expressions per cell. The expressions you have used so far are the ones which evaluate to the base values. Each time you edit a cell, the whole sheet will be reset, which means that all results are recalculated using the base values. After, you can clock the sheet, which is why the iterative part is also called clocked expression. A clock is an atomic operation, which means that all cell results will be recalculated in a way that the new result will only show after the entire recalculation.

An example will demonstrate how to make use of this feature. The notation x -> y means that x is the base expression and y is the clocked expression. Don't let this confuse you, as both are entered separately: TEAPOT does not have an -> operator, but it displays the cell contents this way so you can easily see both expressions at once. So, give the cell a base expression of 1 and a clocked expression of @(0,0,0)+1 (using ESC-Enter or Meta-Enter) and you will see:

@(0,0,0)=1 -> @(0,0,0)+1

The sheet is currently in reset condition and the result is 1. Now clock it and you will see how the value increases.

After this introductory chapter, you should be familiar with the basic concepts in spread sheets. The next chapters explain all operations available in detail. You should read them to get an overview of the possibilities offered by TEAPOT. Finally, we will come back to using TEAPOT by showing some common problems and their solutions.