Commit | Line | Data |
---|---|---|
7ed9159a JY |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename ../info/ses | |
4 | @settitle SES: Simple Emacs Spreadsheet | |
5 | @setchapternewpage off | |
35eb0fa1 LT |
6 | @syncodeindex fn cp |
7 | @syncodeindex vr cp | |
8 | @syncodeindex ky cp | |
7ed9159a JY |
9 | @c %**end of header |
10 | ||
18f952d5 | 11 | @copying |
7ed9159a JY |
12 | This file documents SES: the Simple Emacs Spreadsheet. |
13 | ||
3f548a7c | 14 | Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008 |
4e6835db | 15 | Free Software Foundation, Inc. |
7ed9159a | 16 | |
18f952d5 | 17 | @quotation |
7ed9159a | 18 | Permission is granted to copy, distribute and/or modify this document |
678e7c71 | 19 | under the terms of the GNU Free Documentation License, Version 1.2 or |
7ed9159a JY |
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. | |
25 | ||
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.'' | |
29 | ||
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. | |
18f952d5 KB |
34 | @end quotation |
35 | @end copying | |
36 | ||
37 | @dircategory Emacs | |
38 | @direntry | |
39 | * SES: (ses). Simple Emacs Spreadsheet | |
40 | @end direntry | |
7ed9159a JY |
41 | |
42 | @finalout | |
43 | ||
44 | @titlepage | |
45 | @title SES | |
46 | @subtitle Simple Emacs Spreadsheet | |
47 | @author Jonathan A. Yavner | |
bc0d9d58 | 48 | @author @email{jyavner@@member.fsf.org} |
7ed9159a | 49 | |
7ed9159a JY |
50 | @page |
51 | @vskip 0pt plus 1filll | |
18f952d5 | 52 | @insertcopying |
7ed9159a JY |
53 | @end titlepage |
54 | ||
55 | @contents | |
56 | ||
57 | @c =================================================================== | |
58 | ||
59 | @ifnottex | |
4efff8f7 | 60 | @node Top, Sales Pitch, (dir), (dir) |
7ed9159a JY |
61 | @comment node-name, next, previous, up |
62 | @top SES: Simple Emacs Spreadsheet | |
63 | ||
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 | |
70 | ||
df961c06 | 71 | To report bugs, send email to @email{jyavner@@member.fsf.org}. |
7ed9159a JY |
72 | |
73 | @menu | |
4efff8f7 RC |
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}? | |
ef80b743 | 78 | * Index:: Concept, Function and Variable Index |
4efff8f7 | 79 | * Acknowledgements:: Acknowledgements |
84247bb5 | 80 | * GNU Free Documentation License:: The license for this documentation. |
7ed9159a JY |
81 | @end menu |
82 | ||
83 | @c =================================================================== | |
84 | ||
85 | @node Sales Pitch, The Basics, Top, Top | |
86 | @comment node-name, next, previous, up | |
87 | @chapter Sales Pitch | |
ef80b743 | 88 | @cindex features |
7ed9159a JY |
89 | |
90 | @itemize @bullet | |
91 | @item Create and edit simple spreadsheets with a minimum of fuss. | |
92 | @item Full undo/redo/autosave. | |
93 | @item Immune to viruses in spreadsheet files. | |
94 | @item Cell formulas are straight Emacs Lisp. | |
95 | @item Printer functions for control of cell appearance. | |
96 | @item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc. | |
97 | @item ``Spillover'' of lengthy cell values into following blank cells. | |
98 | @item Header line shows column letters or a selected row. | |
99 | @item Completing-read for entering symbols as cell values. | |
100 | @item Cut, copy, and paste can transfer formulas and printer functions. | |
101 | @item Import and export of tab-separated values or tab-separated formulas. | |
102 | @item Plaintext, easily-hacked file format. | |
103 | @end itemize | |
104 | ||
105 | @c =================================================================== | |
106 | ||
107 | @node The Basics, Advanced Features, Sales Pitch, Top | |
108 | @comment node-name, next, previous, up | |
109 | @chapter The Basics | |
ef80b743 JY |
110 | @cindex basic commands |
111 | @findex ses-jump | |
112 | @findex ses-mark-row | |
113 | @findex ses-mark-column | |
114 | @findex ses-mark-whole-buffer | |
115 | @findex set-mark-command | |
116 | @findex keyboard-quit | |
7ed9159a JY |
117 | |
118 | A @dfn{cell identifier} is a symbol with a column letter and a row | |
119 | number. Cell B7 is the 2nd column of the 7th row. For very wide | |
120 | spreadsheets, there are two column letters: cell AB7 is the 28th | |
121 | column of the 7th row. | |
122 | ||
123 | @table @kbd | |
124 | @item j | |
125 | Moves point to cell, specified by identifier (@code{ses-jump}). | |
126 | @end table | |
127 | ||
128 | Point is always at the left edge of a cell, or at the empty endline. | |
129 | When mark is inactive, the current cell is underlined. When mark is | |
130 | active, the range is the highlighted rectangle of cells (SES always | |
131 | uses transient mark mode). Drag the mouse from A1 to A3 to create the | |
132 | range A1-A2. Many SES commands operate only on single cells, not | |
133 | ranges. | |
134 | ||
135 | @table @kbd | |
136 | @item C-SPC | |
137 | @itemx C-@@ | |
138 | Set mark at point (@code{set-mark-command}). | |
139 | ||
140 | @item C-g | |
141 | Turn off the mark (@code{keyboard-quit}). | |
142 | ||
143 | @item M-h | |
144 | Highlight current row (@code{ses-mark-row}). | |
145 | ||
146 | @item S-M-h | |
147 | Highlight current column (@code{ses-mark-column}). | |
148 | ||
149 | @item C-x h | |
150 | Highlight all cells (@code{mark-whole-buffer}). | |
151 | @end table | |
152 | ||
153 | @menu | |
154 | * Formulas:: | |
155 | * Resizing:: | |
156 | * Printer functions:: | |
157 | * Clearing cells:: | |
158 | * Copy/cut/paste:: | |
159 | * Customizing SES:: | |
160 | @end menu | |
161 | ||
162 | @node Formulas, Resizing, The Basics, The Basics | |
163 | @section Cell formulas | |
ef80b743 JY |
164 | @cindex formulas |
165 | @cindex formulas, entering | |
166 | @findex ses-read-cell | |
167 | @findex ses-read-symbol | |
168 | @findex ses-edit-cell | |
169 | @findex ses-recalculate-cell | |
170 | @findex ses-recalculate-all | |
7ed9159a JY |
171 | |
172 | To enter a number into the current cell, just start typing: | |
173 | ||
174 | @table @kbd | |
175 | @item 0..9 | |
176 | Self-insert a digit (@code{ses-read-cell}). | |
177 | ||
178 | @item - | |
179 | Self-insert a negative number (@code{ses-read-cell}). | |
180 | ||
181 | @item . | |
182 | Self-insert a fractional number (@code{ses-read-cell}). | |
183 | ||
184 | @item " | |
185 | Self-insert a quoted string. The ending double-quote | |
186 | is inserted for you (@code{ses-read-cell}). | |
187 | ||
188 | @item ( | |
189 | Self-insert an expression. The right-parenthesis is inserted for you | |
190 | (@code{ses-read-cell}). To access another cell's value, just use its | |
191 | identifier in your expression. Whenever the other cell is changed, | |
192 | this cell's formula will be reevaluated. While typing in the | |
ee6c21a7 | 193 | expression, you can use @kbd{M-@key{TAB}} to complete symbol names. |
7ed9159a JY |
194 | |
195 | @item ' @r{(apostrophe)} | |
196 | Enter a symbol (ses-read-symbol). SES remembers all symbols that have | |
197 | been used as formulas, so you can type just the beginning of a symbol | |
ee6c21a7 | 198 | and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it. |
7ed9159a JY |
199 | @end table |
200 | ||
201 | To enter something else (e.g., a vector), begin with a digit, then | |
202 | erase the digit and type whatever you want. | |
203 | ||
204 | @table @kbd | |
205 | @item RET | |
206 | Edit the existing formula in the current cell (@code{ses-edit-cell}). | |
207 | ||
208 | @item C-c C-c | |
209 | Force recalculation of the current cell or range (@code{ses-recalculate-cell}). | |
210 | ||
211 | @item C-c C-l | |
212 | Recalculate the entire spreadsheet (@code{ses-recalculate-all}). | |
213 | @end table | |
214 | ||
215 | @node Resizing, Printer functions, Formulas, The Basics | |
216 | @section Resizing the spreadsheet | |
ef80b743 JY |
217 | @cindex resizing spreadsheets |
218 | @findex ses-insert-row | |
219 | @findex ses-insert-column | |
220 | @findex ses-delete-row | |
221 | @findex ses-delete-column | |
222 | @findex ses-set-column-width | |
223 | @findex ses-forward-or-insert | |
224 | @findex ses-append-row-jump-first-column | |
225 | ||
7ed9159a JY |
226 | |
227 | Basic commands: | |
228 | ||
229 | @table @kbd | |
230 | @item C-o | |
231 | (@code{ses-insert-row}) | |
232 | ||
233 | @item M-o | |
234 | (@code{ses-insert-column}) | |
235 | ||
236 | @item C-k | |
237 | (@code{ses-delete-row}) | |
238 | ||
239 | @item M-k | |
240 | (@code{ses-delete-column}) | |
241 | ||
242 | @item w | |
243 | (@code{ses-set-column-width}) | |
244 | ||
245 | @item TAB | |
246 | Moves point to the next rightward cell, or inserts a new column if | |
247 | already at last cell on line, or inserts a new row if at endline | |
248 | (@code{ses-forward-or-insert}). | |
249 | ||
250 | @item C-j | |
251 | Linefeed inserts below the current row and moves to column A | |
252 | (@code{ses-append-row-jump-first-column}). | |
253 | @end table | |
254 | ||
255 | Resizing the spreadsheet (unless you're just changing a column width) | |
256 | relocates all the cell-references in formulas so they still refer to | |
257 | the same cells. If a formula mentioned B1 and you insert a new first | |
258 | row, the formula will now mention B2. | |
259 | ||
260 | If you delete a cell that a formula refers to, the cell-symbol is | |
261 | deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third | |
262 | column becomes @code{(+ A1 B1)}. In case this is not what you wanted: | |
263 | ||
264 | @table @kbd | |
265 | @item C-_ | |
266 | @itemx C-x u | |
267 | Undo previous action (@code{(undo)}). | |
268 | @end table | |
269 | ||
270 | ||
271 | @node Printer functions, Clearing cells, Resizing, The Basics | |
272 | @section Printer functions | |
ef80b743 JY |
273 | @cindex printer functions |
274 | @findex ses-read-cell-printer | |
275 | @findex ses-read-column-printer | |
276 | @findex ses-read-default-printer | |
277 | @findex ses-center | |
278 | @findex ses-center-span | |
279 | @findex ses-dashfill | |
280 | @findex ses-dashfill-span | |
281 | @findex ses-tildefill-span | |
282 | ||
7ed9159a JY |
283 | |
284 | Printer functions convert binary cell values into the print forms that | |
285 | Emacs will display on the screen. | |
286 | ||
287 | A printer can be a format string, like @samp{"$%.2f"}. The result | |
288 | string is right-aligned within the print cell. To get left-alignment, | |
289 | use parentheses: @samp{("$%.2f")}. A printer can also be a | |
290 | one-argument function (a symbol or a lambda), whose result is a string | |
291 | (right-aligned) or list of one string (left-aligned). While typing in | |
ee6c21a7 | 292 | a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols. |
7ed9159a | 293 | |
bf301e70 JH |
294 | Each cell has a printer. If @code{nil}, the column-printer for the cell's |
295 | column is used. If that is also @code{nil}, the default-printer for the | |
7ed9159a JY |
296 | spreadsheet is used. |
297 | ||
298 | @table @kbd | |
299 | @item p | |
300 | Enter a printer for current cell or range (@code{ses-read-cell-printer}). | |
301 | ||
302 | @item M-p | |
303 | Enter a printer for the current column (@code{ses-read-column-printer}). | |
304 | ||
305 | @item C-c C-p | |
306 | Enter the default printer for the spreadsheet | |
307 | (@code{ses-read-default-printer}). | |
308 | @end table | |
309 | ||
310 | The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer | |
311 | history, which is preloaded with the set of all printers used in this | |
312 | spreadsheet, plus the standard printers. | |
313 | ||
314 | The standard printers are suitable only for cells, not columns or | |
315 | default, because they format the value using the column-printer (or | |
bf301e70 | 316 | default-printer if @code{nil}) and then center the result: |
7ed9159a JY |
317 | |
318 | @table @code | |
319 | @item ses-center | |
320 | Just centering. | |
321 | ||
322 | @item ses-center-span | |
323 | Centering with spill-over to following blank cells. | |
324 | ||
325 | @item ses-dashfill | |
326 | Centering using dashes (-) instead of spaces. | |
327 | ||
328 | @item ses-dashfill-span | |
329 | Centering with dashes and spill-over. | |
330 | ||
331 | @item ses-tildefill-span | |
332 | Centering with tildes (~) and spill-over. | |
333 | @end table | |
334 | ||
335 | ||
336 | @node Clearing cells, Copy/cut/paste, Printer functions, The Basics | |
337 | @section Clearing cells | |
ef80b743 JY |
338 | @cindex clearing commands |
339 | @findex ses-clear-cell-backward | |
340 | @findex ses-clear-cell-forward | |
7ed9159a | 341 | |
bf301e70 | 342 | These commands set both formula and printer to @code{nil}: |
7ed9159a JY |
343 | |
344 | @table @kbd | |
345 | @item DEL | |
346 | Clear cell and move left (@code{ses-clear-cell-backward}). | |
347 | ||
348 | @item C-d | |
349 | Clear cell and move right (@code{ses-clear-cell-forward}). | |
350 | @end table | |
351 | ||
352 | ||
353 | @node Copy/cut/paste, Customizing SES, Clearing cells, The Basics | |
354 | @section Copy, cut, and paste | |
ef80b743 JY |
355 | @cindex copy |
356 | @cindex cut | |
357 | @cindex paste | |
358 | @findex kill-ring-save | |
359 | @findex mouse-set-region | |
360 | @findex mouse-set-secondary | |
361 | @findex ses-kill-override | |
362 | @findex yank | |
363 | @findex clipboard-yank | |
364 | @findex mouse-yank-at-click | |
365 | @findex mouse-yank-at-secondary | |
366 | @findex ses-yank-pop | |
7ed9159a JY |
367 | |
368 | The copy functions work on rectangular regions of cells. You can paste the | |
369 | copies into non-SES buffers to export the print text. | |
370 | ||
371 | @table @kbd | |
372 | @item M-w | |
373 | @itemx [copy] | |
374 | @itemx [C-insert] | |
375 | Copy the highlighted cells to kill ring and primary clipboard | |
376 | (@code{kill-ring-save}). | |
377 | ||
378 | @item [drag-mouse-1] | |
379 | Mark a region and copy it to kill ring and primary clipboard | |
380 | (@code{mouse-set-region}). | |
381 | ||
382 | @item [M-drag-mouse-1] | |
383 | Mark a region and copy it to kill ring and secondary clipboard | |
384 | (@code{mouse-set-secondary}). | |
385 | ||
386 | @item C-w | |
387 | @itemx [cut] | |
388 | @itemx [S-delete] | |
bf301e70 | 389 | The cut functions do not actually delete rows or columns---they copy |
7ed9159a JY |
390 | and then clear (@code{ses-kill-override}). |
391 | ||
392 | @item C-y | |
393 | @itemx [S-insert] | |
394 | Paste from kill ring (@code{yank}). The paste functions behave | |
395 | differently depending on the format of the text being inserted: | |
396 | @itemize @bullet | |
397 | @item | |
398 | When pasting cells that were cut from a SES buffer, the print text is | |
399 | ignored and only the attached formula and printer are inserted; cell | |
400 | references in the formula are relocated unless you use @kbd{C-u}. | |
401 | @item | |
402 | The pasted text overwrites a rectangle of cells whose top left corner | |
403 | is the current cell. If part of the rectangle is beyond the edges of | |
404 | the spreadsheet, you must confirm the increase in spreadsheet size. | |
405 | @item | |
406 | Non-SES text is usually inserted as a replacement formula for the | |
407 | current cell. If the formula would be a symbol, it's treated as a | |
408 | string unless you use @kbd{C-u}. Pasted formulas with syntax errors | |
409 | are always treated as strings. | |
410 | @end itemize | |
411 | ||
412 | @item [paste] | |
413 | Paste from primary clipboard or kill ring (@code{clipboard-yank}). | |
414 | ||
415 | @item [mouse-2] | |
416 | Set point and paste from primary clipboard (@code{mouse-yank-at-click}). | |
417 | ||
418 | @item [M-mouse-2] | |
419 | Set point and paste from secondary clipboard (@code{mouse-yank-secondary}). | |
420 | ||
421 | @item M-y | |
422 | Immediately after a paste, you can replace the text with a preceding | |
423 | element from the kill ring (@code{ses-yank-pop}). Unlike the standard | |
424 | Emacs yank-pop, the SES version uses @code{undo} to delete the old | |
425 | yank. This doesn't make any difference? | |
426 | @end table | |
427 | ||
428 | @node Customizing SES, , Copy/cut/paste, The Basics | |
429 | @section Customizing SES | |
ef80b743 JY |
430 | @cindex customizing |
431 | @vindex enable-local-eval | |
432 | @vindex ses-mode-hook | |
433 | @vindex safe-functions | |
434 | @vindex enable-local-eval | |
435 | ||
7ed9159a JY |
436 | |
437 | By default, a newly-created spreadsheet has 1 row and 1 column. The | |
438 | column width is 7 and the default printer is @samp{"%.7g"}. Each of these | |
439 | can be customized. Look in group ``ses''. | |
440 | ||
441 | After entering a cell value, point normally moves right to the next | |
442 | cell. You can customize @code{ses-after-entry-functions} to move left or | |
443 | up or down. For diagonal movement, select two functions from the | |
444 | list. | |
445 | ||
446 | @code{ses-mode-hook} is a normal mode hook (list of functions to | |
447 | execute when starting SES mode for a buffer). | |
448 | ||
409e7710 | 449 | The variable @code{safe-functions} is a list of possibly-unsafe |
7ed9159a JY |
450 | functions to be treated as safe when analysing formulas and printers. |
451 | @xref{Virus protection}. Before customizing @code{safe-functions}, | |
452 | think about how much you trust the person who's suggesting this | |
409e7710 | 453 | change. The value @code{t} turns off all anti-virus protection. A |
7ed9159a JY |
454 | list-of-functions value might enable a ``gee whiz'' spreadsheet, but it |
455 | also creates trapdoors in your anti-virus armor. In order for virus | |
456 | protection to work, you must always press @kbd{n} when presented with | |
457 | a virus warning, unless you understand what the questionable code is | |
458 | trying to do. Do not listen to those who tell you to customize | |
459 | @code{enable-local-eval}---this variable is for people who don't wear | |
460 | safety belts! | |
461 | ||
462 | ||
463 | @c =================================================================== | |
464 | ||
465 | @node Advanced Features, For Gurus, The Basics, Top | |
466 | @chapter Advanced Features | |
ef80b743 JY |
467 | @cindex advanced features |
468 | @findex ses-read-header-row | |
469 | ||
7ed9159a JY |
470 | |
471 | @table @kbd | |
472 | @item C-c M-C-h | |
c6e8a807 | 473 | (@code{ses-set-header-row}). The header line at the top of the SES |
7ed9159a JY |
474 | window normally shows the column letter for each column. You can set |
475 | it to show a copy of some row, such as a row of column titles, so that | |
c6e8a807 JY |
476 | row will always be visible. Default is to set the current row as the |
477 | header; use C-u to prompt for header row. Set the header to row 0 to | |
478 | show column letters again. | |
479 | @item [header-line mouse-3] | |
480 | Pops up a menu to set the current row as the header, or revert to | |
481 | column letters. | |
7ed9159a JY |
482 | @end table |
483 | ||
484 | @menu | |
485 | * The print area:: | |
486 | * Ranges in formulas:: | |
487 | * Sorting by column:: | |
488 | * Standard formula functions:: | |
489 | * More on cell printing:: | |
490 | * Import and export:: | |
491 | * Virus protection:: | |
492 | * Spreadsheets with details and summary:: | |
493 | @end menu | |
494 | ||
495 | @node The print area, Ranges in formulas, Advanced Features, Advanced Features | |
496 | @section The print area | |
ef80b743 JY |
497 | @cindex print area |
498 | @findex widen | |
499 | @findex ses-renarrow-buffer | |
500 | @findex ses-reprint-all | |
7ed9159a JY |
501 | |
502 | A SES file consists of a print area and a data area. Normally the | |
503 | buffer is narrowed to show only the print area. The print area is | |
504 | read-only except for special SES commands; it contains cell values | |
505 | formatted by printer functions. The data area records the formula and | |
506 | printer functions, etc. | |
507 | ||
508 | @table @kbd | |
509 | @item C-x n w | |
510 | Show print and data areas (@code{widen}). | |
511 | ||
4efff8f7 | 512 | @item C-c C-n |
7ed9159a JY |
513 | Show only print area (@code{ses-renarrow-buffer}). |
514 | ||
515 | @item S-C-l | |
516 | @itemx M-C-l | |
517 | Recreate print area by reevaluating printer functions for all cells | |
518 | (@code{ses-reprint-all}). | |
519 | @end table | |
520 | ||
521 | @node Ranges in formulas, Sorting by column, The print area, Advanced Features | |
522 | @section Ranges in formulas | |
ef80b743 JY |
523 | @cindex ranges |
524 | @findex ses-insert-range-click | |
525 | @findex ses-insert-range | |
526 | @findex ses-insert-ses-range-click | |
527 | @findex ses-insert-ses-range | |
528 | @vindex from | |
529 | @vindex to | |
7ed9159a JY |
530 | |
531 | A formula like | |
532 | @lisp | |
533 | (+ A1 A2 A3) | |
534 | @end lisp | |
535 | is the sum of three specific cells. If you insert a new second row, | |
536 | the formula becomes | |
537 | @lisp | |
538 | (+ A1 A3 A4) | |
539 | @end lisp | |
540 | and the new row is not included in the sum. | |
541 | ||
35eb0fa1 | 542 | The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of |
7ed9159a JY |
543 | the values in a rectangle of cells. If your formula is |
544 | @lisp | |
545 | (apply '+ (ses-range A1 A3)) | |
546 | @end lisp | |
547 | and you insert a new second row, it becomes | |
548 | @lisp | |
549 | (apply '+ (ses-range A1 A4)) | |
550 | @end lisp | |
551 | and the new row is included in the sum. | |
552 | ||
553 | While entering or editing a formula in the minibuffer, you can select | |
554 | a range in the spreadsheet (using mouse or keyboard), then paste a | |
555 | representation of that range into your formula. Suppose you select | |
556 | A1-C1: | |
557 | ||
558 | @table @kbd | |
559 | @item [S-mouse-3] | |
560 | Inserts "A1 B1 C1" @code{(ses-insert-range-click}) | |
561 | ||
562 | @item C-c C-r | |
563 | Keyboard version (@code{ses-insert-range}). | |
564 | ||
565 | @item [C-S-mouse-3] | |
566 | Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}). | |
567 | ||
568 | @item C-c C-s | |
569 | Keyboard version (@code{ses-insert-ses-range}). | |
570 | @end table | |
571 | ||
572 | If you delete the @var{from} or @var{to} cell for a range, the nearest | |
573 | still-existing cell is used instead. If you delete the entire range, | |
574 | the formula relocator will delete the ses-range from the formula. | |
575 | ||
576 | If you insert a new row just beyond the end of a one-column range, or | |
577 | a new column just beyond a one-row range, the new cell is included in | |
578 | the range. New cells inserted just before a range are not included. | |
579 | ||
580 | ||
581 | @node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features | |
582 | @section Sorting by column | |
ef80b743 JY |
583 | @cindex sorting |
584 | @findex ses-sort-column | |
585 | @findex ses-sort-column-click | |
7ed9159a JY |
586 | |
587 | @table @kbd | |
588 | @item C-c M-C-s | |
589 | Sort the cells of a range using one of the columns | |
590 | (@code{ses-sort-column}). The rows (or partial rows if the range | |
591 | doesn't include all columns) are rearranged so the chosen column will | |
592 | be in order. | |
593 | ||
594 | @item [header-line mouse-2] | |
595 | The easiest way to sort is to click mouse-2 on the chosen column's header row | |
596 | (@code{ses-sort-column-click}). | |
597 | @end table | |
598 | ||
599 | The sort comparison uses @code{string<}, which works well for | |
600 | right-justified numbers and left-justified strings. | |
601 | ||
602 | With prefix arg, sort is in descending order. | |
603 | ||
604 | Rows are moved one at a time, with relocation of formulas. This works | |
605 | well if formulas refer to other cells in their row, not so well for | |
606 | formulas that refer to other rows in the range or to cells outside the | |
607 | range. | |
608 | ||
609 | ||
610 | @node Standard formula functions, More on cell printing, Sorting by column, Advanced Features | |
611 | @section Standard formula functions | |
ef80b743 JY |
612 | @cindex standard formula functions |
613 | @cindex *skip* | |
614 | @cindex *error* | |
615 | @findex ses-delete-blanks | |
616 | @findex ses-average | |
617 | @findex ses+ | |
7ed9159a JY |
618 | |
619 | Oftentimes you want a calculation to exclude the blank cells. Here | |
620 | are some useful functions to call from your formulas: | |
621 | ||
622 | @table @code | |
623 | @item (ses-delete-blanks &rest @var{args}) | |
bf301e70 | 624 | Returns a list from which all blank cells (value is either @code{nil} or |
7ed9159a JY |
625 | '*skip*) have been deleted. |
626 | ||
627 | @item (ses+ &rest @var{args}) | |
628 | Sum of non-blank arguments. | |
629 | ||
630 | @item (ses-average @var{list}) | |
631 | Average of non-blank elements in @var{list}. Here the list is passed | |
632 | as a single argument, since you'll probably use it with @code{ses-range}. | |
633 | @end table | |
634 | ||
635 | @node More on cell printing, Import and export, Standard formula functions, Advanced Features | |
636 | @section More on cell printing | |
ef80b743 JY |
637 | @cindex cell printing, more |
638 | @findex ses-truncate-cell | |
639 | @findex ses-recalculate-cell | |
7ed9159a JY |
640 | |
641 | Special cell values: | |
642 | @itemize | |
643 | @item nil prints the same as "", but allows previous cell to spill over. | |
644 | @item '*skip* replaces nil when the previous cell actually does spill over; | |
645 | nothing is printed for it. | |
2c7a8f63 | 646 | @item '*error* indicates that the formula signaled an error instead of |
7ed9159a JY |
647 | producing a value: the print cell is filled with hash marks (#). |
648 | @end itemize | |
649 | ||
650 | If the result from the printer function is too wide for the cell and | |
bf301e70 | 651 | the following cell is @code{nil}, the result will spill over into the |
7ed9159a JY |
652 | following cell. Very wide results can spill over several cells. If |
653 | the result is too wide for the available space (up to the end of the | |
bf301e70 | 654 | row or the next non-@code{nil} cell), the result is truncated if the cell's |
7ed9159a JY |
655 | value is a string, or replaced with hash marks otherwise. |
656 | ||
657 | SES could get confused by printer results that contain newlines or | |
658 | tabs, so these are replaced with question marks. | |
659 | ||
660 | @table @kbd | |
661 | @item C-c C-t | |
662 | Confine a cell to its own column (@code{ses-truncate-cell}). This | |
35eb0fa1 | 663 | allows you to move point to a rightward cell that would otherwise be |
7ed9159a JY |
664 | covered by a spill-over. If you don't change the rightward cell, the |
665 | confined cell will spill over again the next time it is reprinted. | |
666 | ||
667 | @item C-c C-c | |
668 | When applied to a single cell, this command displays in the echo area any | |
669 | formula error or printer error that occurred during | |
670 | recalculation/reprinting (@code{ses-recalculate-cell}). | |
671 | @end table | |
672 | ||
673 | When a printer function signals an error, the default printer | |
674 | @samp{"%s"} is substituted. This is useful when your column printer | |
675 | is numeric-only and you use a string as a cell value. | |
676 | ||
677 | ||
678 | @node Import and export, Virus protection, More on cell printing, Advanced Features | |
679 | @section Import and export | |
ef80b743 JY |
680 | @cindex import and export |
681 | @cindex export, and import | |
682 | @findex ses-export-tsv | |
683 | @findex ses-export-tsf | |
7ed9159a JY |
684 | |
685 | @table @kbd | |
686 | @item x t | |
687 | Export a range of cells as tab-separated values (@code{ses-export-tsv}). | |
688 | @item x T | |
689 | Export a range of cells as tab-separated formulas (@code{ses-export-tsf}). | |
690 | @end table | |
691 | ||
692 | The exported text goes to the kill ring --- you can paste it into | |
693 | another buffer. Columns are separated by tabs, rows by newlines. | |
694 | ||
695 | To import text, use any of the yank commands where the text to paste | |
696 | contains tabs and/or newlines. Imported formulas are not relocated. | |
697 | ||
698 | @node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features | |
699 | @section Virus protection | |
ef80b743 | 700 | @cindex virus protection |
7ed9159a JY |
701 | |
702 | Whenever a formula or printer is read from a file or is pasted into | |
703 | the spreadsheet, it receives a ``needs safety check'' marking. Later, | |
704 | when the formula or printer is evaluated for the first time, it is | |
705 | checked for safety using the @code{unsafep} predicate; if found to be | |
706 | ``possibly unsafe'', the questionable formula or printer is displayed | |
707 | and you must press Y to approve it or N to use a substitute. The | |
708 | substitute always signals an error. | |
709 | ||
710 | Formulas or printers that you type in are checked immediately for | |
711 | safety. If found to be possibly unsafe and you press N to disapprove, | |
35eb0fa1 | 712 | the action is canceled and the old formula or printer will remain. |
7ed9159a JY |
713 | |
714 | Besides viruses (which try to copy themselves to other files), | |
715 | @code{unsafep} can also detect all other kinds of Trojan horses, such as | |
716 | spreadsheets that delete files, send email, flood Web sites, alter | |
717 | your Emacs settings, etc. | |
718 | ||
719 | Generally, spreadsheet formulas and printers are simple things that | |
720 | don't need to do any fancy computing, so all potentially-dangerous | |
721 | parts of the Emacs Lisp environment can be excluded without cramping | |
722 | your style as a formula-writer. See the documentation in @file{unsafep.el} | |
723 | for more info on how Lisp forms are classified as safe or unsafe. | |
724 | ||
725 | @node Spreadsheets with details and summary, , Virus protection, Advanced Features | |
726 | @section Spreadsheets with details and summary | |
ef80b743 JY |
727 | @cindex details and summary |
728 | @cindex summary, and details | |
7ed9159a JY |
729 | |
730 | A common organization for spreadsheets is to have a bunch of ``detail'' | |
731 | rows, each perhaps describing a transaction, and then a set of | |
732 | ``summary'' rows that each show reduced data for some subset of the | |
733 | details. SES supports this organization via the @code{ses-select} | |
734 | function. | |
735 | ||
736 | @table @code | |
737 | @item (ses-select @var{fromrange} @var{test} @var{torange}) | |
738 | Returns a subset of @var{torange}. For each member in @var{fromrange} | |
739 | that is equal to @var{test}, the corresponding member of @var{torange} | |
740 | is included in the result. | |
741 | @end table | |
742 | ||
743 | Example of use: | |
744 | @lisp | |
745 | (ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5))) | |
746 | @end lisp | |
747 | This computes the average of the B column values for those rows whose | |
748 | A column value is the symbol 'Smith. | |
749 | ||
750 | Arguably one could specify only @var{fromrange} plus | |
751 | @var{to-row-offset} and @var{to-column-offset}. The @var{torange} is | |
752 | stated explicitly to ensure that the formula will be recalculated if | |
753 | any cell in either range is changed. | |
754 | ||
755 | File @file{etc/ses-example.el} in the Emacs distribution is an example of a | |
756 | details-and-summary spreadsheet. | |
757 | ||
758 | ||
759 | @c =================================================================== | |
760 | ||
ef80b743 | 761 | @node For Gurus, Index, Advanced Features, Top |
7ed9159a | 762 | @chapter For Gurus |
ef80b743 | 763 | @cindex advanced features |
7ed9159a JY |
764 | |
765 | @menu | |
766 | * Deferred updates:: | |
767 | * Nonrelocatable references:: | |
768 | * The data area:: | |
769 | * Buffer-local variables in spreadsheets:: | |
770 | * Uses of defadvice in SES:: | |
771 | @end menu | |
772 | ||
773 | @node Deferred updates, Nonrelocatable references, For Gurus, For Gurus | |
774 | @section Deferred updates | |
ef80b743 JY |
775 | @cindex deferred updates |
776 | @cindex updates, deferred | |
777 | @vindex run-with-idle-timer | |
7ed9159a JY |
778 | |
779 | To save time by avoiding redundant computations, cells that need | |
780 | recalculation due to changes in other cells are added to a set. At | |
781 | the end of the command, each cell in the set is recalculated once. | |
782 | This can create a new set of cells that need recalculation. The | |
783 | process is repeated until either the set is empty or it stops changing | |
784 | (due to circular references among the cells). In extreme cases, you | |
785 | might see progress messages of the form ``Recalculating... (@var{nnn} | |
786 | cells left)''. If you interrupt the calculation using @kbd{C-g}, the | |
787 | spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or | |
788 | @kbd{C-c C-l} to fix it. | |
789 | ||
790 | To save even more time by avoiding redundant writes, cells that have | |
791 | changes are added to a set instead of being written immediately to the | |
792 | data area. Each cell in the set is written once, at the end of the | |
793 | command. If you change vast quantities of cells, you might see a | |
794 | progress message of the form ``Writing... (@var{nnn} cells left)''. | |
795 | These deferred cell-writes cannot be interrupted by @kbd{C-g}, so | |
796 | you'll just have to wait. | |
797 | ||
798 | SES uses @code{run-with-idle-timer} to move the cell underline when | |
799 | Emacs will be scrolling the buffer after the end of a command, and | |
800 | also to narrow and underline after @kbd{C-x C-v}. This is visible as | |
801 | a momentary glitch after C-x C-v and certain scrolling commands. You | |
802 | can type ahead without worrying about the glitch. | |
803 | ||
804 | ||
805 | @node Nonrelocatable references, The data area, Deferred updates, For Gurus | |
806 | @section Nonrelocatable references | |
ef80b743 JY |
807 | @cindex nonrelocatable references |
808 | @cindex references, nonrelocatable | |
7ed9159a JY |
809 | |
810 | @kbd{C-y} relocates all cell-references in a pasted formula, while | |
811 | @kbd{C-u C-y} relocates none of the cell-references. What about mixed | |
812 | cases? | |
813 | ||
814 | You can use | |
815 | @lisp | |
816 | (symbol-value 'B3) | |
817 | @end lisp | |
818 | to make an @dfn{absolute reference}. The formula relocator skips over | |
819 | quoted things, so this will not be relocated when pasted or when | |
820 | rows/columns are inserted/deleted. However, B3 will not be recorded | |
821 | as a dependency of this cell, so this cell will not be updated | |
822 | automatically when B3 is changed. | |
823 | ||
824 | The variables @code{row} and @code{col} are dynamically bound while a | |
825 | cell formula is being evaluated. You can use | |
826 | @lisp | |
827 | (ses-cell-value row 0) | |
828 | @end lisp | |
829 | to get the value from the leftmost column in the current row. This | |
830 | kind of dependency is also not recorded. | |
831 | ||
832 | ||
833 | @node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus | |
834 | @section The data area | |
ef80b743 JY |
835 | @cindex data area |
836 | @findex ses-reconstruct-all | |
7ed9159a JY |
837 | |
838 | Begins with an 014 character, followed by sets of cell-definition | |
839 | macros for each row, followed by column-widths, column-printers, | |
840 | default-printer, and header-row. Then there's the global parameters | |
841 | (file-format ID, numrows, numcols) and the local variables (specifying | |
842 | SES mode for the buffer, etc.) | |
843 | ||
844 | When a SES file is loaded, first the numrows and numcols values are | |
845 | loaded, then the entire data area is @code{eval}ed, and finally the local | |
846 | variables are processed. | |
847 | ||
848 | You can edit the data area, but don't insert or delete any newlines | |
849 | except in the local-variables part, since SES locates things by | |
850 | counting newlines. Use @kbd{C-x C-e} at the end of a line to install | |
851 | your edits into the spreadsheet data structures (this does not update | |
852 | the print area, use e.g. @kbd{C-c C-l} for that). | |
853 | ||
854 | The data area is maintained as an image of spreadsheet data | |
855 | structures that area stored in buffer-local variables. If the data | |
856 | area gets messed up, you can try reconstructing the data area from the | |
857 | data structures: | |
858 | ||
859 | @table @kbd | |
860 | @item C-c M-C-l | |
861 | (@code{ses-reconstruct-all}). | |
862 | @end table | |
863 | ||
864 | ||
865 | @node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus | |
866 | @section Buffer-local variables in spreadsheets | |
ef80b743 JY |
867 | @cindex buffer-local variables |
868 | @cindex variables, buffer-local | |
7ed9159a JY |
869 | |
870 | You can add additional local variables to the list at the bottom of | |
871 | the data area, such as hidden constants you want to refer to in your | |
872 | formulas. | |
873 | ||
874 | You can override the variable @code{symbolic-formulas} to be a list of | |
875 | symbols (as parenthesized strings) to show as completions for the ' | |
876 | command. This initial completions list is used instead of the actual | |
877 | set of symbols-as-formulas in the spreadsheet. | |
878 | ||
879 | For examples of these, see file @file{etc/ses-example.ses}. | |
880 | ||
881 | If (for some reason) you want your formulas or printers to save data | |
882 | into variables, you must declare these variables as buffer-locals in | |
883 | order to avoid a virus warning. | |
884 | ||
885 | You can define functions by making them values for the fake local | |
886 | variable @code{eval}. Such functions can then be used in your | |
887 | formulas and printers, but usually each @code{eval} is presented to | |
888 | the user during file loading as a potential virus --- this can get | |
889 | annoying. | |
890 | ||
891 | You can define functions in your @file{.emacs} file. Other people can | |
892 | still read the print area of your spreadsheet, but they won't be able | |
893 | to recalculate or reprint anything that depends on your functions. To | |
894 | avoid virus warnings, each function used in a formula needs | |
895 | @lisp | |
896 | (put 'your-function-name 'safe-function t) | |
897 | @end lisp | |
898 | ||
899 | @node Uses of defadvice in SES, , Buffer-local variables in spreadsheets, For Gurus | |
900 | @section Uses of defadvice in SES | |
ef80b743 JY |
901 | @cindex defadvice |
902 | @cindex undo-more | |
903 | @cindex copy-region-as-kill | |
904 | @cindex yank | |
7ed9159a JY |
905 | |
906 | @table @code | |
907 | @item undo-more | |
908 | Defines a new undo element format (@var{fun} . @var{args}), which | |
909 | means ``undo by applying @var{fun} to @var{args}''. For spreadsheet | |
910 | buffers, it allows undos in the data area even though that's outside | |
911 | the narrowing. | |
912 | ||
913 | @item copy-region-as-kill | |
914 | When copying from the print area of a spreadsheet, treat the region as | |
915 | a rectangle and attach each cell's formula and printer as 'ses | |
916 | properties. | |
917 | ||
918 | @item yank | |
919 | When yanking into the print area of a spreadsheet, first try to yank | |
920 | as cells (if the yank text has 'ses properties), then as tab-separated | |
921 | formulas, then (if all else fails) as a single formula for the current | |
922 | cell. | |
923 | @end table | |
924 | ||
ef80b743 JY |
925 | @c =================================================================== |
926 | @node Index, Acknowledgements, For Gurus, Top | |
35eb0fa1 | 927 | @unnumbered Index |
ef80b743 JY |
928 | |
929 | @printindex cp | |
930 | ||
7ed9159a JY |
931 | @c =================================================================== |
932 | ||
84247bb5 | 933 | @node Acknowledgements, GNU Free Documentation License, Index, Top |
7ed9159a JY |
934 | @chapter Acknowledgements |
935 | ||
c6e8a807 JY |
936 | Coding by: |
937 | @quotation | |
938 | Jonathan Yavner @email{jyavner@@member.fsf.org}@* | |
939 | Stefan Monnier @email{monnier@@gnu.org} | |
940 | @end quotation | |
941 | ||
ef80b743 JY |
942 | @noindent |
943 | Texinfo manual by: | |
944 | @quotation | |
945 | Jonathan Yavner @email{jyavner@@member.fsf.org}@* | |
946 | Brad Collins <brad@@chenla.org> | |
947 | @end quotation | |
948 | ||
949 | @noindent | |
c6e8a807 | 950 | Ideas from: |
7ed9159a JY |
951 | @quotation |
952 | Christoph Conrad @email{christoph.conrad@@gmx.de}@* | |
953 | CyberBob @email{cyberbob@@redneck.gacracker.org}@* | |
954 | Syver Enstad @email{syver-en@@online.no}@* | |
955 | Ami Fischman @email{fischman@@zion.bpnetworks.com}@* | |
956 | Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@* | |
957 | Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@* | |
958 | Yusong Li @email{lyusong@@hotmail.com}@* | |
4581649e | 959 | Juri Linkov @email{juri@@jurta.org}@* |
7ed9159a JY |
960 | Harald Maier @email{maierh@@myself.com}@* |
961 | Alan Nash @email{anash@@san.rr.com}@* | |
962 |