Scheme

Siag uses Scheme for commands and expressions. This means that the program can be easily extended with new functions. When Load is chosen from the File menu, for instance, the Lisp function (load-buffer) is called. It is thus possible to make File - Load do something completely different by writing a new load-buffer function, perhaps adding the ability to read other file formats.

Documentation for Siod, the Scheme interpreter used in Siag

Cell references

References to cells in the sheet can be done using A1 or R1C1 notation. Note that this is a nonstandard extension to the Scheme language which means that symbols cannot have names that start with one or more letters and finishes with one or more digits.

When lines and columns are inserted or removed, the references are automatically updated.

There is also a functional interface to the spreadsheet contents.

(get-cell row column): Returns the value of the cell.
(x-get-cell row column buffer): Cross-references between buffers are possible by specifying the buffer name. The buffer must be loaded.
(get-string row column): Returns the value of the cell in the form of a string, regardless of what's actually there: a string, a number, a label, an error or nothing.
(x-get-string row column buffer): The same as get-string, but references another buffer.
(href n): Refers to a cell n columns to the right (left for negative n) of the current cell.
(vref n): Refers to a cell n rows below (above for negative cell) the current cell.
(area-sum r1 c1 r2 c2): The sum of all cells from (r1,c1) to (r2,c2)
(area-min r1 c1 r2 c2): The minimum of all cells from (r1,c1) to (r2,c2)
(area-max r1 c1 r2 c2): The maximum of all cells from (r1,c1) to (r2,c2)
(area-avg r1 c1 r2 c2): The average of all cells from (r1,c1) to (r2,c2)

Additional functions can be defined in $SIAGHOME/siag/siag.scm, where they will be available for all users, or in $HOME/.siagrc, where they will be available for one user only.

Ranges

Certain functions can handle not only numbers and references, but whole ranges of cells. Such ranges are written as, for example, a1..c2 (A1 notation) or r1c1..r2c3 (R1C1 notation). In this case, the range consists of all cells from row 1, column 1 to row 2, column 3 (6 cells altogether). Not all fuctions can handle ranges.

Ranges update when lines and columns are inserted or deleted, just like the references described above.

Functions

Siag adds the following functions to those defined by SIOD:

(backward-cell): Move point one cell to the left.
(forward-cell): Move point one cell to the right.
(next-line): Move point one line down.
(previous-line): Move point one line up.
(beginning-of-line): Move point to column 1.
(end-of-line): Move point to the last used cell in the current line.
(beginning-of-buffer): Move point to column 1, line 1.
(end-of-buffer): Move point to the last used cell in the last used line.
(top-of-buffer): Move point to line 1 without changing the column.
(bottom-of-buffer): Move point to the last used line without changing the column.
(scroll-up): Move the window up one windowful.
(scroll-cell-up): Move the window up one line.
(scroll-down): Move the window down one windowful.
(scroll-cell-down): Move the window down one line.
(scroll-left): Move the window left one windowful.
(scroll-cell-left): Move the window left one column.
(scroll-right): Move the window right one windowful.
(scroll-cell-right): Move the window right one column.
(what-cursor-position): Prints information about the contents of the current cell on the status bar.
(delete-cell): Delete the contents of the current cell.
(insert-line): Insert an empty line, moving the rest of the document down.
(edit-label): Create a label in the current cell.
(edit-expression): Create an expression in the current cell.
(set-mark-command): Move mark to the current cell.
(exchange-point-and-mark): Swap point and mark.
(kill-region): Should delete everything between point and mark for compatibility with Emacs, but currently does nothing. Block commands are available for that purpose.
(copy-block): Copy the block to the rectangular area with its top left corner in the current cell. If the block overlaps the destination area, useful fill operations can be achieved.
(intelligent-copy-block): Copies the block in such a way that overlapping areas are handled correctly.
(delete-block): Deletes all the cells in block.
(print-block): Dumps the block to a text file.
(set-block): Sets the block to be the area between mark and point.
(save-block-file): What does this do?
(new-siag): Loads a new Siag window.
(load-buffer): Loads a Siag document into a new buffer.
(save-buffer): Saves the current buffer as a Siag document.
(save-buffer-as): Saves the current buffer using a new file name.
(print-version): Prints version information on the status bar.
(help-contents): Starts the Chimera program with siag.html as argument.
(help-search): Search for keyword. Currently not implemented.
(help-for-help): Starts the Chimera program with siaghelp.html as argument.
(recenter): Redraws the screen.
(recalc-matrix): Recalculates all the cells once. If the are circular references, this may need to be repeated.
(execute-extended-command): Read and execute a Scheme command.
(keyboard-quit): Abort a multi-key command sequence.
(quit-siag): Exit from Siag. If there are any unsaved changes, asks if they should be saved.
(no-op): Does nothing. Sometimes useful for debugging.

Functions available for expressions

Hundreds of string and/or numeric functions are available. The full reference is here. The reference shows the standard syntax, not the Scheme syntax. The mapping between the two is trivial.

There are three ways to execute Scheme code:

Enter it as an expression in a cell
Press ( or Alt-X and type it in the input window
Load it from a file using (load "filename")

A file can be loaded on startup by giving the option -iFilename on the command line. A useful file to load is siod.scm which adds common functions like caar, cadr and the like.

There is no difference between functions that are intended for commands and those that are intended for expressions. It is quite possible to enter the function (forward-cell) into a cell, making the point move forward every time the sheet is recalculated (a command cannot be entered directly as it returns nil and an expression must return a number, but it can be entered as (begin (forward-cell) 0), which returns 0).

It is also possible to make the program compute the sum (+ 1 2) every time a certain key is pressed. Not very useful (except for debugging), but possible. This is done by changing the keybindings in the resource file.

Examples

123.4: The constant 123.4
(- (+ 1 2) 3): This evaluates to 0
(get-cell 3 4): The contents of the cell in row 3, column 4
(get-cell R (- C 1)): The contents of the cell immediately to the left of the current cell
(href -1): The same as above
(+ r2c3 r2c4): The sum of the value in row 2, column 3 and the value in row 2, column 4
(+ c2 d2): The same as above, except that A1 notation was used instead of R1C1.
(acos r3c1): Arc cosine of the value in row 3, column 1.
(tan r2c2): Tangent of r2c2.
(/ (sin r2c2) (cos r2c2)): Also tangent of r2c2.
(pow temp 0.25): The variable temp raised to the power of 1/4.
(pow temp (/ 1 4)): The same as above.
(asin (sin 1.59)): This evaluates to 1.59
(r_sum r2c2..r5c6 r1c1 12): The sum of all numbers between row 2, column 2 and row 5, column 6; the number in row 1, column 1; and the number 12.

Command Reference

(load-buffer)

Asks for a file name and opens the file with that name as a Siag document.

(new-buffer)

Opens a new empty Siag window.

(preview)

Preview the contents of the current buffer.

(print)

Prints the current buffer using the lpr command.

(save-buffer)

Saves the currently open document using the most recently used filename. If no name has been given to the document, the name "noname.siag" is used.

(save-buffer-as)

Asks for a filename and saves the currently open document using that filename.

(load-external)

Calls an external program to load a document. This can be used to load over a network, using a program like httpget. The program must print the document on stdout.

(save-external)

Calls an external program to save a document. The program must read the document from stdin.

(quit-program)

Quits from Siag. If there are any changes that have not been saved, Siag asks if they should be saved.

(undo-restore)

Undoes the latest undoable operation. Not all operations can be undone; in particular, operations involving very large ranges of cells can require so much space that it is not realistic to store the previous state. Also, some commands simply don't implement undo.

(delete-cell)

Delete the contents of the current cell.

(insert-line)

Insert a line into the document, shifting the rest of the document down.

(remove-line)

Remove one line, shifting the rest of the document up.

(insert-col)

Insert one column, shifting the rest of the document right.

(remove-col)

Remove one column, shifting the rest of the document left.

(select-all)

Select every cell in the grid.

(search-forward)

Search the grid for a cell where the text matches a string.

(search-backward)

Like Find, but search backwards.

(edit-label)

Asks for a label to insert into the current cell.

(edit-siod)

Asks for a SIOD expression to insert into the current cell.

(edit-c)

Asks for a C expression to insert into the current cell.

(edit-guile)

Asks for a Guile expression to insert into the current cell. Requires the optional Guile interpreter.

(edit-tcl)

Asks for a Tcl expression to insert into the current cell. Requires the optional Tcl interpreter.

(set-mark-command)

Moves the mark to the current cell.

(set-block)

Sets the block to be the rectangular area between the mark and the current cell.

(unset-block)

Clears the block from the grid.

(copy-block)

Copies the contents of the block to the area to the right and below the current cell.

(delete-block)

Deletes all the cells in the block.

(fill-block)

Fill every cell in the selection with a single value or a pattern of values.

(block-sum)

Inserts a formula calculating the sum of the cells in the block into the current cell.

(block-min)

Inserts a formula calculating the smallest value of the cells in the block into the current cell.

(block-max)

Inserts a formula calculating the largest value of the cells in the block into the current cell.

(block-avg)

Inserts a formula calculating the average of the cells in the block into the current cell.

(block-borders 0/1/2/3)

0: Removes borders from every cell in the block.
1: Puts borders around the block.
2: Puts borders around every cell in the block.
3: Puts borders under the last line of the block.

(set-cell-width)

Sets the width in pixels of the current column.

(fit-block-width)

Sets the width of every column in the selection to be just wide enough for the values that are to be displayed.

(set-cell-height)

Sets the height in pixels of the current row.

(fit-block-height)

Sets the height of every row in the selection to be just high enough for the values that are to be displayed.

(define-style)

All the styles can be redefined, given a little care and understanding of how printf works. Most formats are simply variations of floating point, but Integer and Hex are by definition integer and are called with integer arguments. Date and Time are really weird and should be more flexible.

(new-attribute "family"/"style"/"fg"/"bg")

Change the way the current cell or the selection looks.

(data-record-edit)

Enter values into a record, where the field names are taken from the first line of the block. This way, all a user has to do is to set the block where the database is to be, put the cursor on the line where he wants to edit a record and select Data - Edit Record.

(data-entry)

This function is useful when entering data into many cells. After a record has been edited, the program automatically moves down one line and continues with the next.

(siag-net port)

Starts a trivial TCP based data server which listens on port 8080 and understands the following commands:

PUT r1 c1 r2 c2: Reads one label per line and puts them into r1c1..r2c2.
GET r1 c1 r2 c2: Prints one label per line from the range r1c1..r2c2.
QUIT: Exits the server and returns to Siag.

Note that once the server is started, Siag no longer responds to user input until it recieves a QUIT command.