2 Quick Tutorial

If you want to get started quickly and think that you know what to expect from a simple spreadsheet, this chapter may be all that you need.

First, visit a new file with the .ses file name extension. Emacs presents you with an empty spreadsheet containing a single cell.

Begin by inserting a headline: "IncomeRET. The double quotes indicate that you are editing a text cell, it is not part of the cell value, and no closing quotation mark is needed.

To insert your first income value, you must first resize the spreadsheet. Press TAB to add a new cell and navigate back up to it. Enter a number, such as ‘2.23’. Then proceed to add a few more income entries, e.g.:

A
 Income
   2.23
   0.02
  15.76
  -4.00

To add up the values, enter a Lisp expression:

(+ A2 A3 A4 A5)

Perhaps you want to add a cell to the right of cell ‘A4’ to explain why you have a negative entry. Pressing TAB in that cell adds an entire new column ‘B’, where you can add such a note.

The column is fairly narrow by default, but pressing w allows you to resize it as needed. Make it 20 characters wide. You can now add descriptive legends for all the entries, e.g.:

A       B
 Income
   2.23       Consulting fee
   0.02     Informed opinion
  15.76       Lemonade stand
     -4          Loan to Joe
  14.01                Total

By default, the cell value print-out is right aligned, that is the reason for such an alignment for the notes in column ‘B’. To change that, you can enter a printer function for the whole column, using e.g., M-p ("%s"). Enclosing "%s" into a list tells SES to align left. You can override a column’s printer function in any individual cell using p.

If Joe pays back his loan, you might blank that entry; e.g., by positioning the cursor in cell A5 and pressing C-d. If you do that, the total printed out in cell A6 will display ‘######’. That is because the value in an empty cell is typically nil, and the regular + operator fails to handle a range that contains that value. Instead of emptying the cell, you could enter a literal ‘0’, or delete the entire row using C-k. An alternative is to use the special function ses+ instead of the regular +:

(ses+ A2 A3 A4 A5)

To make a formula robust against changes in the spreadsheet geometry, you can use the ses-range macro to refer to a range of cells by the end-points, e.g.:

(apply 'ses+ (ses-range A2 A5))

(The apply is necessary because ses-range produces a list of values. This allows for more complex possibilities.)

Alternatively you can use the ! modifier of ses-range to remove blank cells from the returned list, which enables using + instead of ses+:

(apply '+ (ses-range A2 A5 !))

Actually, both options are not exactly equivalent as the former makes the summing in reversed order of argument, and the latter in the same order. You can also reverse the order of arguments returned by ses-range with the < modifier.