1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../../info/ses
4 @settitle @acronym{SES}: Simple Emacs Spreadsheet
12 This file documents @acronym{SES}: the Simple Emacs Spreadsheet.
14 Copyright @copyright{} 2002-2012 Free Software Foundation, Inc.
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
21 and with the Back-Cover Texts as in (a) below. A copy of the license
22 is included in the section entitled ``GNU Free Documentation License.''
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual. Buying copies from the FSF supports it in
26 developing GNU and promoting software freedom.''
30 @dircategory Emacs misc features
32 * @acronym{SES}: (ses). Simple Emacs Spreadsheet.
39 @subtitle Simple Emacs Spreadsheet
40 @author Jonathan A. Yavner
41 @author @email{jyavner@@member.fsf.org}
44 @vskip 0pt plus 1filll
50 @c ===================================================================
53 @node Top, Sales Pitch, (dir), (dir)
54 @comment node-name, next, previous, up
55 @top @acronym{SES}: Simple Emacs Spreadsheet
58 @acronym{SES} is a major mode for GNU Emacs to edit spreadsheet files, which
59 contain a rectangular grid of cells. The cells' values are specified
60 by formulas that can refer to the values of other cells.
64 To report bugs, send email to @email{jyavner@@member.fsf.org}.
69 * Sales Pitch:: Why use @acronym{SES}?
70 * The Basics:: Basic spreadsheet commands
71 * Advanced Features:: Want to know more?
72 * For Gurus:: Want to know @emph{even more}?
73 * Index:: Concept, Function and Variable Index
74 * Acknowledgments:: Acknowledgments
75 * GNU Free Documentation License:: The license for this documentation.
78 @c ===================================================================
80 @node Sales Pitch, The Basics, Top, Top
81 @comment node-name, next, previous, up
86 @item Create and edit simple spreadsheets with a minimum of fuss.
87 @item Full undo/redo/autosave.
88 @item Immune to viruses in spreadsheet files.
89 @item Cell formulas are straight Emacs Lisp.
90 @item Printer functions for control of cell appearance.
91 @item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc.
92 @item ``Spillover'' of lengthy cell values into following blank cells.
93 @item Header line shows column letters or a selected row.
94 @item Completing-read for entering symbols as cell values.
95 @item Cut, copy, and paste can transfer formulas and printer functions.
96 @item Import and export of tab-separated values or tab-separated formulas.
97 @item Plaintext, easily-hacked file format.
100 @c ===================================================================
102 @node The Basics, Advanced Features, Sales Pitch, Top
103 @comment node-name, next, previous, up
105 @cindex basic commands
108 @findex ses-mark-column
109 @findex ses-mark-whole-buffer
110 @findex set-mark-command
111 @findex keyboard-quit
113 To create a new spreadsheet, visit a nonexistent file whose name ends
114 with ".ses". For example, @kbd{C-x C-f test.ses RET}.
117 A @dfn{cell identifier} is a symbol with a column letter and a row
118 number. Cell B7 is the 2nd column of the 7th row. For very wide
119 spreadsheets, there are two column letters: cell AB7 is the 28th
120 column of the 7th row. Super wide spreadsheets get AAA1, etc.
124 Moves point to cell, specified by identifier (@code{ses-jump}).
127 Point is always at the left edge of a cell, or at the empty endline.
128 When mark is inactive, the current cell is underlined. When mark is
129 active, the range is the highlighted rectangle of cells (@acronym{SES} always
130 uses transient mark mode). Drag the mouse from A1 to A3 to create the
131 range A1-A2. Many @acronym{SES} commands operate only on single cells, not
137 Set mark at point (@code{set-mark-command}).
140 Turn off the mark (@code{keyboard-quit}).
143 Highlight current row (@code{ses-mark-row}).
146 Highlight current column (@code{ses-mark-column}).
149 Highlight all cells (@code{mark-whole-buffer}).
155 * Printer functions::
158 * Customizing @acronym{SES}::
161 @node Formulas, Resizing, The Basics, The Basics
162 @section Cell formulas
164 @cindex formulas, entering
165 @findex ses-read-cell
166 @findex ses-read-symbol
167 @findex ses-edit-cell
168 @findex ses-recalculate-cell
169 @findex ses-recalculate-all
171 To enter a number into the current cell, just start typing:
175 Self-insert a digit (@code{ses-read-cell}).
178 Self-insert a negative number (@code{ses-read-cell}).
181 Self-insert a fractional number (@code{ses-read-cell}).
184 Self-insert a quoted string. The ending double-quote
185 is inserted for you (@code{ses-read-cell}).
188 Self-insert an expression. The right-parenthesis is inserted for you
189 (@code{ses-read-cell}). To access another cell's value, just use its
190 identifier in your expression. Whenever the other cell is changed,
191 this cell's formula will be reevaluated. While typing in the
192 expression, you can use @kbd{M-@key{TAB}} to complete symbol names.
194 @item ' @r{(apostrophe)}
195 Enter a symbol (ses-read-symbol). @acronym{SES} remembers all symbols that have
196 been used as formulas, so you can type just the beginning of a symbol
197 and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it.
200 To enter something else (e.g., a vector), begin with a digit, then
201 erase the digit and type whatever you want.
205 Edit the existing formula in the current cell (@code{ses-edit-cell}).
208 Force recalculation of the current cell or range (@code{ses-recalculate-cell}).
211 Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
214 @node Resizing, Printer functions, Formulas, The Basics
215 @section Resizing the spreadsheet
216 @cindex resizing spreadsheets
217 @findex ses-insert-row
218 @findex ses-insert-column
219 @findex ses-delete-row
220 @findex ses-delete-column
221 @findex ses-set-column-width
222 @findex ses-forward-or-insert
223 @findex ses-append-row-jump-first-column
230 (@code{ses-insert-row})
233 (@code{ses-insert-column})
236 (@code{ses-delete-row})
239 (@code{ses-delete-column})
242 (@code{ses-set-column-width})
245 Moves point to the next rightward cell, or inserts a new column if
246 already at last cell on line, or inserts a new row if at endline
247 (@code{ses-forward-or-insert}).
250 Linefeed inserts below the current row and moves to column A
251 (@code{ses-append-row-jump-first-column}).
254 Resizing the spreadsheet (unless you're just changing a column width)
255 relocates all the cell-references in formulas so they still refer to
256 the same cells. If a formula mentioned B1 and you insert a new first
257 row, the formula will now mention B2.
259 If you delete a cell that a formula refers to, the cell-symbol is
260 deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third
261 column becomes @code{(+ A1 B1)}. In case this is not what you wanted:
266 Undo previous action (@code{(undo)}).
270 @node Printer functions, Clearing cells, Resizing, The Basics
271 @section Printer functions
272 @cindex printer functions
273 @findex ses-read-cell-printer
274 @findex ses-read-column-printer
275 @findex ses-read-default-printer
277 @findex ses-center-span
279 @findex ses-dashfill-span
280 @findex ses-tildefill-span
283 Printer functions convert binary cell values into the print forms that
284 Emacs will display on the screen.
286 A printer can be a format string, like @samp{"$%.2f"}. The result
287 string is right-aligned within the print cell. To get left-alignment,
288 use parentheses: @samp{("$%.2f")}. A printer can also be a
289 one-argument function (a symbol or a lambda), whose result is a string
290 (right-aligned) or list of one string (left-aligned). While typing in
291 a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols.
293 Each cell has a printer. If @code{nil}, the column-printer for the cell's
294 column is used. If that is also @code{nil}, the default-printer for the
299 Enter a printer for current cell or range (@code{ses-read-cell-printer}).
302 Enter a printer for the current column (@code{ses-read-column-printer}).
305 Enter the default printer for the spreadsheet
306 (@code{ses-read-default-printer}).
309 The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer
310 history, which is preloaded with the set of all printers used in this
311 spreadsheet, plus the standard printers.
313 The standard printers are suitable only for cells, not columns or
314 default, because they format the value using the column-printer (or
315 default-printer if @code{nil}) and then center the result:
321 @item ses-center-span
322 Centering with spill-over to following blank cells.
325 Centering using dashes (-) instead of spaces.
327 @item ses-dashfill-span
328 Centering with dashes and spill-over.
330 @item ses-tildefill-span
331 Centering with tildes (~) and spill-over.
335 @node Clearing cells, Copy/cut/paste, Printer functions, The Basics
336 @section Clearing cells
337 @cindex clearing commands
338 @findex ses-clear-cell-backward
339 @findex ses-clear-cell-forward
341 These commands set both formula and printer to @code{nil}:
345 Clear cell and move left (@code{ses-clear-cell-backward}).
348 Clear cell and move right (@code{ses-clear-cell-forward}).
352 @node Copy/cut/paste, Customizing @acronym{SES}, Clearing cells, The Basics
353 @section Copy, cut, and paste
357 @findex kill-ring-save
358 @findex mouse-set-region
359 @findex mouse-set-secondary
360 @findex ses-kill-override
362 @findex clipboard-yank
363 @findex mouse-yank-at-click
364 @findex mouse-yank-at-secondary
367 The copy functions work on rectangular regions of cells. You can paste the
368 copies into non-@acronym{SES} buffers to export the print text.
374 Copy the highlighted cells to kill ring and primary clipboard
375 (@code{kill-ring-save}).
378 Mark a region and copy it to kill ring and primary clipboard
379 (@code{mouse-set-region}).
381 @item [M-drag-mouse-1]
382 Mark a region and copy it to kill ring and secondary clipboard
383 (@code{mouse-set-secondary}).
388 The cut functions do not actually delete rows or columns---they copy
389 and then clear (@code{ses-kill-override}).
393 Paste from kill ring (@code{yank}). The paste functions behave
394 differently depending on the format of the text being inserted:
397 When pasting cells that were cut from a @acronym{SES} buffer, the print text is
398 ignored and only the attached formula and printer are inserted; cell
399 references in the formula are relocated unless you use @kbd{C-u}.
401 The pasted text overwrites a rectangle of cells whose top left corner
402 is the current cell. If part of the rectangle is beyond the edges of
403 the spreadsheet, you must confirm the increase in spreadsheet size.
405 Non-@acronym{SES} text is usually inserted as a replacement formula for the
406 current cell. If the formula would be a symbol, it's treated as a
407 string unless you use @kbd{C-u}. Pasted formulas with syntax errors
408 are always treated as strings.
412 Paste from primary clipboard or kill ring (@code{clipboard-yank}).
415 Set point and paste from primary clipboard (@code{mouse-yank-at-click}).
418 Set point and paste from secondary clipboard (@code{mouse-yank-secondary}).
421 Immediately after a paste, you can replace the text with a preceding
422 element from the kill ring (@code{ses-yank-pop}). Unlike the standard
423 Emacs yank-pop, the @acronym{SES} version uses @code{undo} to delete the old
424 yank. This doesn't make any difference?
427 @node Customizing @acronym{SES}, , Copy/cut/paste, The Basics
428 @section Customizing @acronym{SES}
430 @vindex enable-local-eval
431 @vindex ses-mode-hook
432 @vindex safe-functions
433 @vindex enable-local-eval
436 By default, a newly-created spreadsheet has 1 row and 1 column. The
437 column width is 7 and the default printer is @samp{"%.7g"}. Each of these
438 can be customized. Look in group ``ses''.
440 After entering a cell value, point normally moves right to the next
441 cell. You can customize @code{ses-after-entry-functions} to move left or
442 up or down. For diagonal movement, select two functions from the
445 @code{ses-mode-hook} is a normal mode hook (list of functions to
446 execute when starting @acronym{SES} mode for a buffer).
448 The variable @code{safe-functions} is a list of possibly-unsafe
449 functions to be treated as safe when analyzing formulas and printers.
450 @xref{Virus protection}. Before customizing @code{safe-functions},
451 think about how much you trust the person who's suggesting this
452 change. The value @code{t} turns off all anti-virus protection. A
453 list-of-functions value might enable a ``gee whiz'' spreadsheet, but it
454 also creates trapdoors in your anti-virus armor. In order for virus
455 protection to work, you must always press @kbd{n} when presented with
456 a virus warning, unless you understand what the questionable code is
457 trying to do. Do not listen to those who tell you to customize
458 @code{enable-local-eval}---this variable is for people who don't wear
462 @c ===================================================================
464 @node Advanced Features, For Gurus, The Basics, Top
465 @chapter Advanced Features
466 @cindex advanced features
467 @findex ses-read-header-row
472 (@code{ses-set-header-row}).
473 @findex ses-set-header-row
475 The header line at the top of the @acronym{SES}
476 window normally shows the column letter for each column. You can set
477 it to show a copy of some row, such as a row of column titles, so that
478 row will always be visible. Default is to set the current row as the
479 header; use C-u to prompt for header row. Set the header to row 0 to
480 show column letters again.
481 @item [header-line mouse-3]
482 Pops up a menu to set the current row as the header, or revert to
484 @item M-x ses-rename-cell
485 @findex ses-rename-cell
486 Rename a cell from a standard A1-like name to any
488 @item M-x ses-repair-cell-reference-all
489 @findex ses-repair-cell-reference-all
490 When you interrupt a cell formula update by clicking @kbd{C-g}, then
491 the cell reference link may be broken, which will jeopardize automatic
492 cell update when any other cell on which it depends is changed. To
493 repair that use function @code{ses-repair-cell-reference-all}
498 * Ranges in formulas::
499 * Sorting by column::
500 * Standard formula functions::
501 * More on cell printing::
502 * Import and export::
504 * Spreadsheets with details and summary::
507 @node The print area, Ranges in formulas, Advanced Features, Advanced Features
508 @section The print area
511 @findex ses-renarrow-buffer
512 @findex ses-reprint-all
514 A @acronym{SES} file consists of a print area and a data area. Normally the
515 buffer is narrowed to show only the print area. The print area is
516 read-only except for special @acronym{SES} commands; it contains cell values
517 formatted by printer functions. The data area records the formula and
518 printer functions, etc.
522 Show print and data areas (@code{widen}).
525 Show only print area (@code{ses-renarrow-buffer}).
529 Recreate print area by reevaluating printer functions for all cells
530 (@code{ses-reprint-all}).
533 @node Ranges in formulas, Sorting by column, The print area, Advanced Features
534 @section Ranges in formulas
536 @findex ses-insert-range-click
537 @findex ses-insert-range
538 @findex ses-insert-ses-range-click
539 @findex ses-insert-ses-range
547 is the sum of three specific cells. If you insert a new second row,
552 and the new row is not included in the sum.
554 The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of
555 the values in a rectangle of cells. If your formula is
557 (apply '+ (ses-range A1 A3))
559 and you insert a new second row, it becomes
561 (apply '+ (ses-range A1 A4))
563 and the new row is included in the sum.
565 While entering or editing a formula in the minibuffer, you can select
566 a range in the spreadsheet (using mouse or keyboard), then paste a
567 representation of that range into your formula. Suppose you select
572 Inserts "A1 B1 C1" @code{(ses-insert-range-click})
575 Keyboard version (@code{ses-insert-range}).
578 Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}).
581 Keyboard version (@code{ses-insert-ses-range}).
584 If you delete the @var{from} or @var{to} cell for a range, the nearest
585 still-existing cell is used instead. If you delete the entire range,
586 the formula relocator will delete the ses-range from the formula.
588 If you insert a new row just beyond the end of a one-column range, or
589 a new column just beyond a one-row range, the new cell is included in
590 the range. New cells inserted just before a range are not included.
592 Flags can be added to @code{ses-range} immediately after the @var{to}
596 Empty cells in range can be removed by adding the @code{!} flag. An
597 empty cell is a cell the value of which is one of symbols @code{nil}
598 or @code{*skip*}. For instance @code{(ses-range A1 A4 !)} will do the
599 same as @code{(list A1 A3)} when cells @code{A2} and @code{A4} are
602 Empty cell values are replaced by the argument following flag
603 @code{_}, or @code{0} when flag @code{_} is last in argument list. For
604 instance @code{(ses-range A1 A4 _ "empty")} will do the same as
605 @code{(list A1 "empty" A3 "empty")} when cells @code{A2} and @code{A4}
606 are empty. Similarly, @code{(ses-range A1 A4 _ )} will do the same as
607 @code{(list A1 0 A3 0)}.
609 When order matters, list cells by reading cells row-wise from top left
610 to bottom right. This flag is provided for completeness only as it is
611 the default reading order.
613 List cells by reading cells row-wise from top right to bottom left.
615 List cells by reading cells column-wise from top left to bottom right.
617 List cells by reading cells column-wise from top right to bottom left.
619 A short hand for @code{v>}.
621 A short hand for @code{^>}.
623 A short hand for @code{>v}.
625 A short hand for @code{>^}.
627 Instead of listing cells, it makes a Calc vector or matrix of it
628 (@pxref{Top,,,calc,GNU Emacs Calc Manual}). If the range contains only
629 one row or one column a vector is made, otherwise a matrix is made.
631 Same as @code{*} except that a matrix is always made even when there
632 is only one row or column in the range.
634 Same as @code{*} except that a vector is always made even when there
635 is only one row or column in the range, that is to say the
636 corresponding matrix is flattened.
639 @node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
640 @section Sorting by column
642 @findex ses-sort-column
643 @findex ses-sort-column-click
647 Sort the cells of a range using one of the columns
648 (@code{ses-sort-column}). The rows (or partial rows if the range
649 doesn't include all columns) are rearranged so the chosen column will
652 @item [header-line mouse-2]
653 The easiest way to sort is to click mouse-2 on the chosen column's header row
654 (@code{ses-sort-column-click}).
657 The sort comparison uses @code{string<}, which works well for
658 right-justified numbers and left-justified strings.
660 With prefix arg, sort is in descending order.
662 Rows are moved one at a time, with relocation of formulas. This works
663 well if formulas refer to other cells in their row, not so well for
664 formulas that refer to other rows in the range or to cells outside the
668 @node Standard formula functions, More on cell printing, Sorting by column, Advanced Features
669 @section Standard formula functions
670 @cindex standard formula functions
673 @findex ses-delete-blanks
677 Oftentimes you want a calculation to exclude the blank cells. Here
678 are some useful functions to call from your formulas:
681 @item (ses-delete-blanks &rest @var{args})
682 Returns a list from which all blank cells (value is either @code{nil} or
683 '*skip*) have been deleted.
685 @item (ses+ &rest @var{args})
686 Sum of non-blank arguments.
688 @item (ses-average @var{list})
689 Average of non-blank elements in @var{list}. Here the list is passed
690 as a single argument, since you'll probably use it with @code{ses-range}.
693 @node More on cell printing, Import and export, Standard formula functions, Advanced Features
694 @section More on cell printing
695 @cindex cell printing, more
696 @findex ses-truncate-cell
697 @findex ses-recalculate-cell
701 @item nil prints the same as "", but allows previous cell to spill over.
702 @item '*skip* replaces nil when the previous cell actually does spill over;
703 nothing is printed for it.
704 @item '*error* indicates that the formula signaled an error instead of
705 producing a value: the print cell is filled with hash marks (#).
708 If the result from the printer function is too wide for the cell and
709 the following cell is @code{nil}, the result will spill over into the
710 following cell. Very wide results can spill over several cells. If
711 the result is too wide for the available space (up to the end of the
712 row or the next non-@code{nil} cell), the result is truncated if the cell's
713 value is a string, or replaced with hash marks otherwise.
715 @acronym{SES} could get confused by printer results that contain newlines or
716 tabs, so these are replaced with question marks.
720 Confine a cell to its own column (@code{ses-truncate-cell}). This
721 allows you to move point to a rightward cell that would otherwise be
722 covered by a spill-over. If you don't change the rightward cell, the
723 confined cell will spill over again the next time it is reprinted.
726 When applied to a single cell, this command displays in the echo area
727 any formula error or printer error that occurred during
728 recalculation/reprinting (@code{ses-recalculate-cell}). You can use
729 this to undo the effect of @kbd{t}.
732 When a printer function signals an error, the fallback printer
733 @samp{"%s"} is substituted. This is useful when your column printer
734 is numeric-only and you use a string as a cell value. Note that the
735 standard default printer is ``%.7g'' which is numeric-only, so cells
736 that are empty of contain strings will use the fallback printer.
737 @kbd{c} on such cells will display ``Format specifier doesn't match
741 @node Import and export, Virus protection, More on cell printing, Advanced Features
742 @section Import and export
743 @cindex import and export
744 @cindex export, and import
745 @findex ses-export-tsv
746 @findex ses-export-tsf
750 Export a range of cells as tab-separated values (@code{ses-export-tsv}).
752 Export a range of cells as tab-separated formulas (@code{ses-export-tsf}).
755 The exported text goes to the kill ring --- you can paste it into
756 another buffer. Columns are separated by tabs, rows by newlines.
758 To import text, use any of the yank commands where the text to paste
759 contains tabs and/or newlines. Imported formulas are not relocated.
761 @node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features
762 @section Virus protection
763 @cindex virus protection
765 Whenever a formula or printer is read from a file or is pasted into
766 the spreadsheet, it receives a ``needs safety check'' marking. Later,
767 when the formula or printer is evaluated for the first time, it is
768 checked for safety using the @code{unsafep} predicate; if found to be
769 ``possibly unsafe'', the questionable formula or printer is displayed
770 and you must press Y to approve it or N to use a substitute. The
771 substitute always signals an error.
773 Formulas or printers that you type in are checked immediately for
774 safety. If found to be possibly unsafe and you press N to disapprove,
775 the action is canceled and the old formula or printer will remain.
777 Besides viruses (which try to copy themselves to other files),
778 @code{unsafep} can also detect all other kinds of Trojan horses, such as
779 spreadsheets that delete files, send email, flood Web sites, alter
780 your Emacs settings, etc.
782 Generally, spreadsheet formulas and printers are simple things that
783 don't need to do any fancy computing, so all potentially-dangerous
784 parts of the Emacs Lisp environment can be excluded without cramping
785 your style as a formula-writer. See the documentation in @file{unsafep.el}
786 for more info on how Lisp forms are classified as safe or unsafe.
788 @node Spreadsheets with details and summary, , Virus protection, Advanced Features
789 @section Spreadsheets with details and summary
790 @cindex details and summary
791 @cindex summary, and details
793 A common organization for spreadsheets is to have a bunch of ``detail''
794 rows, each perhaps describing a transaction, and then a set of
795 ``summary'' rows that each show reduced data for some subset of the
796 details. @acronym{SES} supports this organization via the @code{ses-select}
800 @item (ses-select @var{fromrange} @var{test} @var{torange})
801 Returns a subset of @var{torange}. For each member in @var{fromrange}
802 that is equal to @var{test}, the corresponding member of @var{torange}
803 is included in the result.
808 (ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5)))
810 This computes the average of the B column values for those rows whose
811 A column value is the symbol 'Smith.
813 Arguably one could specify only @var{fromrange} plus
814 @var{to-row-offset} and @var{to-column-offset}. The @var{torange} is
815 stated explicitly to ensure that the formula will be recalculated if
816 any cell in either range is changed.
818 File @file{etc/ses-example.el} in the Emacs distribution is an example of a
819 details-and-summary spreadsheet.
822 @c ===================================================================
824 @node For Gurus, Index, Advanced Features, Top
826 @cindex advanced features
830 * Nonrelocatable references::
832 * Buffer-local variables in spreadsheets::
833 * Uses of defadvice in @acronym{SES}::
836 @node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
837 @section Deferred updates
838 @cindex deferred updates
839 @cindex updates, deferred
840 @vindex run-with-idle-timer
842 To save time by avoiding redundant computations, cells that need
843 recalculation due to changes in other cells are added to a set. At
844 the end of the command, each cell in the set is recalculated once.
845 This can create a new set of cells that need recalculation. The
846 process is repeated until either the set is empty or it stops changing
847 (due to circular references among the cells). In extreme cases, you
848 might see progress messages of the form ``Recalculating... (@var{nnn}
849 cells left)''. If you interrupt the calculation using @kbd{C-g}, the
850 spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or
851 @kbd{C-c C-l} to fix it.
853 To save even more time by avoiding redundant writes, cells that have
854 changes are added to a set instead of being written immediately to the
855 data area. Each cell in the set is written once, at the end of the
856 command. If you change vast quantities of cells, you might see a
857 progress message of the form ``Writing... (@var{nnn} cells left)''.
858 These deferred cell-writes cannot be interrupted by @kbd{C-g}, so
859 you'll just have to wait.
861 @acronym{SES} uses @code{run-with-idle-timer} to move the cell underline when
862 Emacs will be scrolling the buffer after the end of a command, and
863 also to narrow and underline after @kbd{C-x C-v}. This is visible as
864 a momentary glitch after C-x C-v and certain scrolling commands. You
865 can type ahead without worrying about the glitch.
868 @node Nonrelocatable references, The data area, Deferred updates, For Gurus
869 @section Nonrelocatable references
870 @cindex nonrelocatable references
871 @cindex references, nonrelocatable
873 @kbd{C-y} relocates all cell-references in a pasted formula, while
874 @kbd{C-u C-y} relocates none of the cell-references. What about mixed
881 to make an @dfn{absolute reference}. The formula relocator skips over
882 quoted things, so this will not be relocated when pasted or when
883 rows/columns are inserted/deleted. However, B3 will not be recorded
884 as a dependency of this cell, so this cell will not be updated
885 automatically when B3 is changed.
887 The variables @code{row} and @code{col} are dynamically bound while a
888 cell formula is being evaluated. You can use
890 (ses-cell-value row 0)
892 to get the value from the leftmost column in the current row. This
893 kind of dependency is also not recorded.
896 @node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus
897 @section The data area
899 @findex ses-reconstruct-all
901 Begins with an 014 character, followed by sets of cell-definition
902 macros for each row, followed by column-widths, column-printers,
903 default-printer, and header-row. Then there's the global parameters
904 (file-format ID, numrows, numcols) and the local variables (specifying
905 @acronym{SES} mode for the buffer, etc.)
907 When a @acronym{SES} file is loaded, first the numrows and numcols values are
908 loaded, then the entire data area is @code{eval}ed, and finally the local
909 variables are processed.
911 You can edit the data area, but don't insert or delete any newlines
912 except in the local-variables part, since @acronym{SES} locates things by
913 counting newlines. Use @kbd{C-x C-e} at the end of a line to install
914 your edits into the spreadsheet data structures (this does not update
915 the print area, use, e.g., @kbd{C-c C-l} for that).
917 The data area is maintained as an image of spreadsheet data
918 structures that area stored in buffer-local variables. If the data
919 area gets messed up, you can try reconstructing the data area from the
924 (@code{ses-reconstruct-all}).
928 @node Buffer-local variables in spreadsheets, Uses of defadvice in @acronym{SES}, The data area, For Gurus
929 @section Buffer-local variables in spreadsheets
930 @cindex buffer-local variables
931 @cindex variables, buffer-local
933 You can add additional local variables to the list at the bottom of
934 the data area, such as hidden constants you want to refer to in your
937 You can override the variable @code{ses--symbolic-formulas} to be a list of
938 symbols (as parenthesized strings) to show as completions for the '
939 command. This initial completions list is used instead of the actual
940 set of symbols-as-formulas in the spreadsheet.
942 For an example of this, see file @file{etc/ses-example.ses}.
944 If (for some reason) you want your formulas or printers to save data
945 into variables, you must declare these variables as buffer-locals in
946 order to avoid a virus warning.
948 You can define functions by making them values for the fake local
949 variable @code{eval}. Such functions can then be used in your
950 formulas and printers, but usually each @code{eval} is presented to
951 the user during file loading as a potential virus --- this can get
954 You can define functions in your @file{.emacs} file. Other people can
955 still read the print area of your spreadsheet, but they won't be able
956 to recalculate or reprint anything that depends on your functions. To
957 avoid virus warnings, each function used in a formula needs
959 (put 'your-function-name 'safe-function t)
962 @node Uses of defadvice in @acronym{SES}, , Buffer-local variables in spreadsheets, For Gurus
963 @section Uses of defadvice in @acronym{SES}
966 @cindex copy-region-as-kill
971 Defines a new undo element format (@var{fun} . @var{args}), which
972 means ``undo by applying @var{fun} to @var{args}''. For spreadsheet
973 buffers, it allows undos in the data area even though that's outside
976 @item copy-region-as-kill
977 When copying from the print area of a spreadsheet, treat the region as
978 a rectangle and attach each cell's formula and printer as 'ses
982 When yanking into the print area of a spreadsheet, first try to yank
983 as cells (if the yank text has 'ses properties), then as tab-separated
984 formulas, then (if all else fails) as a single formula for the current
988 @c ===================================================================
989 @node Index, Acknowledgments, For Gurus, Top
994 @c ===================================================================
996 @node Acknowledgments, GNU Free Documentation License, Index, Top
997 @chapter Acknowledgments
1001 Jonathan Yavner @email{jyavner@@member.fsf.org}@*
1002 Stefan Monnier @email{monnier@@gnu.org}@*
1003 Shigeru Fukaya @email{shigeru.fukaya@@gmail.com}
1009 Jonathan Yavner @email{jyavner@@member.fsf.org}@*
1010 Brad Collins <brad@@chenla.org>
1016 Christoph Conrad @email{christoph.conrad@@gmx.de}@*
1017 CyberBob @email{cyberbob@@redneck.gacracker.org}@*
1018 Syver Enstad @email{syver-en@@online.no}@*
1019 Ami Fischman @email{fischman@@zion.bpnetworks.com}@*
1020 Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@*
1021 Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@*
1022 Yusong Li @email{lyusong@@hotmail.com}@*
1023 Juri Linkov @email{juri@@jurta.org}@*
1024 Harald Maier @email{maierh@@myself.com}@*
1025 Alan Nash @email{anash@@san.rr.com}@*
1026 François Pinard @email{pinard@@iro.umontreal.ca}@*
1027 Pedro Pinto @email{ppinto@@cs.cmu.edu}@*
1028 Stefan Reichör @email{xsteve@@riic.at}@*
1029 Oliver Scholz @email{epameinondas@@gmx.de}@*
1030 Richard M. Stallman @email{rms@@gnu.org}@*
1031 Luc Teirlinck @email{teirllm@@dms.auburn.edu}@*
1032 J. Otto Tennant @email{jotto@@pobox.com}@*
1033 Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr}
1036 @c ===================================================================
1038 @node GNU Free Documentation License, , Acknowledgments, Top
1039 @appendix GNU Free Documentation License
1040 @include doclicense.texi