*** empty log message ***
[emacs.git] / man / ses.texi
blobff4b47f2ee40c902afdfaac2a6bb9125fdedc43e
1 \input texinfo   @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename ../info/ses
4 @settitle SES: Simple Emacs Spreadsheet
5 @setchapternewpage off
6 @syncodeindex fn cp
7 @syncodeindex vr cp
8 @syncodeindex ky cp
9 @c %**end of header
11 @copying
12 This file documents SES: the Simple Emacs Spreadsheet.
14 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007
15 Free Software Foundation, Inc.
17 @quotation
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.2 or
20 any later version published by the Free Software Foundation; with no
21 Invariant Sections, with the Front-Cover texts being ``A GNU
22 Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the
23 license is included in the section entitled ``GNU Free Documentation
24 License'' in the Emacs manual.
26 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
27 this GNU Manual, like GNU software.  Copies published by the Free
28 Software Foundation raise funds for GNU development.''
30 This document is part of a collection distributed under the GNU Free
31 Documentation License.  If you want to distribute this document
32 separately from the collection, you can do so by adding a copy of the
33 license to the document, as described in section 6 of the license.
34 @end quotation
35 @end copying
37 @dircategory Emacs
38 @direntry
39 * SES: (ses).       Simple Emacs Spreadsheet
40 @end direntry
42 @finalout
44 @titlepage
45 @title SES
46 @subtitle Simple Emacs Spreadsheet
47 @author Jonathan A. Yavner
48 @author @email{jyavner@@member.fsf.org}
50 @page
51 @vskip 0pt plus 1filll
52 @insertcopying
53 @end titlepage
55 @contents
57 @c ===================================================================
59 @ifnottex
60 @node Top, Sales Pitch, (dir), (dir)
61 @comment  node-name,  next,  previous,  up
62 @top SES: Simple Emacs Spreadsheet
64 @display
65 SES is a major mode for GNU Emacs to edit spreadsheet files, which
66 contain a rectangular grid of cells.  The cells' values are specified
67 by formulas that can refer to the values of other cells.
68 @end display
69 @end ifnottex
71 To report bugs, send email to @email{jyavner@@member.fsf.org}.
73 @menu
74 * Sales Pitch::                 Why use SES?
75 * The Basics::                  Basic spreadsheet commands
76 * Advanced Features::           Want to know more?
77 * For Gurus::                   Want to know @emph{even more}?
78 * Index::                       Concept, Function and Variable Index
79 * Acknowledgements::            Acknowledgements
80 @end menu
82 @c ===================================================================
84 @node Sales Pitch, The Basics, Top, Top
85 @comment  node-name,  next,  previous,  up
86 @chapter Sales Pitch
87 @cindex features
89 @itemize @bullet
90 @item Create and edit simple spreadsheets with a minimum of fuss.
91 @item Full undo/redo/autosave.
92 @item Immune to viruses in spreadsheet files.
93 @item Cell formulas are straight Emacs Lisp.
94 @item Printer functions for control of cell appearance.
95 @item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc.
96 @item ``Spillover'' of lengthy cell values into following blank cells.
97 @item Header line shows column letters or a selected row.
98 @item Completing-read for entering symbols as cell values.
99 @item Cut, copy, and paste can transfer formulas and printer functions.
100 @item Import and export of tab-separated values or tab-separated formulas.
101 @item Plaintext, easily-hacked file format.
102 @end itemize
104 @c ===================================================================
106 @node The Basics, Advanced Features, Sales Pitch, Top
107 @comment  node-name,  next,  previous,  up
108 @chapter The Basics
109 @cindex basic commands
110 @findex ses-jump
111 @findex ses-mark-row
112 @findex ses-mark-column
113 @findex ses-mark-whole-buffer
114 @findex set-mark-command
115 @findex keyboard-quit
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.
122 @table @kbd
123 @item j
124 Moves point to cell, specified by identifier (@code{ses-jump}).
125 @end table
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 (SES always
130 uses transient mark mode).  Drag the mouse from A1 to A3 to create the
131 range A1-A2.  Many SES commands operate only on single cells, not
132 ranges.
134 @table @kbd
135 @item C-SPC
136 @itemx C-@@
137 Set mark at point (@code{set-mark-command}).
139 @item C-g
140 Turn off the mark (@code{keyboard-quit}).
142 @item M-h
143 Highlight current row (@code{ses-mark-row}).
145 @item S-M-h
146 Highlight current column (@code{ses-mark-column}).
148 @item C-x h
149 Highlight all cells (@code{mark-whole-buffer}).
150 @end table
152 @menu
153 * Formulas::
154 * Resizing::
155 * Printer functions::
156 * Clearing cells::
157 * Copy/cut/paste::
158 * Customizing SES::
159 @end menu
161 @node Formulas, Resizing, The Basics, The Basics
162 @section Cell formulas
163 @cindex 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:
173 @table @kbd
174 @item 0..9
175 Self-insert a digit (@code{ses-read-cell}).
177 @item -
178 Self-insert a negative number (@code{ses-read-cell}).
180 @item .
181 Self-insert a fractional number (@code{ses-read-cell}).
183 @item "
184 Self-insert a quoted string.  The ending double-quote
185 is inserted for you (@code{ses-read-cell}).
187 @item (
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).  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.
198 @end table
200 To enter something else (e.g., a vector), begin with a digit, then
201 erase the digit and type whatever you want.
203 @table @kbd
204 @item RET
205 Edit the existing formula in the current cell (@code{ses-edit-cell}).
207 @item C-c C-c
208 Force recalculation of the current cell or range (@code{ses-recalculate-cell}).
210 @item C-c C-l
211 Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
212 @end table
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
226 Basic commands:
228 @table @kbd
229 @item C-o
230 (@code{ses-insert-row})
232 @item M-o
233 (@code{ses-insert-column})
235 @item C-k
236 (@code{ses-delete-row})
238 @item M-k
239 (@code{ses-delete-column})
241 @item w
242 (@code{ses-set-column-width})
244 @item TAB
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}).
249 @item C-j
250 Linefeed inserts below the current row and moves to column A
251 (@code{ses-append-row-jump-first-column}).
252 @end table
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:
263 @table @kbd
264 @item C-_
265 @itemx C-x u
266 Undo previous action (@code{(undo)}).
267 @end table
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
276 @findex ses-center
277 @findex ses-center-span
278 @findex ses-dashfill
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
295 spreadsheet is used.
297 @table @kbd
298 @item p
299 Enter a printer for current cell or range (@code{ses-read-cell-printer}).
301 @item M-p
302 Enter a printer for the current column (@code{ses-read-column-printer}).
304 @item C-c C-p
305 Enter the default printer for the spreadsheet
306 (@code{ses-read-default-printer}).
307 @end table
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:
317 @table @code
318 @item ses-center
319 Just centering.
321 @item ses-center-span
322 Centering with spill-over to following blank cells.
324 @item ses-dashfill
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.
332 @end table
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}:
343 @table @kbd
344 @item DEL
345 Clear cell and move left (@code{ses-clear-cell-backward}).
347 @item C-d
348 Clear cell and move right (@code{ses-clear-cell-forward}).
349 @end table
352 @node Copy/cut/paste, Customizing SES, Clearing cells, The Basics
353 @section Copy, cut, and paste
354 @cindex copy
355 @cindex cut
356 @cindex paste
357 @findex kill-ring-save
358 @findex mouse-set-region
359 @findex mouse-set-secondary
360 @findex ses-kill-override
361 @findex yank
362 @findex clipboard-yank
363 @findex mouse-yank-at-click
364 @findex mouse-yank-at-secondary
365 @findex ses-yank-pop
367 The copy functions work on rectangular regions of cells.  You can paste the
368 copies into non-SES buffers to export the print text.
370 @table @kbd
371 @item M-w
372 @itemx [copy]
373 @itemx [C-insert]
374 Copy the highlighted cells to kill ring and primary clipboard
375 (@code{kill-ring-save}).
377 @item [drag-mouse-1]
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}).
385 @item C-w
386 @itemx [cut]
387 @itemx [S-delete]
388 The cut functions do not actually delete rows or columns---they copy
389 and then clear (@code{ses-kill-override}).
391 @item C-y
392 @itemx [S-insert]
393 Paste from kill ring (@code{yank}).  The paste functions behave
394 differently depending on the format of the text being inserted:
395 @itemize @bullet
396 @item
397 When pasting cells that were cut from a 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}.
400 @item
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.
404 @item
405 Non-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.
409 @end itemize
411 @item [paste]
412 Paste from primary clipboard or kill ring (@code{clipboard-yank}).
414 @item [mouse-2]
415 Set point and paste from primary clipboard (@code{mouse-yank-at-click}).
417 @item [M-mouse-2]
418 Set point and paste from secondary clipboard (@code{mouse-yank-secondary}).
420 @item M-y
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 SES version uses @code{undo} to delete the old
424 yank.  This doesn't make any difference?
425 @end table
427 @node Customizing SES,  , Copy/cut/paste, The Basics
428 @section Customizing SES
429 @cindex customizing
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
443 list.
445 @code{ses-mode-hook} is a normal mode hook (list of functions to
446 execute when starting 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 analysing 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
459 safety belts!
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
470 @table @kbd
471 @item C-c M-C-h
472 (@code{ses-set-header-row}).  The header line at the top of the SES
473 window normally shows the column letter for each column.  You can set
474 it to show a copy of some row, such as a row of column titles, so that
475 row will always be visible.  Default is to set the current row as the
476 header; use C-u to prompt for header row.  Set the header to row 0 to
477 show column letters again.
478 @item [header-line mouse-3]
479 Pops up a menu to set the current row as the header, or revert to
480 column letters.
481 @end table
483 @menu
484 * The print area::
485 * Ranges in formulas::
486 * Sorting by column::
487 * Standard formula functions::
488 * More on cell printing::
489 * Import and export::
490 * Virus protection::
491 * Spreadsheets with details and summary::
492 @end menu
494 @node The print area, Ranges in formulas, Advanced Features, Advanced Features
495 @section The print area
496 @cindex print area
497 @findex widen
498 @findex ses-renarrow-buffer
499 @findex ses-reprint-all
501 A SES file consists of a print area and a data area.  Normally the
502 buffer is narrowed to show only the print area.  The print area is
503 read-only except for special SES commands; it contains cell values
504 formatted by printer functions.  The data area records the formula and
505 printer functions, etc.
507 @table @kbd
508 @item C-x n w
509 Show print and data areas (@code{widen}).
511 @item C-c C-n
512 Show only print area (@code{ses-renarrow-buffer}).
514 @item S-C-l
515 @itemx M-C-l
516 Recreate print area by reevaluating printer functions for all cells
517 (@code{ses-reprint-all}).
518 @end table
520 @node Ranges in formulas, Sorting by column, The print area, Advanced Features
521 @section Ranges in formulas
522 @cindex ranges
523 @findex ses-insert-range-click
524 @findex ses-insert-range
525 @findex ses-insert-ses-range-click
526 @findex ses-insert-ses-range
527 @vindex from
528 @vindex to
530 A formula like
531 @lisp
532 (+ A1 A2 A3)
533 @end lisp
534 is the sum of three specific cells.  If you insert a new second row,
535 the formula becomes
536 @lisp
537 (+ A1 A3 A4)
538 @end lisp
539 and the new row is not included in the sum.
541 The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of
542 the values in a rectangle of cells.  If your formula is
543 @lisp
544 (apply '+ (ses-range A1 A3))
545 @end lisp
546 and you insert a new second row, it becomes
547 @lisp
548 (apply '+ (ses-range A1 A4))
549 @end lisp
550 and the new row is included in the sum.
552 While entering or editing a formula in the minibuffer, you can select
553 a range in the spreadsheet (using mouse or keyboard), then paste a
554 representation of that range into your formula.  Suppose you select
555 A1-C1:
557 @table @kbd
558 @item [S-mouse-3]
559 Inserts "A1 B1 C1" @code{(ses-insert-range-click})
561 @item C-c C-r
562 Keyboard version (@code{ses-insert-range}).
564 @item [C-S-mouse-3]
565 Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}).
567 @item C-c C-s
568 Keyboard version (@code{ses-insert-ses-range}).
569 @end table
571 If you delete the @var{from} or @var{to} cell for a range, the nearest
572 still-existing cell is used instead.  If you delete the entire range,
573 the formula relocator will delete the ses-range from the formula.
575 If you insert a new row just beyond the end of a one-column range, or
576 a new column just beyond a one-row range, the new cell is included in
577 the range.  New cells inserted just before a range are not included.
580 @node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
581 @section Sorting by column
582 @cindex sorting
583 @findex ses-sort-column
584 @findex ses-sort-column-click
586 @table @kbd
587 @item C-c M-C-s
588 Sort the cells of a range using one of the columns
589 (@code{ses-sort-column}).  The rows (or partial rows if the range
590 doesn't include all columns) are rearranged so the chosen column will
591 be in order.
593 @item [header-line mouse-2]
594 The easiest way to sort is to click mouse-2 on the chosen column's header row
595 (@code{ses-sort-column-click}).
596 @end table
598 The sort comparison uses @code{string<}, which works well for
599 right-justified numbers and left-justified strings.
601 With prefix arg, sort is in descending order.
603 Rows are moved one at a time, with relocation of formulas.  This works
604 well if formulas refer to other cells in their row, not so well for
605 formulas that refer to other rows in the range or to cells outside the
606 range.
609 @node Standard formula functions, More on cell printing, Sorting by column, Advanced Features
610 @section Standard formula functions
611 @cindex standard formula functions
612 @cindex *skip*
613 @cindex *error*
614 @findex ses-delete-blanks
615 @findex ses-average
616 @findex ses+
618 Oftentimes you want a calculation to exclude the blank cells.  Here
619 are some useful functions to call from your formulas:
621 @table @code
622 @item (ses-delete-blanks &rest @var{args})
623 Returns a list from which all blank cells (value is either @code{nil} or
624 '*skip*) have been deleted.
626 @item (ses+ &rest @var{args})
627 Sum of non-blank arguments.
629 @item (ses-average @var{list})
630 Average of non-blank elements in @var{list}.  Here the list is passed
631 as a single argument, since you'll probably use it with @code{ses-range}.
632 @end table
634 @node More on cell printing, Import and export, Standard formula functions, Advanced Features
635 @section More on cell printing
636 @cindex cell printing, more
637 @findex ses-truncate-cell
638 @findex ses-recalculate-cell
640 Special cell values:
641 @itemize
642 @item nil prints the same as "", but allows previous cell to spill over.
643 @item '*skip* replaces nil when the previous cell actually does spill over;
644 nothing is printed for it.
645 @item '*error* indicates that the formula signaled an error instead of
646 producing a value: the print cell is filled with hash marks (#).
647 @end itemize
649 If the result from the printer function is too wide for the cell and
650 the following cell is @code{nil}, the result will spill over into the
651 following cell.  Very wide results can spill over several cells.  If
652 the result is too wide for the available space (up to the end of the
653 row or the next non-@code{nil} cell), the result is truncated if the cell's
654 value is a string, or replaced with hash marks otherwise.
656 SES could get confused by printer results that contain newlines or
657 tabs, so these are replaced with question marks.
659 @table @kbd
660 @item C-c C-t
661 Confine a cell to its own column (@code{ses-truncate-cell}).  This
662 allows you to move point to a rightward cell that would otherwise be
663 covered by a spill-over.  If you don't change the rightward cell, the
664 confined cell will spill over again the next time it is reprinted.
666 @item C-c C-c
667 When applied to a single cell, this command displays in the echo area any
668 formula error or printer error that occurred during
669 recalculation/reprinting (@code{ses-recalculate-cell}).
670 @end table
672 When a printer function signals an error, the default printer
673 @samp{"%s"} is substituted.  This is useful when your column printer
674 is numeric-only and you use a string as a cell value.
677 @node Import and export, Virus protection, More on cell printing, Advanced Features
678 @section Import and export
679 @cindex import and export
680 @cindex export, and import
681 @findex ses-export-tsv
682 @findex ses-export-tsf
684 @table @kbd
685 @item x t
686 Export a range of cells as tab-separated values (@code{ses-export-tsv}).
687 @item x T
688 Export a range of cells as tab-separated formulas (@code{ses-export-tsf}).
689 @end table
691 The exported text goes to the kill ring --- you can paste it into
692 another buffer.  Columns are separated by tabs, rows by newlines.
694 To import text, use any of the yank commands where the text to paste
695 contains tabs and/or newlines.  Imported formulas are not relocated.
697 @node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features
698 @section Virus protection
699 @cindex virus protection
701 Whenever a formula or printer is read from a file or is pasted into
702 the spreadsheet, it receives a ``needs safety check'' marking.  Later,
703 when the formula or printer is evaluated for the first time, it is
704 checked for safety using the @code{unsafep} predicate; if found to be
705 ``possibly unsafe'', the questionable formula or printer is displayed
706 and you must press Y to approve it or N to use a substitute.  The
707 substitute always signals an error.
709 Formulas or printers that you type in are checked immediately for
710 safety.  If found to be possibly unsafe and you press N to disapprove,
711 the action is canceled and the old formula or printer will remain.
713 Besides viruses (which try to copy themselves to other files),
714 @code{unsafep} can also detect all other kinds of Trojan horses, such as
715 spreadsheets that delete files, send email, flood Web sites, alter
716 your Emacs settings, etc.
718 Generally, spreadsheet formulas and printers are simple things that
719 don't need to do any fancy computing, so all potentially-dangerous
720 parts of the Emacs Lisp environment can be excluded without cramping
721 your style as a formula-writer.  See the documentation in @file{unsafep.el}
722 for more info on how Lisp forms are classified as safe or unsafe.
724 @node Spreadsheets with details and summary,  , Virus protection, Advanced Features
725 @section Spreadsheets with details and summary
726 @cindex details and summary
727 @cindex summary, and details
729 A common organization for spreadsheets is to have a bunch of ``detail''
730 rows, each perhaps describing a transaction, and then a set of
731 ``summary'' rows that each show reduced data for some subset of the
732 details.  SES supports this organization via the @code{ses-select}
733 function.
735 @table @code
736 @item (ses-select @var{fromrange} @var{test} @var{torange})
737 Returns a subset of @var{torange}.  For each member in @var{fromrange}
738 that is equal to @var{test}, the corresponding member of @var{torange}
739 is included in the result.
740 @end table
742 Example of use:
743 @lisp
744 (ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5)))
745 @end lisp
746 This computes the average of the B column values for those rows whose
747 A column value is the symbol 'Smith.
749 Arguably one could specify only @var{fromrange} plus
750 @var{to-row-offset} and @var{to-column-offset}.  The @var{torange} is
751 stated explicitly to ensure that the formula will be recalculated if
752 any cell in either range is changed.
754 File @file{etc/ses-example.el} in the Emacs distribution is an example of a
755 details-and-summary spreadsheet.
758 @c ===================================================================
760 @node For Gurus, Index, Advanced Features, Top
761 @chapter For Gurus
762 @cindex advanced features
764 @menu
765 * Deferred updates::
766 * Nonrelocatable references::
767 * The data area::
768 * Buffer-local variables in spreadsheets::
769 * Uses of defadvice in SES::
770 @end menu
772 @node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
773 @section Deferred updates
774 @cindex deferred updates
775 @cindex updates, deferred
776 @vindex run-with-idle-timer
778 To save time by avoiding redundant computations, cells that need
779 recalculation due to changes in other cells are added to a set.  At
780 the end of the command, each cell in the set is recalculated once.
781 This can create a new set of cells that need recalculation.  The
782 process is repeated until either the set is empty or it stops changing
783 (due to circular references among the cells).  In extreme cases, you
784 might see progress messages of the form ``Recalculating... (@var{nnn}
785 cells left)''.  If you interrupt the calculation using @kbd{C-g}, the
786 spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or
787 @kbd{C-c C-l} to fix it.
789 To save even more time by avoiding redundant writes, cells that have
790 changes are added to a set instead of being written immediately to the
791 data area.  Each cell in the set is written once, at the end of the
792 command.  If you change vast quantities of cells, you might see a
793 progress message of the form ``Writing... (@var{nnn} cells left)''.
794 These deferred cell-writes cannot be interrupted by @kbd{C-g}, so
795 you'll just have to wait.
797 SES uses @code{run-with-idle-timer} to move the cell underline when
798 Emacs will be scrolling the buffer after the end of a command, and
799 also to narrow and underline after @kbd{C-x C-v}.  This is visible as
800 a momentary glitch after C-x C-v and certain scrolling commands.  You
801 can type ahead without worrying about the glitch.
804 @node Nonrelocatable references, The data area, Deferred updates, For Gurus
805 @section Nonrelocatable references
806 @cindex nonrelocatable references
807 @cindex references, nonrelocatable
809 @kbd{C-y} relocates all cell-references in a pasted formula, while
810 @kbd{C-u C-y} relocates none of the cell-references.  What about mixed
811 cases?
813 You can use
814 @lisp
815 (symbol-value 'B3)
816 @end lisp
817 to make an @dfn{absolute reference}.  The formula relocator skips over
818 quoted things, so this will not be relocated when pasted or when
819 rows/columns are inserted/deleted.  However, B3 will not be recorded
820 as a dependency of this cell, so this cell will not be updated
821 automatically when B3 is changed.
823 The variables @code{row} and @code{col} are dynamically bound while a
824 cell formula is being evaluated.  You can use
825 @lisp
826 (ses-cell-value row 0)
827 @end lisp
828 to get the value from the leftmost column in the current row.  This
829 kind of dependency is also not recorded.
832 @node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus
833 @section The data area
834 @cindex data area
835 @findex ses-reconstruct-all
837 Begins with an 014 character, followed by sets of cell-definition
838 macros for each row, followed by column-widths, column-printers,
839 default-printer, and header-row.  Then there's the global parameters
840 (file-format ID, numrows, numcols) and the local variables (specifying
841 SES mode for the buffer, etc.)
843 When a SES file is loaded, first the numrows and numcols values are
844 loaded, then the entire data area is @code{eval}ed, and finally the local
845 variables are processed.
847 You can edit the data area, but don't insert or delete any newlines
848 except in the local-variables part, since SES locates things by
849 counting newlines.  Use @kbd{C-x C-e} at the end of a line to install
850 your edits into the spreadsheet data structures (this does not update
851 the print area, use e.g. @kbd{C-c C-l} for that).
853 The data area is maintained as an image of spreadsheet data
854 structures that area stored in buffer-local variables.  If the data
855 area gets messed up, you can try reconstructing the data area from the
856 data structures:
858 @table @kbd
859 @item C-c M-C-l
860 (@code{ses-reconstruct-all}).
861 @end table
864 @node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus
865 @section Buffer-local variables in spreadsheets
866 @cindex buffer-local variables
867 @cindex variables, buffer-local
869 You can add additional local variables to the list at the bottom of
870 the data area, such as hidden constants you want to refer to in your
871 formulas.
873 You can override the variable @code{symbolic-formulas} to be a list of
874 symbols (as parenthesized strings) to show as completions for the '
875 command.  This initial completions list is used instead of the actual
876 set of symbols-as-formulas in the spreadsheet.
878 For examples of these, see file @file{etc/ses-example.ses}.
880 If (for some reason) you want your formulas or printers to save data
881 into variables, you must declare these variables as buffer-locals in
882 order to avoid a virus warning.
884 You can define functions by making them values for the fake local
885 variable @code{eval}.  Such functions can then be used in your
886 formulas and printers, but usually each @code{eval} is presented to
887 the user during file loading as a potential virus --- this can get
888 annoying.
890 You can define functions in your @file{.emacs} file.  Other people can
891 still read the print area of your spreadsheet, but they won't be able
892 to recalculate or reprint anything that depends on your functions.  To
893 avoid virus warnings, each function used in a formula needs
894 @lisp
895 (put 'your-function-name 'safe-function t)
896 @end lisp
898 @node Uses of defadvice in SES,  , Buffer-local variables in spreadsheets, For Gurus
899 @section Uses of defadvice in SES
900 @cindex defadvice
901 @cindex undo-more
902 @cindex copy-region-as-kill
903 @cindex yank
905 @table @code
906 @item undo-more
907 Defines a new undo element format (@var{fun} . @var{args}), which
908 means ``undo by applying @var{fun} to @var{args}''.  For spreadsheet
909 buffers, it allows undos in the data area even though that's outside
910 the narrowing.
912 @item copy-region-as-kill
913 When copying from the print area of a spreadsheet, treat the region as
914 a rectangle and attach each cell's formula and printer as 'ses
915 properties.
917 @item yank
918 When yanking into the print area of a spreadsheet, first try to yank
919 as cells (if the yank text has 'ses properties), then as tab-separated
920 formulas, then (if all else fails) as a single formula for the current
921 cell.
922 @end table
924 @c ===================================================================
925 @node Index, Acknowledgements, For Gurus, Top
926 @unnumbered Index
928 @printindex cp
930 @c ===================================================================
932 @node Acknowledgements, , Index, Top
933 @chapter Acknowledgements
935 Coding by:
936 @quotation
937 Jonathan Yavner @email{jyavner@@member.fsf.org}@*
938 Stefan Monnier @email{monnier@@gnu.org}
939 @end quotation
941 @noindent
942 Texinfo manual by:
943 @quotation
944 Jonathan Yavner @email{jyavner@@member.fsf.org}@*
945 Brad Collins <brad@@chenla.org>
946 @end quotation
948 @noindent
949 Ideas from:
950 @quotation
951 Christoph Conrad @email{christoph.conrad@@gmx.de}@*
952 CyberBob @email{cyberbob@@redneck.gacracker.org}@*
953 Syver Enstad @email{syver-en@@online.no}@*
954 Ami Fischman @email{fischman@@zion.bpnetworks.com}@*
955 Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@*
956 Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@*
957 Yusong Li @email{lyusong@@hotmail.com}@*
958 Juri Linkov @email{juri@@jurta.org}@*
959 Harald Maier @email{maierh@@myself.com}@*
960 Alan Nash @email{anash@@san.rr.com}@*
961 François Pinard @email{pinard@@iro.umontreal.ca}@*
962 Pedro Pinto @email{ppinto@@cs.cmu.edu}@*
963 Stefan Reichör @email{xsteve@@riic.at}@*
964 Oliver Scholz @email{epameinondas@@gmx.de}@*
965 Richard M. Stallman @email{rms@@gnu.org}@*
966 Luc Teirlinck @email{teirllm@@dms.auburn.edu}@*
967 J. Otto Tennant @email{jotto@@pobox.com}@*
968 Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr}
969 @end quotation
971 @c ===================================================================
973 @bye
975 @ignore
976    arch-tag: 10a4ee1c-7ef4-4c06-8b7a-f975e39f0dec
977 @end ignore