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