NewCalc is a program for manipulating tables of information. Each table is rectangular, composed of cells, arranged in rows and columns. An individual cell may contain ordinary text, an expression, or control information. The individual expressions in a row/column may be summed, and the sum displayed in some cell in that row/column. A computed value (such as a row or column sum) may be assigned to an identifier, and that identifier may be used in an expression in some other table. If one expression is changed in one cell, all displayed values throughout the document can be automatically updated to reflect the change.

A NewCalc document is composed of pages, each page containing one or more tables. In complex situations, a group of consecutive pages may be combined together. In this case, the first page of the group is a summary page, and contains summary tables. Each summary table contains a summary of information contained in item tables on each of the other pages of the group.

A primary goal of the program is to make it easy to construct a desired collection of tables. This is done automatically through structural manipulations of the tables and pages, rather than by writing individual expressions in each cell to express the desired relations. In cases where the built in structural features do not produce the desired effect, the user is free to extend them through the use of expressions and assignment of values to identifiers.

This document is intended to be read while using a Cedar machine. The user is carried step by step through the various manipulations, beginning with those involving a single table and working up to more complex operations.

In the preceding step, you selected the word slot with a mouse click, and it was displayed in reverse video to indicate its selection. Unfortunately, NewCalc does not always indicate selections in this manner.

NewCalc uses two representations for a cell, either as a Button Viewer, or as a Text Viewer. The normal representation for a cell is as a Button. Clicking the button runs a procedure which converts it to a text viewer, and selects the entire contents of the viewer. This action is what provided the preceding reverse video for slot.

If one now selects a second cell, converting its representation from a Button to a Text Viewer (in reverse video), the first remains as a text viewer. Now we can move the selection back to the first, by clicking at any character in the viewer, but in this case the selection is represented by an underlined character, or by a blinking carat.

In general, a selected cell is represented by a text viewer which contains the current Viewers text selection, for which there are several modes: reverse video, underlined characters, or blinking caret.

Explore this behavior in the table previously constructed. Click the mouse over any cell, it should convert to reverse video. Now click the mouse over any other cell, and it will convert to reverse video, while the first reverts to normal video. Now go back and click the mouse at the first cell, you will get a Viewer text selection, but not with reverse video.

A table is composed of cells, arranged in rows and columns. The behavior of the cells in a table depends on control information associated the rows and columns of the table. Examine the table previously constructed. The first row contains the following text: "<zvt: "0.00"> ... <sum>". This row displays the control information associated with the columns of the table, together with some control information for the table as a whole.

The <zvt: "0.00"> indicates that any derived values in the table that are equal to zero will be displayed as "0.00". At the moment there are no derived values of zero, but later we will manipulate this text. The <text> indicates that the cells in this column contain text, with no semantic signifcance. The <+exp> indicates that some cells in this column contain expressions, which will contribute positively to a sum for the row in which they occur. The <sum> indicates that this column contains cells which will display derived values which are the partial sums of the values in their row. For example, 106.00 is the sum of 25, 36, and 45.

Now examine the first column. As for the first row, this column displays the control information for the individual rows, together with global table control information in the first few rows. The <id: "newTableId"> says the the name of this table is newTableId. The <text> indicates that the cells in this row contain text, just like the cells in the column controled with <text>. The <sum> indicates that this row contains cells which will display derived values which are the partial sums of the values in their column. For example, 69.00 is the sum of 25 and 44.

Notice that the behavior of a cell is a somewhat complicated function of its row and column controls. e.g. it either row or column control is text, the cell acts as a text cell. (Well... almost always.) Later, we will investigate these control modes in more detail, but first, lets try some cell modifications.

Select the number 25, and change it to 5. Now click the command button labeled adjust in the upper part of the viewer. The row and column sums are immediately adjusted to reflect the change from 25 to 5. (You could make several numerical changes before clicking adjust. No derived values will be updated until you click adjust.)

Select the number 86.0 and try to change it to 25. You can't. This cell is displaying a derived value, and is uneditable.

Select the text textCol and replace it with a long sequence of characters. You will notice that only some of the new characters are displayed. Now click adjust, and all of the characters that you typed will be displayed. Simultaneously, the width of the column will be adjusted to accommadate the longer text. (The inability to display all of the characters as they were typed is an artifact of the current NewCalc mechanism for displaying a cell.)

Normally, you do not want to see the row and column control information. Select any cell in the array, and then, in the document command area, click the button labeled ToggleControlVisibility. All control information should disappear from the table. Notice that the table name remains in the upper left corner of the table.

Now we begin to manipulate the rows and columns of the table. Select any cell in the first addCol, and then, in the document command area, click the button labeled InsertColumn. A new column will be installed in the table, in front of the selected column, with information identical to the selected column. Similarly, you can AppendColumn, DeleteColumn, InsertRow, AppendRow, or DeleteRow. (Warning: don't delete all of the rows or columns from the table.)

In order to further manipulate the table, we need to redisplay the control information for the table. Select any cell in the table, and click ToggleControlVisibility. The control information should now be visible again.

Observe that in the document commands, there are two rows, one starting with SetRow and the next starting with SetColumn. These are the buttons for controlling the row and column controls in a table. For example, select any cell in any column controled by <+exp>; now, in the command row starting with SetColumn, click the button labeled -exp. Observe that the displayed column control changes to <-exp>, and that cells in this column now subtract from their row sums, rather than add to them.

One can display partial row sums in any column by setting its control to sum. One can display the final row totals in any column by setting the column control to total.

The controls +0, lv*exp, and lv are used together to provide pairs of columns whose pairs of values are multiplied together before being added to their row sum. Pick three successive columns currently containing numerical quantitities contributing to row sums. Set the first to +0, the second to lv*exp and the third to lv. The result of this is that in each row, the quantity in the first column (controled with +0) is multiplied by the quantity in the second column (controled with lv*exp) and the product is added to the row sums. The third column (labeled lv) displays the product. (In general, an lv column displays the value in the columns to its left, but does not contribute to row sums.)

The control information itself is displayed in any row or column controled by con. Thus, if one desired, one could delete such rows and columns, but this would be confusing; furthermore the same effect is obtained by using the ToggleControlVisibility command. Also, if one was sufficiently zany, one could have more than one column or row controled by con;

As a final step in manipulating a table, we shall reset the text to be displayed for derived zero values, and the table name. First, arrange for some column or row sum to be zero, and for this value to be displayed. Observe that it is displayed as "0.00". Observe in the document command area, a command labeled setZvt followed by 0.00. Change the 0.00 to z. Now select any cell in the table, and click setZvt. The control information labeled <zvt:...> now shows z. Arrange for any column or row sum to be zero. Observe that now any derieved zero value is displayed as a z. One can choose any non empty text, e.g. a single space character.

Now we change the table name. Observe in the document command area, a command labeled SetTableId followed by newTableId. Change newTableId to be ExampleTable. Now select any cell in the table, and click SetTableId. The control information labeled <id: ...> changes to <id: ExampleTable>.

Finally, after making sure that some cell in the table is selected, click ToggleControlVisibility. The control information is removed and are we are left with a clean table. (The array name is still displayed, as ExampleTable.)

It is possible use expressions rather than just numbers. The following operators are available: +, -, *, /, (). Some simple conditionals can also be written, in the form IF exp relOp exp THEN exp ELSE exp. Unfortunately, at the moment it is difficult to use complex expressions because they force columns to be too wide. Try selecting an input number and replacing it with an expression involving numbers, e.g. 7.6+4.5*3.

If you type in an expression with bad syntax, this is recognized by NewCalc during a subsequent adjust action. Adjust modifies the typed in expression by bracketing it with triples of &. For example, 4++6 is replaced by &&&4++6&&&. Furthermore, the value of the old expresion is used for the cell in dependent calculations, leading to some confusing numbers in other cells.

Identifiers may be used in expressions, and assigned values. An identifier is any sequence of letters and digits, starting with a letter. (NewCalc does not currently correctly check for this rule, but it will in the future.) For example: Tax84, and Income83 are identifiers. An identifer may be used in place of a number in any expression. For example, principal*interest is an expression.

An identifier is assigned a value by placing it in any column controled by one of id←t, id←s, or id←lv. In the first case, the identifier is assigned as value the final row total in which it lies, in the second case it is assigned the intermediate row sum, and in the third case it is assigned the value occuring in the cell to its left.

For example, modify the table so that there are 6 columns, controlled as follows: con, id←t, text, +exp, text, total.

Now, modify the rows so that they are controled as follows: con, +exp, +exp, +exp, ... . Next, modify the cells in the first text column to contain ← and in the second column to contain =. Finally, place appropriate identifiers in the column controled by id←t, and appropriate expressions in the column controled by +exp. After turning off control visibility, one can arrive at a table that looks roughly like:

In this table, there is exactly one expression contributing to each row sum. This row sum is assigned to an identifer in the first column, and displayed in the last column.

There is no requirement that expressions use identifiers that have been assigned to earlier in the text, an identifier may be assigned to any where and used anywhere.

So as to assist in the passing of information from one table to another, identifiers are really treated as having three parts: a page id, a table id, and a final id. For example, if the above described table occured on a page named foo, then the two identifiers used in the above table are really foo.newTableId.a and foo.newTableId.b.

Any identifier appearing in an id← column has the appropriate suffix automatically added, and any identifier appearing in an expression has as much suffix added as is needed. For example, one could use the value of a in some other table on the same page by writing newTableId.a, and on some other page by writing foo.newTableId.a.

We will see how to use these features when we see how to create multiple tables and multiple pages.

A page is a column of rows of tables. A new table is added to a page by first creating a slot in the desired position, selecting the slot, and then clicking CreateTable. The mechanism for creating a slot in the desired position is somewhat arcane. There are two command buttons, InsertSlot, and AppendSlot. If the current selection is in a table or in a slot, and one of these commands is clicked, a new slot will appear before or after the selected item, in the same row as the selected item.

In order to introduce new rows, the commands AppendRow and InsertRow are arranged to create new rows of slots if the current selected item is a slot.

For example, let us create a new table below the existing one. Choose a name for the new table, e.g. TableTwo.

Warning: If some cell in a table is selected, and DeleteSlot is clicked, the table is deleted!

A document is a sequence of pages. This structure is displayed in the lower part of the document viewer. At the moment, the document is a single page, and this is shown by a line containing page1 foo, where foo is the name of the page.

The name of a page can be changed. In the commmand region of the document viewer, there is a line of the form newPageId: pageName. Change the text of pageName to any desired new name, e.g. NewPageName. Select one of the words in the line page1 foo, and in the command region, click SetPageId. The page name in the lower part of the document viewer changes, as well as the page name in the page displayer.

Now, lets add a new page to the document. First choose a new name, e.g. SecondName. In the command region of the document viewer, replace the text following newPageId: with SecondName. Now, in the lower part of the document viewer, select either of page1 or NewPageName and, in the command region of the document viewer, click InsertPage. There are now two lines of text in the lower part of the document viewer: page1 SecondName followed by page2 NewPageName. The document now has two pages. The old page is now page2, and the new page is page1. There is a new icon, which is page1. Open the new icon, and observe that this is a clean page, containing its name, SecondName, and a single slot. This page may be manipulated just like the original page.

Consecutive pages may be treated as a group. To form a group, select any existing page (in the lower part of the document viewer), and in the upper part of the document viewer, click MakeSummaryPage. The selected entry in the lower part of the document viewer now has the word summary appended. This is a one page group.

Pages in the document have three flavors: individual, summary, or item. Pages outside of a group are individual pages. A page group consists of a summary page followed by zero or more item pages. If a page belongs to a group, this is indicated by appending its flavor to the line of text describing the page.

Additional pages may be added to a group by selecting existing pages in the group and clicking either InsertPage or AppendPage. These newly created item pages are built as copies of the previously selected page. Hence, if the new page is named the same as the old page, and if there were any identifiers in the selected page that were assigned to, the multiple assignment to an identifier message will occur. The fix is to change the name of the new page.

Sometimes InsertPage and AppendPage create individual pages, rather than pages in the group. For example, inserting before a summary page creates an individual page, and appending after the last item page, if it is also the last page in the document, creates an individual page.

The purpose of page groups is to allow Table Groups. A table group is a collection of item tables together with one summary table. The column structure of the tables are identical, and each data row in the summary table contains the column totals for one of the item tables.

To form a table group, proceed as follows:

There is now a new table group, spread out among the pages of the page Group. The summary table is on the summary page, and the item tables are on the item pages.

Documents may be saved on files, loaded from files, and printed. Saved documents may have a primitive form of encryption.

To print a document. In the command region of the document viewer, click Show. Now, in your commander, execute "print -p -s 8 -n 1 print.calc". This will print the document in Gacha8, in protrait mode. The parameters to print can be changed to use Gach6, or landscape mode, as desired.

To save a document, click save. The document will be written to a file whose name is composed form the displayed working dir, together with the displayed save File Name. These two names may be edited by the user before clicking save.

To load a previously saved document, click load. The file name is constructed exactly as in the case of save.

A document may be saved and loaded in an encrypted form. The encryption key is any sequence of up to about 20 characters. The encryption key is entered in two steps. First, observe the line in the command region of the form setEncryptionKey : + +. In order to set the key, replace the text between and including the two +s, with the desired key. Then click setEncryptionKey. All subsequent saves and loads will use this key. Note that the + + is replaced by a sequence of *s. The key can be changed by replacing this sequence with the new key, and again clicking setEncryptionKey.

If an attempt is made to load a document saved under one encryption using a different key, or no key, an unpleasant Error window will appear.

This program was first written three years ago to allow me to construct my home budget. Initially it could support a single table, with about 100 cells. It was then expanded to support the CSL budget. This turned out to require many tables, with a total of over 2000 cells. In this second version, there was no concept of table group, or of column and row controls. Instead, there were expressions behind each cell to arrange for the desired computation. While this turned out to be adequate to support the CSL budget, there were many problems. Some of these problems involved interactions with the Cedar system, which have been improved by later versions of Cedar. Other problems involved attempts to modify the structure of an existing budget. That second version had various mechanisms for copying tables, and performing text substitutions on the expressions behind the cells. Unfortunately, only one expression could be examined at a time, and with 2000 cells, inconsistencies appeared in the expressions.

In this third version of the program, I have replaced the hidden cell expressions by row and column controls. The row and column controls directly determine what each cell will do. I have also added the concept of table groups. These two mechanisms should remove the necessity for almost all of the expressions used in the old CSL budget.

We shall see how well this works out.

Howard Sturgis: July 24, 1984 2:34:59 pm PDT