*** empty log message ***
[emacs.git] / lispintro / emacs-lisp-intro.texi
blobcf01932d024ea08cac021ac01591011d2b01c0ff
1 \input texinfo                                  @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename ../info/eintr
4 @c sethtmlfilename emacs-lisp-intro.html
5 @settitle Programming in Emacs Lisp
6 @syncodeindex vr cp
7 @syncodeindex fn cp
8 @setchapternewpage odd
9 @finalout
11 @c ---------
12 @c <<<< For hard copy printing, this file is now
13 @c      set for smallbook, which works for all sizes
14 @c      of paper, and with Postscript figures >>>>
15 @smallbook
16 @clear  largebook
17 @set print-postscript-figures
18 @c set largebook
19 @c clear print-postscript-figures
20 @c ---------
22 @comment %**end of header
24 @set edition-number 2.12
25 @set update-date 2003 Nov 19
27 @ignore
28  ## Summary of shell commands to create various output formats:
30     ## Info output
31     makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
33     ## DVI output
34     texi2dvi emacs-lisp-intro.texi
36     ## HTML output
37     makeinfo --html --no-split --verbose emacs-lisp-intro.texi
39     ## Plain text output
40     makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
41     --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
43     ## DocBook output
44     makeinfo --docbook --no-split --paragraph-indent=0 \
45     --verbose emacs-lisp-intro.texi
47     ## XML output
48     makeinfo --xml --no-split --paragraph-indent=0 \
49     --verbose emacs-lisp-intro.texi
51     #### (You must be in the same directory as the viewed file.)
53       ## View DVI output
54       xdvi emacs-lisp-intro.dvi &
56       ## View HTML output
57       galeon emacs-lisp-intro.html
59       ## View Info output with standalone reader
60       info emacs-lisp-intro.info
62 @end ignore
64 @c ================ Included Figures ================
66 @c Set  print-postscript-figures  if you print PostScript figures.
67 @c If you clear this, the ten figures will be printed as ASCII diagrams.
68 @c (This is not relevant to Info, since Info only handles ASCII.)
69 @c Your site may require editing changes to print PostScript; in this
70 @c case, search for `print-postscript-figures' and make appropriate changes.
73 @c ================ How to Create an Info file ================
75 @c If you have `makeinfo' installed, run the following command
77 @c     makeinfo emacs-lisp-intro.texi
79 @c or, if you want a single, large Info file, and no paragraph indents:
80 @c     makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
82 @c After creating the Info file, edit your Info `dir' file, if the
83 @c `dircategory' section below does not enable your system to
84 @c install the manual automatically.
85 @c (The `dir' file is often in the `/usr/local/info/' directory.)
87 @c ================ How to Create an HTML file ================
89 @c To convert to HTML format
90 @c     makeinfo --html --no-split --verbose emacs-lisp-intro.texi
92 @c ================ How to Print a Book in Various Sizes ================
94 @c This book can be printed in any of three different sizes.
95 @c In the above header, set @-commands appropriately.
97 @c     7 by 9.25 inches:
98 @c              @smallbook
99 @c              @clear largebook
101 @c     8.5 by 11 inches:
102 @c              @c smallbook
103 @c              @set largebook
105 @c     European A4 size paper:
106 @c              @c smallbook
107 @c              @afourpaper
108 @c              @set largebook
110 @c ================ How to Typeset and Print ================
112 @c If you do not include PostScript figures, run either of the
113 @c following command sequences, or similar commands suited to your
114 @c system:
116 @c     texi2dvi emacs-lisp-intro.texi
117 @c     lpr -d emacs-lisp-intro.dvi
119 @c or else:
121 @c     tex emacs-lisp-intro.texi
122 @c     texindex emacs-lisp-intro.??
123 @c     tex emacs-lisp-intro.texi
124 @c     lpr -d emacs-lisp-intro.dvi
126 @c If you include the PostScript figures, and you have old software,
127 @c you may need to convert the .dvi file to a .ps file before
128 @c printing.  Run either of the following command sequences, or one
129 @c similar:
131 @c     dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
133 @c or else:
135 @c     postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
138 @c (Note: if you edit the book so as to change the length of the
139 @c table of contents, you may have to change the value of `pageno' below.)
141 @c ================ End of Formatting Sections ================
143 @c For next or subsequent edition:
144 @c   create function using with-output-to-temp-buffer
145 @c   create a major mode, with keymaps
146 @c   run an asynchronous process, like grep or diff
148 @c For 8.5 by 11 inch format: do not use such a small amount of
149 @c whitespace between paragraphs as smallbook format
150 @ifset largebook
151 @tex
152 \global\parskip 6pt plus 1pt
153 @end tex
154 @end ifset
156 @c For all sized formats:  print within-book cross
157 @c reference with ``...''  rather than [...]
159 @c This works with the texinfo.tex file, version 2003-05-04.08,
160 @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
162 @tex
163 \global\def\xrefprintnodename#1{``#1''}
164 @end tex
166 @c ----------------------------------------------------
168 @dircategory Emacs
169 @direntry
170 * Emacs Lisp Intro: (eintr).
171                         A simple introduction to Emacs Lisp programming.
172 @end direntry
174 @copying
175 This is an @cite{Introduction to Programming in Emacs Lisp}, for
176 people who are not programmers.
177 @sp 1
178 Edition @value{edition-number}, @value{update-date}
179 @sp 1
180 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
181 2002, 2003 Free Software Foundation, Inc.
182 @sp 1
184 @iftex
185 Published by the:@*
187 GNU Press,                      @hfill  @uref{http://www.gnupress.org}@*
188 a division of the               @hfill General: @email{press@@gnu.org}@*
189 Free Software Foundation, Inc.  @hfill Orders:@w{ }  @email{sales@@gnu.org}@*
190 59 Temple Place, Suite 330      @hfill Tel: +1 (617) 542-5942@*
191 Boston, MA 02111-1307 USA       @hfill Fax: +1 (617) 542-2652@*
192 @end iftex
194 @ifnottex
195 Published by the:
197 @example
198 GNU Press,                          Website: http://www.gnupress.org
199 a division of the                   General: press@@gnu.org
200 Free Software Foundation, Inc.      Orders:  sales@@gnu.org
201 59 Temple Place, Suite 330          Tel: +1 (617) 542-5942
202 Boston, MA 02111-1307 USA           Fax: +1 (617) 542-2652
203 @end example
204 @end ifnottex
206 @sp 1
207 @c Printed copies are available for $30 each.@*
208 ISBN 1-882114-43-4
210 Permission is granted to copy, distribute and/or modify this document
211 under the terms of the GNU Free Documentation License, Version 1.1 or
212 any later version published by the Free Software Foundation; there
213 being no Invariant Section, with the Front-Cover Texts being ``A GNU
214 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of
215 the license is included in the section entitled ``GNU Free
216 Documentation License''.
218 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
219 modify this GNU Manual, like GNU software.  Copies published by the
220 Free Software Foundation raise funds for GNU development.''
221 @end copying
223 @c half title; two lines here, so do not use `shorttitlepage'
224 @tex
225 {\begingroup%
226     \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
227         \endgroup}%
228 {\begingroup\hbox{}\vskip 0.25in \chaprm%
229         \centerline{Programming in Emacs Lisp}%
230         \endgroup\page\hbox{}\page}
231 @end tex
233 @titlepage
234 @sp 6
235 @center @titlefont{An Introduction to}
236 @sp 2
237 @center @titlefont{Programming in Emacs Lisp}
238 @sp 2
239 @center Revised Second Edition
240 @sp 4
241 @center by Robert J. Chassell
243 @page
244 @vskip 0pt plus 1filll
245 @insertcopying
246 @end titlepage
248 @iftex
249 @headings off
250 @evenheading @thispage @| @| @thischapter
251 @oddheading @thissection @| @| @thispage
252 @end iftex
254 @ifnothtml
255 @c     Keep T.O.C. short by tightening up for largebook
256 @ifset largebook
257 @tex
258 \global\parskip 2pt plus 1pt
259 \global\advance\baselineskip by -1pt
260 @end tex
261 @end ifset
262 @end ifnothtml
264 @shortcontents
265 @contents
267 @ifnottex
268 @node Top, Preface, (dir), (dir)
269 @top An Introduction to Programming in Emacs Lisp
271 @insertcopying
273 This master menu first lists each chapter and index; then it lists
274 every node in every chapter.
275 @end ifnottex
277 @menu
278 * Preface::                     What to look for.
279 * List Processing::             What is Lisp?
280 * Practicing Evaluation::       Running several programs.
281 * Writing Defuns::              How to write function definitions.
282 * Buffer Walk Through::         Exploring a few buffer-related functions.
283 * More Complex::                A few, even more complex functions.
284 * Narrowing & Widening::        Restricting your and Emacs attention to
285                                     a region.
286 * car cdr & cons::              Fundamental functions in Lisp.
287 * Cutting & Storing Text::      Removing text and saving it.
288 * List Implementation::         How lists are implemented in the computer.
289 * Yanking::                     Pasting stored text.
290 * Loops & Recursion::           How to repeat a process.
291 * Regexp Search::               Regular expression searches.
292 * Counting Words::              A review of repetition and regexps.
293 * Words in a defun::            Counting words in a @code{defun}.
294 * Readying a Graph::            A prototype graph printing function.
295 * Emacs Initialization::        How to write a @file{.emacs} file.
296 * Debugging::                   How to run the Emacs Lisp debuggers.
297 * Conclusion::                  Now you have the basics.
298 * the-the::                     An appendix: how to find reduplicated words.
299 * Kill Ring::                   An appendix: how the kill ring works.
300 * Full Graph::                  How to create a graph with labelled axes.
301 * Free Software and Free Manuals::
302 * GNU Free Documentation License::
303 * Index::
304 * About the Author::
306 @detailmenu
307  --- The Detailed Node Listing ---
309 Preface
311 * Why::                         Why learn Emacs Lisp?
312 * On Reading this Text::        Read, gain familiarity, pick up habits....
313 * Who You Are::                 For whom this is written.
314 * Lisp History::
315 * Note for Novices::            You can read this as a novice.
316 * Thank You::
318 List Processing
320 * Lisp Lists::                  What are lists?
321 * Run a Program::               Any list in Lisp is a program ready to run.
322 * Making Errors::               Generating an error message.
323 * Names & Definitions::         Names of symbols and function definitions.
324 * Lisp Interpreter::            What the Lisp interpreter does.
325 * Evaluation::                  Running a program.
326 * Variables::                   Returning a value from a variable.
327 * Arguments::                   Passing information to a function.
328 * set & setq::                  Setting the value of a variable.
329 * Summary::                     The major points.
330 * Error Message Exercises::
332 Lisp Lists
334 * Numbers Lists::               List have numbers, other lists, in them.
335 * Lisp Atoms::                  Elemental entities.
336 * Whitespace in Lists::         Formating lists to be readable.
337 * Typing Lists::                How GNU Emacs helps you type lists.
339 The Lisp Interpreter
341 * Complications::               Variables, Special forms, Lists within.
342 * Byte Compiling::              Specially processing code for speed.
344 Evaluation
346 * Evaluating Inner Lists::      Lists within lists...
348 Variables
350 * fill-column Example::
351 * Void Function::               The error message for a symbol
352                                   without a function.
353 * Void Variable::               The error message for a symbol without a value.
355 Arguments
357 * Data types::                  Types of data passed to a function.
358 * Args as Variable or List::    An argument can be the value
359                                   of a variable or list.
360 * Variable Number of Arguments::  Some functions may take a
361                                   variable number of arguments.
362 * Wrong Type of Argument::      Passing an argument of the wrong type
363                                   to a function.
364 * message::                     A useful function for sending messages.
366 Setting the Value of a Variable
368 * Using set::                   Setting values.
369 * Using setq::                  Setting a quoted value.
370 * Counting::                    Using @code{setq} to count.
372 Practicing Evaluation
374 * How to Evaluate::             Typing editing commands or @kbd{C-x C-e}
375                                   causes evaluation.
376 * Buffer Names::                Buffers and files are different.
377 * Getting Buffers::             Getting a buffer itself, not merely its name.
378 * Switching Buffers::           How to change to another buffer.
379 * Buffer Size & Locations::     Where point is located and the size of
380                                 the buffer.
381 * Evaluation Exercise::
383 How To Write Function Definitions
385 * Primitive Functions::
386 * defun::                       The @code{defun} special form.
387 * Install::                     Install a function definition.
388 * Interactive::                 Making a function interactive.
389 * Interactive Options::         Different options for @code{interactive}.
390 * Permanent Installation::      Installing code permanently.
391 * let::                         Creating and initializing local variables.
392 * if::                          What if?
393 * else::                        If--then--else expressions.
394 * Truth & Falsehood::           What Lisp considers false and true.
395 * save-excursion::              Keeping track of point, mark, and buffer.
396 * Review::
397 * defun Exercises::
399 Install a Function Definition
401 * Effect of installation::
402 * Change a defun::              How to change a function definition.
404 Make a Function Interactive
406 * Interactive multiply-by-seven::  An overview.
407 * multiply-by-seven in detail::  The interactive version.
409 @code{let}
411 * Prevent confusion::
412 * Parts of let Expression::
413 * Sample let Expression::
414 * Uninitialized let Variables::
416 The @code{if} Special Form
418 * if in more detail::
419 * type-of-animal in detail::    An example of an @code{if} expression.
421 Truth and Falsehood in Emacs Lisp
423 * nil explained::               @code{nil} has two meanings.
425 @code{save-excursion}
427 * Point and mark::              A review of various locations.
428 * Template for save-excursion::
430 A Few Buffer--Related Functions
432 * Finding More::                How to find more information.
433 * simplified-beginning-of-buffer::  Shows @code{goto-char},
434                                 @code{point-min}, and @code{push-mark}.
435 * mark-whole-buffer::           Almost the same as @code{beginning-of-buffer}.
436 * append-to-buffer::            Uses @code{save-excursion} and
437                                 @code{insert-buffer-substring}.
438 * Buffer Related Review::       Review.
439 * Buffer Exercises::
441 The Definition of @code{mark-whole-buffer}
443 * mark-whole-buffer overview::
444 * Body of mark-whole-buffer::   Only three lines of code.
446 The Definition of @code{append-to-buffer}
448 * append-to-buffer overview::
449 * append interactive::          A two part interactive expression.
450 * append-to-buffer body::       Incorporates a @code{let} expression.
451 * append save-excursion::       How the @code{save-excursion} works.
453 A Few More Complex Functions
455 * copy-to-buffer::              With @code{set-buffer}, @code{get-buffer-create}.
456 * insert-buffer::               Read-only, and with @code{or}.
457 * beginning-of-buffer::         Shows @code{goto-char},
458                                 @code{point-min}, and @code{push-mark}.
459 * Second Buffer Related Review::
460 * optional Exercise::
462 The Definition of @code{insert-buffer}
464 * insert-buffer code::
465 * insert-buffer interactive::   When you can read, but not write.
466 * insert-buffer body::          The body has an @code{or} and a @code{let}.
467 * if & or::                     Using an @code{if} instead of an @code{or}.
468 * Insert or::                   How the @code{or} expression works.
469 * Insert let::                  Two @code{save-excursion} expressions.
471 The Interactive Expression in @code{insert-buffer}
473 * Read-only buffer::            When a buffer cannot be modified.
474 * b for interactive::           An existing buffer or else its name.
476 Complete Definition of @code{beginning-of-buffer}
478 * Optional Arguments::
479 * beginning-of-buffer opt arg::  Example with optional argument.
480 * beginning-of-buffer complete::
482 @code{beginning-of-buffer} with an Argument
484 * Disentangle beginning-of-buffer::
485 * Large buffer case::
486 * Small buffer case::
488 Narrowing and Widening
490 * Narrowing advantages::        The advantages of narrowing
491 * save-restriction::            The @code{save-restriction} special form.
492 * what-line::                   The number of the line that point is on.
493 * narrow Exercise::
495 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
497 * Strange Names::               An historical aside: why the strange names?
498 * car & cdr::                   Functions for extracting part of a list.
499 * cons::                        Constructing a list.
500 * nthcdr::                      Calling @code{cdr} repeatedly.
501 * nth::
502 * setcar::                      Changing the first element of a list.
503 * setcdr::                      Changing the rest of a list.
504 * cons Exercise::
506 @code{cons}
508 * Build a list::
509 * length::                      How to find the length of a list.
511 Cutting and Storing Text
513 * Storing Text::                Text is stored in a list.
514 * zap-to-char::                 Cutting out text up to a character.
515 * kill-region::                 Cutting text out of a region.
516 * Digression into C::           Minor note on C programming language macros.
517 * defvar::                      How to give a variable an initial value.
518 * copy-region-as-kill::         A definition for copying text.
519 * cons & search-fwd Review::
520 * search Exercises::
522 @code{zap-to-char}
524 * Complete zap-to-char::        The complete implementation.
525 * zap-to-char interactive::     A three part interactive expression.
526 * zap-to-char body::            A short overview.
527 * search-forward::              How to search for a string.
528 * progn::                       The @code{progn} special form.
529 * Summing up zap-to-char::      Using @code{point} and @code{search-forward}.
531 @code{kill-region}
533 * Complete kill-region::        The function definition.
534 * condition-case::              Dealing with a problem.
535 * delete-and-extract-region::   Doing the work.
537 Initializing a Variable with @code{defvar}
539 * See variable current value::
540 * defvar and asterisk::         An old-time convention.
542 @code{copy-region-as-kill}
544 * Complete copy-region-as-kill::  The complete function definition.
545 * copy-region-as-kill body::    The body of @code{copy-region-as-kill}.
547 The Body of @code{copy-region-as-kill}
549 * last-command & this-command::
550 * kill-append function::
551 * kill-new function::
553 How Lists are Implemented
555 * Lists diagrammed::
556 * Symbols as Chest::            Exploring a powerful metaphor.
557 * List Exercise::
559 Yanking Text Back
561 * Kill Ring Overview::          The kill ring is a list.
562 * kill-ring-yank-pointer::      The @code{kill-ring-yank-pointer} variable.
563 * yank nthcdr Exercises::
565 Loops and Recursion
567 * while::                       Causing a stretch of code to repeat.
568 * dolist dotimes::
569 * Recursion::                   Causing a function to call itself.
570 * Looping exercise::
572 @code{while}
574 * Looping with while::          Repeat so long as test returns true.
575 * Loop Example::                A @code{while} loop that uses a list.
576 * print-elements-of-list::      Uses @code{while}, @code{car}, @code{cdr}.
577 * Incrementing Loop::           A loop with an incrementing counter.
578 * Decrementing Loop::           A loop with a decrementing counter.
580 A Loop with an Incrementing Counter
582 * Incrementing Example::        Counting pebbles in a triangle.
583 * Inc Example parts::           The parts of the function definition.
584 * Inc Example altogether::      Putting the function definition together.
586 Loop with a Decrementing Counter
588 * Decrementing Example::        More pebbles on the beach.
589 * Dec Example parts::           The parts of the function definition.
590 * Dec Example altogether::      Putting the function definition together.
592 Save your time: @code{dolist} and @code{dotimes}
594 * dolist::
595 * dotimes::
597 Recursion
599 * Building Robots::             Same model, different serial number ...
600 * Recursive Definition Parts::  Walk until you stop ...
601 * Recursion with list::         Using a list as the test whether to recurse.
602 * Recursive triangle function::
603 * Recursion with cond::
604 * Recursive Patterns::          Often used templates.
605 * No Deferment::                Don't store up work ...
606 * No deferment solution::
608 Recursion in Place of a Counter
610 * Recursive Example arg of 1 or 2::
611 * Recursive Example arg of 3 or 4::
613 Recursive Patterns
615 * Every::
616 * Accumulate::
617 * Keep::
619 Regular Expression Searches
621 * sentence-end::                The regular expression for @code{sentence-end}.
622 * re-search-forward::           Very similar to @code{search-forward}.
623 * forward-sentence::            A straightforward example of regexp search.
624 * forward-paragraph::           A somewhat complex example.
625 * etags::                       How to create your own @file{TAGS} table.
626 * Regexp Review::
627 * re-search Exercises::
629 @code{forward-sentence}
631 * Complete forward-sentence::
632 * fwd-sentence while loops::    Two @code{while} loops.
633 * fwd-sentence re-search::      A regular expression search.
635 @code{forward-paragraph}: a Goldmine of Functions
637 * forward-paragraph in brief::  Key parts of the function definition.
638 * fwd-para let::                The @code{let*} expression.
639 * fwd-para while::              The forward motion @code{while} loop.
640 * fwd-para between paragraphs::  Movement between paragraphs.
641 * fwd-para within paragraph::   Movement within paragraphs.
642 * fwd-para no fill prefix::     When there is no fill prefix.
643 * fwd-para with fill prefix::   When there is a fill prefix.
644 * fwd-para summary::            Summary of @code{forward-paragraph} code.
646 Counting: Repetition and Regexps
648 * Why Count Words::
649 * count-words-region::          Use a regexp, but find a problem.
650 * recursive-count-words::       Start with case of no words in region.
651 * Counting Exercise::
653 The @code{count-words-region} Function
655 * Design count-words-region::   The definition using a @code{while} loop.
656 * Whitespace Bug::              The Whitespace Bug in @code{count-words-region}.
658 Counting Words in a @code{defun}
660 * Divide and Conquer::
661 * Words and Symbols::           What to count?
662 * Syntax::                      What constitutes a word or symbol?
663 * count-words-in-defun::        Very like @code{count-words}.
664 * Several defuns::              Counting several defuns in a file.
665 * Find a File::                 Do you want to look at a file?
666 * lengths-list-file::           A list of the lengths of many definitions.
667 * Several files::               Counting in definitions in different files.
668 * Several files recursively::   Recursively counting in different files.
669 * Prepare the data::            Prepare the data for display in a graph.
671 Count Words in @code{defuns} in Different Files
673 * lengths-list-many-files::     Return a list of the lengths of defuns.
674 * append::                      Attach one list to another.
676 Prepare the Data for Display in a Graph
678 * Sorting::                     Sorting lists.
679 * Files List::                  Making a list of files.
680 * Counting function definitions::
682 Readying a Graph
684 * Columns of a graph::
685 * graph-body-print::            How to print the body of a graph.
686 * recursive-graph-body-print::
687 * Printed Axes::
688 * Line Graph Exercise::
690 Your @file{.emacs} File
692 * Default Configuration::
693 * Site-wide Init::              You can write site-wide init files.
694 * defcustom::                   Emacs will write code for you.
695 * Beginning a .emacs File::     How to write a @code{.emacs file}.
696 * Text and Auto-fill::          Automatically wrap lines.
697 * Mail Aliases::                Use abbreviations for email addresses.
698 * Indent Tabs Mode::            Don't use tabs with @TeX{}
699 * Keybindings::                 Create some personal keybindings.
700 * Keymaps::                     More about key binding.
701 * Loading Files::               Load (i.e., evaluate) files automatically.
702 * Autoload::                    Make functions available.
703 * Simple Extension::            Define a function; bind it to a key.
704 * X11 Colors::                  Colors in version 19 in X.
705 * Miscellaneous::
706 * Mode Line::                   How to customize your mode line.
708 Debugging
710 * debug::                       How to use the built-in debugger.
711 * debug-on-entry::              Start debugging when you call a function.
712 * debug-on-quit::               Start debugging when you quit with @kbd{C-g}.
713 * edebug::                      How to use Edebug, a source level debugger.
714 * Debugging Exercises::
716 Handling the Kill Ring
718 * rotate-yank-pointer::         Move a pointer along a list and around.
719 * yank::                        Paste a copy of a clipped element.
720 * yank-pop::                    Insert first element pointed to.
721 * ring file::
723 The @code{rotate-yank-pointer} Function
725 * Understanding rotate-yk-ptr::
726 * rotate-yk-ptr body::          The body of @code{rotate-yank-pointer}.
728 The Body of @code{rotate-yank-pointer}
730 * Digression concerning error::  How to mislead humans, but not computers.
731 * rotate-yk-ptr else-part::     The else-part of the @code{if} expression.
732 * Remainder Function::          The remainder, @code{%}, function.
733 * rotate-yk-ptr remainder::     Using @code{%} in @code{rotate-yank-pointer}.
734 * kill-rng-yk-ptr last elt::    Pointing to the last element.
736 @code{yank}
738 * rotate-yk-ptr arg::           Pass the argument to @code{rotate-yank-pointer}.
739 * rotate-yk-ptr negative arg::  Pass a negative argument.
741 A Graph with Labelled Axes
743 * Labelled Example::
744 * print-graph Varlist::         @code{let} expression in @code{print-graph}.
745 * print-Y-axis::                Print a label for the vertical axis.
746 * print-X-axis::                Print a horizontal label.
747 * Print Whole Graph::           The function to print a complete graph.
749 The @code{print-Y-axis} Function
751 * Height of label::             What height for the Y axis?
752 * Compute a Remainder::         How to compute the remainder of a division.
753 * Y Axis Element::              Construct a line for the Y axis.
754 * Y-axis-column::               Generate a list of Y axis labels.
755 * print-Y-axis Penultimate::    A not quite final version.
757 The @code{print-X-axis} Function
759 * Similarities differences::    Much like @code{print-Y-axis}, but not exactly.
760 * X Axis Tic Marks::            Create tic marks for the horizontal axis.
762 Printing the Whole Graph
764 * The final version::           A few changes.
765 * Test print-graph::            Run a short test.
766 * Graphing words in defuns::    Executing the final code.
767 * lambda::                      How to write an anonymous function.
768 * mapcar::                      Apply a function to elements of a list.
769 * Another Bug::                 Yet another bug @dots{} most insidious.
770 * Final printed graph::         The graph itself!
772 @end detailmenu
773 @end menu
775 @c >>>> Set pageno appropriately <<<<
777 @c The first page of the Preface is a roman numeral; it is the first
778 @c right handed page after the Table of Contents; hence the following
779 @c setting must be for an odd negative number.
781 @iftex
782 @global@pageno = -11
783 @end iftex
785 @node Preface, List Processing, Top, Top
786 @comment  node-name,  next,  previous,  up
787 @unnumbered Preface
789 Most of the GNU Emacs integrated environment is written in the programming
790 language called Emacs Lisp.  The code written in this programming
791 language is the software---the sets of instructions---that tell the
792 computer what to do when you give it commands.  Emacs is designed so
793 that you can write new code in Emacs Lisp and easily install it as an
794 extension to the editor.
796 (GNU Emacs is sometimes called an ``extensible editor'', but it does
797 much more than provide editing capabilities.  It is better to refer to
798 Emacs as an ``extensible computing environment''.  However, that
799 phrase is quite a mouthful.  It is easier to refer to Emacs simply as
800 an editor.  Moreover, everything you do in Emacs---find the Mayan date
801 and phases of the moon, simplify polynomials, debug code, manage
802 files, read letters, write books---all these activities are kinds of
803 editing in the most general sense of the word.)
805 @menu
806 * Why::                         Why learn Emacs Lisp?
807 * On Reading this Text::        Read, gain familiarity, pick up habits....
808 * Who You Are::                 For whom this is written.
809 * Lisp History::
810 * Note for Novices::            You can read this as a novice.
811 * Thank You::
812 @end menu
814 @node Why, On Reading this Text, Preface, Preface
815 @ifnottex
816 @unnumberedsec Why Study Emacs Lisp?
817 @end ifnottex
819 Although Emacs Lisp is usually thought of in association only with Emacs,
820 it is a full computer programming language.  You can use Emacs Lisp as
821 you would any other programming language.
823 Perhaps you want to understand programming; perhaps you want to extend
824 Emacs; or perhaps you want to become a programmer.  This introduction to
825 Emacs Lisp is designed to get you started: to guide you in learning the
826 fundamentals of programming, and more importantly, to show you how you
827 can teach yourself to go further.
829 @node On Reading this Text, Who You Are, Why, Preface
830 @comment  node-name,  next,  previous,  up
831 @unnumberedsec On Reading this Text
833 All through this document, you will see little sample programs you can
834 run inside of Emacs.  If you read this document in Info inside of GNU
835 Emacs, you can run the programs as they appear.  (This is easy to do and
836 is explained when the examples are presented.)  Alternatively, you can
837 read this introduction as a printed book while sitting beside a computer
838 running Emacs.  (This is what I like to do; I like printed books.)  If
839 you don't have a running Emacs beside you, you can still read this book,
840 but in this case, it is best to treat it as a novel or as a travel guide
841 to a country not yet visited: interesting, but not the same as being
842 there.
844 Much of this introduction is dedicated to walk-throughs or guided tours
845 of code used in GNU Emacs.  These tours are designed for two purposes:
846 first, to give you familiarity with real, working code (code you use
847 every day); and, second, to give you familiarity with the way Emacs
848 works.  It is interesting to see how a working environment is
849 implemented.
850 Also, I
851 hope that you will pick up the habit of browsing through source code.
852 You can learn from it and mine it for ideas.  Having GNU Emacs is like
853 having a dragon's cave of treasures.
855 In addition to learning about Emacs as an editor and Emacs Lisp as a
856 programming language, the examples and guided tours will give you an
857 opportunity to get acquainted with Emacs as a Lisp programming
858 environment.  GNU Emacs supports programming and provides tools that
859 you will want to become comfortable using, such as @kbd{M-.} (the key
860 which invokes the @code{find-tag} command).  You will also learn about
861 buffers and other objects that are part of the environment.
862 Learning about these features of Emacs is like learning new routes
863 around your home town.
865 @ignore
866 In addition, I have written several programs as extended examples.
867 Although these are examples, the programs are real.  I use them.
868 Other people use them.  You may use them.  Beyond the fragments of
869 programs used for illustrations, there is very little in here that is
870 `just for teaching purposes'; what you see is used.  This is a great
871 advantage of Emacs Lisp: it is easy to learn to use it for work.
872 @end ignore
874 Finally, I hope to convey some of the skills for using Emacs to
875 learn aspects of programming that you don't know.  You can often use
876 Emacs to help you understand what puzzles you or to find out how to do
877 something new.  This self-reliance is not only a pleasure, but an
878 advantage.
880 @node Who You Are, Lisp History, On Reading this Text, Preface
881 @comment  node-name,  next,  previous,  up
882 @unnumberedsec For Whom This is Written
884 This text is written as an elementary introduction for people who are
885 not programmers.  If you are a programmer, you may not be satisfied with
886 this primer.  The reason is that you may have become expert at reading
887 reference manuals and be put off by the way this text is organized.
889 An expert programmer who reviewed this text said to me:
891 @quotation
892 @i{I prefer to learn from reference manuals.  I ``dive into'' each
893 paragraph, and ``come up for air'' between paragraphs.}
895 @i{When I get to the end of a paragraph, I assume that that subject is
896 done, finished, that I know everything I need (with the
897 possible exception of the case when the next paragraph starts talking
898 about it in more detail).  I expect that a well written reference manual
899 will not have a lot of redundancy, and that it will have excellent
900 pointers to the (one) place where the information I want is.}
901 @end quotation
903 This introduction is not written for this person!
905 Firstly, I try to say everything at least three times: first, to
906 introduce it; second, to show it in context; and third, to show it in a
907 different context, or to review it.
909 Secondly, I hardly ever put all the information about a subject in one
910 place, much less in one paragraph.  To my way of thinking, that imposes
911 too heavy a burden on the reader.  Instead I try to explain only what
912 you need to know at the time.  (Sometimes I include a little extra
913 information so you won't be surprised later when the additional
914 information is formally introduced.)
916 When you read this text, you are not expected to learn everything the
917 first time.  Frequently, you need only make, as it were, a `nodding
918 acquaintance' with some of the items mentioned.  My hope is that I have
919 structured the text and given you enough hints that you will be alert to
920 what is important, and concentrate on it.
922 You will need to ``dive into'' some paragraphs; there is no other way
923 to read them.  But I have tried to keep down the number of such
924 paragraphs.  This book is intended as an approachable hill, rather than
925 as a daunting mountain.
927 This introduction to @cite{Programming in Emacs Lisp} has a companion
928 document,
929 @iftex
930 @cite{The GNU Emacs Lisp Reference Manual}.
931 @end iftex
932 @ifnottex
933 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
934 Emacs Lisp Reference Manual}.
935 @end ifnottex
936 The reference manual has more detail than this introduction.  In the
937 reference manual, all the information about one topic is concentrated
938 in one place.  You should turn to it if you are like the programmer
939 quoted above.  And, of course, after you have read this
940 @cite{Introduction}, you will find the @cite{Reference Manual} useful
941 when you are writing your own programs.
943 @node Lisp History, Note for Novices, Who You Are, Preface
944 @unnumberedsec Lisp History
945 @cindex Lisp history
947 Lisp was first developed in the late 1950s at the Massachusetts
948 Institute of Technology for research in artificial intelligence.  The
949 great power of the Lisp language makes it superior for other purposes as
950 well, such as writing editor commands and integrated environments.
952 @cindex Maclisp
953 @cindex Common Lisp
954 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT
955 in the 1960s.  It is somewhat inspired by Common Lisp, which became a
956 standard in the 1980s.  However, Emacs Lisp is much simpler than Common
957 Lisp.  (The standard Emacs distribution contains an optional extensions
958 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.)
960 @node Note for Novices, Thank You, Lisp History, Preface
961 @comment  node-name,  next,  previous,  up
962 @unnumberedsec A Note for Novices
964 If you don't know GNU Emacs, you can still read this document
965 profitably.  However, I recommend you learn Emacs, if only to learn to
966 move around your computer screen.  You can teach yourself how to use
967 Emacs with the on-line tutorial.  To use it, type @kbd{C-h t}.  (This
968 means you press and release the @key{CTRL} key and the @kbd{h} at the
969 same time, and then press and release @kbd{t}.)
971 Also, I often refer to one of Emacs' standard commands by listing the
972 keys which you press to invoke the command and then giving the name of
973 the command in parentheses, like this: @kbd{M-C-\}
974 (@code{indent-region}).  What this means is that the
975 @code{indent-region} command is customarily invoked by typing
976 @kbd{M-C-\}.  (You can, if you wish, change the keys that are typed to
977 invoke the command; this is called @dfn{rebinding}.  @xref{Keymaps, ,
978 Keymaps}.)  The abbreviation @kbd{M-C-\} means that you type your
979 @key{META} key, @key{CTRL} key and @key{\} key all at the same time.
980 (On many modern keyboards the @key{META} key is labelled
981 @key{ALT}.)
982 Sometimes a combination like this is called a keychord, since it is
983 similar to the way you play a chord on a piano.  If your keyboard does
984 not have a @key{META} key, the @key{ESC} key prefix is used in place
985 of it.  In this case, @kbd{M-C-\} means that you press and release your
986 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
987 the same time.  But usually @kbd{M-C-\} means press the @key{CTRL} key
988 along with the key that is labelled @key{ALT} and, at the same time,
989 press the @key{\} key.
991 In addition to typing a lone keychord, you can prefix what you type
992 with @kbd{C-u}, which is called the `universal argument'.  The
993 @kbd{C-u} keychord passes an argument to the subsequent command.
994 Thus, to indent a region of plain text by 6 spaces, mark the region,
995 and then type @w{@kbd{C-u 6 M-C-\}}.  (If you do not specify a number,
996 Emacs either passes the number 4 to the command or otherwise runs the
997 command differently than it would otherwise.)  @xref{Arguments, ,
998 Numeric Arguments, emacs, The GNU Emacs Manual}.
1000 If you are reading this in Info using GNU Emacs, you can read through
1001 this whole document just by pressing the space bar, @key{SPC}.
1002 (To learn about Info, type @kbd{C-h i} and then select Info.)
1004 A note on terminology:  when I use the word Lisp alone, I often am
1005 referring to the various dialects of Lisp in general, but when I speak
1006 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
1008 @node Thank You,  , Note for Novices, Preface
1009 @comment  node-name,  next,  previous,  up
1010 @unnumberedsec Thank You
1012 My thanks to all who helped me with this book.  My especial thanks to
1013 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
1014 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@:
1015 Stallman}, and @w{Melissa Weisshaus}.  My thanks also go to both
1016 @w{Philip Johnson} and @w{David Stampe} for their patient
1017 encouragement.  My mistakes are my own.
1019 @flushright
1020 Robert J. Chassell
1021 @end flushright
1023 @c ================ Beginning of main text ================
1025 @c Start main text on right-hand (verso) page
1027 @tex
1028 \par\vfill\supereject
1029 \headings off
1030 \ifodd\pageno
1031     \par\vfill\supereject
1032 \else
1033     \par\vfill\supereject
1034     \page\hbox{}\page
1035     \par\vfill\supereject
1037 @end tex
1039 @iftex
1040 @headings off
1041 @evenheading @thispage @| @| @thischapter
1042 @oddheading @thissection @| @| @thispage
1043 @global@pageno = 1
1044 @end iftex
1046 @node List Processing, Practicing Evaluation, Preface, Top
1047 @comment  node-name,  next,  previous,  up
1048 @chapter List Processing
1050 To the untutored eye, Lisp is a strange programming language.  In Lisp
1051 code there are parentheses everywhere.  Some people even claim that the
1052 name stands for `Lots of Isolated Silly Parentheses'.  But the claim is
1053 unwarranted.  Lisp stands for LISt Processing, and the programming
1054 language handles @emph{lists} (and lists of lists) by putting them
1055 between parentheses.  The parentheses mark the boundaries of the list.
1056 Sometimes a list is preceded by a single apostrophe or quotation mark,
1057 @samp{'}.  Lists are the basis of Lisp.
1059 @menu
1060 * Lisp Lists::                  What are lists?
1061 * Run a Program::               Any list in Lisp is a program ready to run.
1062 * Making Errors::               Generating an error message.
1063 * Names & Definitions::         Names of symbols and function definitions.
1064 * Lisp Interpreter::            What the Lisp interpreter does.
1065 * Evaluation::                  Running a program.
1066 * Variables::                   Returning a value from a variable.
1067 * Arguments::                   Passing information to a function.
1068 * set & setq::                  Setting the value of a variable.
1069 * Summary::                     The major points.
1070 * Error Message Exercises::
1071 @end menu
1073 @node Lisp Lists, Run a Program, List Processing, List Processing
1074 @comment  node-name,  next,  previous,  up
1075 @section Lisp Lists
1076 @cindex Lisp Lists
1078 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}.
1079 This list is preceded by a single apostrophe.  It could just as well be
1080 written as follows, which looks more like the kind of list you are likely
1081 to be familiar with:
1083 @smallexample
1084 @group
1085 '(rose
1086   violet
1087   daisy
1088   buttercup)
1089 @end group
1090 @end smallexample
1092 @noindent
1093 The elements of this list are the names of the four different flowers,
1094 separated from each other by whitespace and surrounded by parentheses,
1095 like flowers in a field with a stone wall around them.
1096 @cindex Flowers in a field
1098 @menu
1099 * Numbers Lists::               List have numbers, other lists, in them.
1100 * Lisp Atoms::                  Elemental entities.
1101 * Whitespace in Lists::         Formating lists to be readable.
1102 * Typing Lists::                How GNU Emacs helps you type lists.
1103 @end menu
1105 @node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
1106 @ifnottex
1107 @unnumberedsubsec Numbers, Lists inside of Lists
1108 @end ifnottex
1110 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}.
1111 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each
1112 separated by whitespace.
1114 In Lisp, both data and programs are represented the same way; that is,
1115 they are both lists of words, numbers, or other lists, separated by
1116 whitespace and surrounded by parentheses.  (Since a program looks like
1117 data, one program may easily serve as data for another; this is a very
1118 powerful feature of Lisp.)  (Incidentally, these two parenthetical
1119 remarks are @emph{not} Lisp lists, because they contain @samp{;} and
1120 @samp{.} as punctuation marks.)
1122 @need 1200
1123 Here is another list, this time with a list inside of it:
1125 @smallexample
1126 '(this list has (a list inside of it))
1127 @end smallexample
1129 The components of this list are the words @samp{this}, @samp{list},
1130 @samp{has}, and the list @samp{(a list inside of it)}.  The interior
1131 list is made up of the words @samp{a}, @samp{list}, @samp{inside},
1132 @samp{of}, @samp{it}.
1134 @node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists
1135 @comment  node-name,  next,  previous,  up
1136 @subsection Lisp Atoms
1137 @cindex Lisp Atoms
1139 In Lisp, what we have been calling words are called @dfn{atoms}.  This
1140 term comes from the historical meaning of the word atom, which means
1141 `indivisible'.  As far as Lisp is concerned, the words we have been
1142 using in the lists cannot be divided into any smaller parts and still
1143 mean the same thing as part of a program; likewise with numbers and
1144 single character symbols like @samp{+}.  On the other hand, unlike an
1145 atom, a list can be split into parts.  (@xref{car cdr & cons, ,
1146 @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
1148 In a list, atoms are separated from each other by whitespace.  They can be
1149 right next to a parenthesis.
1151 @cindex @samp{empty list} defined
1152 Technically speaking, a list in Lisp consists of parentheses surrounding
1153 atoms separated by whitespace or surrounding other lists or surrounding
1154 both atoms and other lists.  A list can have just one atom in it or
1155 have nothing in it at all.  A list with nothing in it looks like this:
1156 @code{()}, and is called the @dfn{empty list}.  Unlike anything else, an
1157 empty list is considered both an atom and a list at the same time.
1159 @cindex Symbolic expressions, introduced
1160 @cindex @samp{expression} defined
1161 @cindex @samp{form} defined
1162 The printed representation of both atoms and lists are called
1163 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
1164 The word @dfn{expression} by itself can refer to either the printed
1165 representation, or to the atom or list as it is held internally in the
1166 computer.  Often, people use the term @dfn{expression}
1167 indiscriminately.  (Also, in many texts, the word @dfn{form} is used
1168 as a synonym for expression.)
1170 Incidentally, the atoms that make up our universe were named such when
1171 they were thought to be indivisible; but it has been found that physical
1172 atoms are not indivisible.  Parts can split off an atom or it can
1173 fission into two parts of roughly equal size.  Physical atoms were named
1174 prematurely, before their truer nature was found.  In Lisp, certain
1175 kinds of atom, such as an array, can be separated into parts; but the
1176 mechanism for doing this is different from the mechanism for splitting a
1177 list.  As far as list operations are concerned, the atoms of a list are
1178 unsplittable.
1180 As in English, the meanings of the component letters of a Lisp atom
1181 are different from the meaning the letters make as a word.  For
1182 example, the word for the South American sloth, the @samp{ai}, is
1183 completely different from the two words, @samp{a}, and @samp{i}.
1185 There are many kinds of atom in nature but only a few in Lisp: for
1186 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such
1187 as @samp{+}, @samp{foo}, or @samp{forward-line}.  The words we have
1188 listed in the examples above are all symbols.  In everyday Lisp
1189 conversation, the word ``atom'' is not often used, because programmers
1190 usually try to be more specific about what kind of atom they are dealing
1191 with.  Lisp programming is mostly about symbols (and sometimes numbers)
1192 within lists.  (Incidentally, the preceding three word parenthetical
1193 remark is a proper list in Lisp, since it consists of atoms, which in
1194 this case are symbols, separated by whitespace and enclosed by
1195 parentheses, without any non-Lisp punctuation.)
1197 @need 1250
1198 In addition, text between double quotation marks---even sentences or
1199 paragraphs---is an atom.  Here is an example:
1200 @cindex Text between double quotation marks
1202 @smallexample
1203 '(this list includes "text between quotation marks.")
1204 @end smallexample
1206 @cindex @samp{string} defined
1207 @noindent
1208 In Lisp, all of the quoted text including the punctuation mark and the
1209 blank spaces is a single atom.  This kind of atom is called a
1210 @dfn{string} (for `string of characters') and is the sort of thing that
1211 is used for messages that a computer can print for a human to read.
1212 Strings are a different kind of atom than numbers or symbols and are
1213 used differently.
1215 @node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists
1216 @comment  node-name,  next,  previous,  up
1217 @subsection Whitespace in Lists
1218 @cindex Whitespace in lists
1220 @need 1200
1221 The amount of whitespace in a list does not matter.  From the point of view
1222 of the Lisp language,
1224 @smallexample
1225 @group
1226 '(this list
1227    looks like this)
1228 @end group
1229 @end smallexample
1231 @need 800
1232 @noindent
1233 is exactly the same as this:
1235 @smallexample
1236 '(this list looks like this)
1237 @end smallexample
1239 Both examples show what to Lisp is the same list, the list made up of
1240 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and
1241 @samp{this} in that order.
1243 Extra whitespace and newlines are designed to make a list more readable
1244 by humans.  When Lisp reads the expression, it gets rid of all the extra
1245 whitespace (but it needs to have at least one space between atoms in
1246 order to tell them apart.)
1248 Odd as it seems, the examples we have seen cover almost all of what Lisp
1249 lists look like!  Every other list in Lisp looks more or less like one
1250 of these examples, except that the list may be longer and more complex.
1251 In brief, a list is between parentheses, a string is between quotation
1252 marks, a symbol looks like a word, and a number looks like a number.
1253 (For certain situations, square brackets, dots and a few other special
1254 characters may be used; however, we will go quite far without them.)
1256 @node Typing Lists,  , Whitespace in Lists, Lisp Lists
1257 @comment  node-name,  next,  previous,  up
1258 @subsection GNU Emacs Helps You Type Lists
1259 @cindex Help typing lists
1260 @cindex Formatting help
1262 When you type a Lisp expression in GNU Emacs using either Lisp
1263 Interaction mode or Emacs Lisp mode, you have available to you several
1264 commands to format the Lisp expression so it is easy to read.  For
1265 example, pressing the @key{TAB} key automatically indents the line the
1266 cursor is on by the right amount.  A command to properly indent the
1267 code in a region is customarily bound to @kbd{M-C-\}.  Indentation is
1268 designed so that you can see which elements of a list belong to which
1269 list---elements of a sub-list are indented more than the elements of
1270 the enclosing list.
1272 In addition, when you type a closing parenthesis, Emacs momentarily
1273 jumps the cursor back to the matching opening parenthesis, so you can
1274 see which one it is.  This is very useful, since every list you type
1275 in Lisp must have its closing parenthesis match its opening
1276 parenthesis.  (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs
1277 Manual}, for more information about Emacs' modes.)
1279 @node Run a Program, Making Errors, Lisp Lists, List Processing
1280 @comment  node-name,  next,  previous,  up
1281 @section Run a Program
1282 @cindex Run a program
1283 @cindex Program, running one
1285 @cindex @samp{evaluate} defined
1286 A list in Lisp---any list---is a program ready to run.  If you run it
1287 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one
1288 of three things: do nothing except return to you the list itself; send
1289 you an error message; or, treat the first symbol in the list as a
1290 command to do something.  (Usually, of course, it is the last of these
1291 three things that you really want!)
1293 @c use code for the single apostrophe, not samp.
1294 The single apostrophe, @code{'}, that I put in front of some of the
1295 example lists in preceding sections is called a @dfn{quote}; when it
1296 precedes a list, it tells Lisp to do nothing with the list, other than
1297 take it as it is written.  But if there is no quote preceding a list,
1298 the first item of the list is special: it is a command for the computer
1299 to obey.  (In Lisp, these commands are called @emph{functions}.)  The list
1300 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp
1301 understands that the @code{+} is an instruction to do something with the
1302 rest of the list: add the numbers that follow.
1304 @need 1250
1305 If you are reading this inside of GNU Emacs in Info, here is how you can
1306 evaluate such a list:  place your cursor immediately after the right
1307 hand parenthesis of the following list and then type @kbd{C-x C-e}:
1309 @smallexample
1310 (+ 2 2)
1311 @end smallexample
1313 @c use code for the number four, not samp.
1314 @noindent
1315 You will see the number @code{4} appear in the echo area.  (In the
1316 jargon, what you have just done is ``evaluate the list.''  The echo area
1317 is the line at the bottom of the screen that displays or ``echoes''
1318 text.)  Now try the same thing with a quoted list:  place the cursor
1319 right after the following list and type @kbd{C-x C-e}:
1321 @smallexample
1322 '(this is a quoted list)
1323 @end smallexample
1325 @noindent
1326 You will see @code{(this is a quoted list)} appear in the echo area.
1328 @cindex Lisp interpreter, explained
1329 @cindex Interpreter, Lisp, explained
1330 In both cases, what you are doing is giving a command to the program
1331 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
1332 interpreter a command to evaluate the expression.  The name of the Lisp
1333 interpreter comes from the word for the task done by a human who comes
1334 up with the meaning of an expression---who ``interprets'' it.
1336 You can also evaluate an atom that is not part of a list---one that is
1337 not surrounded by parentheses; again, the Lisp interpreter translates
1338 from the humanly readable expression to the language of the computer.
1339 But before discussing this (@pxref{Variables}), we will discuss what the
1340 Lisp interpreter does when you make an error.
1342 @node Making Errors, Names & Definitions, Run a Program, List Processing
1343 @comment  node-name,  next,  previous,  up
1344 @section Generate an Error Message
1345 @cindex Generate an error message
1346 @cindex Error message generation
1348 Partly so you won't worry if you do it accidentally, we will now give
1349 a command to the Lisp interpreter that generates an error message.
1350 This is a harmless activity; and indeed, we will often try to generate
1351 error messages intentionally.  Once you understand the jargon, error
1352 messages can be informative.  Instead of being called ``error''
1353 messages, they should be called ``help'' messages.  They are like
1354 signposts to a traveller in a strange country; deciphering them can be
1355 hard, but once understood, they can point the way.
1357 The error message is generated by a built-in GNU Emacs debugger.  We
1358 will `enter the debugger'.  You get out of the debugger by typing @code{q}.
1360 What we will do is evaluate a list that is not quoted and does not
1361 have a meaningful command as its first element.  Here is a list almost
1362 exactly the same as the one we just used, but without the single-quote
1363 in front of it.  Position the cursor right after it and type @kbd{C-x
1364 C-e}:
1366 @smallexample
1367 (this is an unquoted list)
1368 @end smallexample
1370 @noindent
1371 What you see depends on which version of Emacs you are running.  GNU
1372 Emacs version 21 provides more information than version 20 and before.
1373 First, the more recent result of generating an error; then the
1374 earlier, version 20 result.
1376 @need 1250
1377 @noindent
1378 In GNU Emacs version 21, a @file{*Backtrace*} window will open up and
1379 you will see the following in it:
1381 @smallexample
1382 @group
1383 ---------- Buffer: *Backtrace* ----------
1384 Debugger entered--Lisp error: (void-function this)
1385   (this is an unquoted list)
1386   eval((this is an unquoted list))
1387   eval-last-sexp-1(nil)
1388   eval-last-sexp(nil)
1389   call-interactively(eval-last-sexp)
1390 ---------- Buffer: *Backtrace* ----------
1391 @end group
1392 @end smallexample
1394 @need 1200
1395 @noindent
1396 Your cursor will be in this window (you may have to wait a few seconds
1397 before it becomes visible).  To quit the debugger and make the
1398 debugger window go away, type:
1400 @smallexample
1402 @end smallexample
1404 @noindent
1405 Please type @kbd{q} right now, so you become confident that you can
1406 get out of the debugger.  Then, type @kbd{C-x C-e} again to re-enter
1409 @cindex @samp{function} defined
1410 Based on what we already know, we can almost read this error message.
1412 You read the @file{*Backtrace*} buffer from the bottom up; it tells
1413 you what Emacs did.  When you typed @kbd{C-x C-e}, you made an
1414 interactive call to the command @code{eval-last-sexp}.  @code{eval} is
1415 an abbreviation for `evaluate' and @code{sexp} is an abbreviation for
1416 `symbolic expression'.  The command means `evaluate last symbolic
1417 expression', which is the expression just before your cursor.
1419 Each line above tells you what the Lisp interpreter evaluated next.
1420 The most recent action is at the top.  The buffer is called the
1421 @file{*Backtrace*} buffer because it enables you to track Emacs
1422 backwards.
1424 @need 800
1425 At the top of the @file{*Backtrace*} buffer, you see the line:
1427 @smallexample
1428 Debugger entered--Lisp error: (void-function this)
1429 @end smallexample
1431 @noindent
1432 The Lisp interpreter tried to evaluate the first atom of the list, the
1433 word @samp{this}.  It is this action that generated the error message
1434 @samp{void-function this}.
1436 The message contains the words @samp{void-function} and @samp{this}.
1438 @cindex @samp{function} defined
1439 The word @samp{function} was mentioned once before.  It is a very
1440 important word.  For our purposes, we can define it by saying that a
1441 @dfn{function} is a set of instructions to the computer that tell the
1442 computer to do something.
1444 Now we can begin to understand the error message: @samp{void-function
1445 this}.  The function (that is, the word @samp{this}) does not have a
1446 definition of any set of instructions for the computer to carry out.
1448 The slightly odd word, @samp{void-function}, is designed to cover the
1449 way Emacs Lisp is implemented, which is that when a symbol does not
1450 have a function definition attached to it, the place that should
1451 contain the instructions is `void'.
1453 On the other hand, since we were able to add 2 plus 2 successfully, by
1454 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
1455 have a set of instructions for the computer to obey and those
1456 instructions must be to add the numbers that follow the @code{+}.
1458 @need 1250
1459 In GNU Emacs version 20, and in earlier versions, you will see only
1460 one line of error message; it will appear in the echo area and look
1461 like this:
1463 @smallexample
1464 Symbol's function definition is void:@: this
1465 @end smallexample
1467 @noindent
1468 (Also, your terminal may beep at you---some do, some don't; and others
1469 blink.  This is just a device to get your attention.)  The message goes
1470 away as soon as you type another key, even just to move the cursor.
1472 We know the meaning of the word @samp{Symbol}.  It refers to the first
1473 atom of the list, the word @samp{this}.  The word @samp{function}
1474 refers to the instructions that tell the computer what to do.
1475 (Technically, the symbol tells the computer where to find the
1476 instructions, but this is a complication we can ignore for the
1477 moment.)
1479 The error message can be understood: @samp{Symbol's function
1480 definition is void:@: this}.  The symbol (that is, the word
1481 @samp{this}) lacks instructions for the computer to carry out.
1483 @node Names & Definitions, Lisp Interpreter, Making Errors, List Processing
1484 @comment  node-name,  next,  previous,  up
1485 @section Symbol Names and Function Definitions
1486 @cindex Symbol names
1488 We can articulate another characteristic of Lisp based on what we have
1489 discussed so far---an important characteristic: a symbol, like
1490 @code{+}, is not itself the set of instructions for the computer to
1491 carry out.  Instead, the symbol is used, perhaps temporarily, as a way
1492 of locating the definition or set of instructions.  What we see is the
1493 name through which the instructions can be found.  Names of people
1494 work the same way.  I can be referred to as @samp{Bob}; however, I am
1495 not the letters @samp{B}, @samp{o}, @samp{b} but am, or were, the
1496 consciousness consistently associated with a particular life-form.
1497 The name is not me, but it can be used to refer to me.
1499 In Lisp, one set of instructions can be attached to several names.
1500 For example, the computer instructions for adding numbers can be
1501 linked to the symbol @code{plus} as well as to the symbol @code{+}
1502 (and are in some dialects of Lisp).  Among humans, I can be referred
1503 to as @samp{Robert} as well as @samp{Bob} and by other words as well.
1505 On the other hand, a symbol can have only one function definition
1506 attached to it at a time.  Otherwise, the computer would be confused as
1507 to which definition to use.  If this were the case among people, only
1508 one person in the world could be named @samp{Bob}.  However, the function
1509 definition to which the name refers can be changed readily.
1510 (@xref{Install, , Install a Function Definition}.)
1512 Since Emacs Lisp is large, it is customary to name symbols in a way
1513 that identifies the part of Emacs to which the function belongs.
1514 Thus, all the names for functions that deal with Texinfo start with
1515 @samp{texinfo-} and those for functions that deal with reading mail
1516 start with @samp{rmail-}.
1518 @node Lisp Interpreter, Evaluation, Names & Definitions, List Processing
1519 @comment  node-name,  next,  previous,  up
1520 @section The Lisp Interpreter
1521 @cindex Lisp interpreter, what it does
1522 @cindex Interpreter, what it does
1524 Based on what we have seen, we can now start to figure out what the
1525 Lisp interpreter does when we command it to evaluate a list.
1526 First, it looks to see whether there is a quote before the list; if
1527 there is, the interpreter just gives us the list.  On the other
1528 hand, if there is no quote, the interpreter looks at the first element
1529 in the list and sees whether it has a function definition.  If it does,
1530 the interpreter carries out the instructions in the function definition.
1531 Otherwise, the interpreter prints an error message.
1533 This is how Lisp works.  Simple.  There are added complications which we
1534 will get to in a minute, but these are the fundamentals.  Of course, to
1535 write Lisp programs, you need to know how to write function definitions
1536 and attach them to names, and how to do this without confusing either
1537 yourself or the computer.
1539 @menu
1540 * Complications::               Variables, Special forms, Lists within.
1541 * Byte Compiling::              Specially processing code for speed.
1542 @end menu
1544 @node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
1545 @ifnottex
1546 @unnumberedsubsec Complications
1547 @end ifnottex
1549 Now, for the first complication.  In addition to lists, the Lisp
1550 interpreter can evaluate a symbol that is not quoted and does not have
1551 parentheses around it.  The Lisp interpreter will attempt to determine
1552 the symbol's value as a @dfn{variable}.  This situation is described
1553 in the section on variables.  (@xref{Variables}.)
1555 @cindex Special form
1556 The second complication occurs because some functions are unusual and do
1557 not work in the usual manner.  Those that don't are called @dfn{special
1558 forms}.  They are used for special jobs, like defining a function, and
1559 there are not many of them.  In the next few chapters, you will be
1560 introduced to several of the more important special forms.
1562 The third and final complication is this: if the function that the
1563 Lisp interpreter is looking at is not a special form, and if it is part
1564 of a list, the Lisp interpreter looks to see whether the list has a list
1565 inside of it.  If there is an inner list, the Lisp interpreter first
1566 figures out what it should do with the inside list, and then it works on
1567 the outside list.  If there is yet another list embedded inside the
1568 inner list, it works on that one first, and so on.  It always works on
1569 the innermost list first.  The interpreter works on the innermost list
1570 first, to evaluate the result of that list.  The result may be
1571 used by the enclosing expression.
1573 Otherwise, the interpreter works left to right, from one expression to
1574 the next.
1576 @node Byte Compiling,  , Complications, Lisp Interpreter
1577 @subsection Byte Compiling
1578 @cindex Byte compiling
1580 One other aspect of interpreting: the Lisp interpreter is able to
1581 interpret two kinds of entity: humanly readable code, on which we will
1582 focus exclusively, and specially processed code, called @dfn{byte
1583 compiled} code, which is not humanly readable.  Byte compiled code
1584 runs faster than humanly readable code.
1586 You can transform humanly readable code into byte compiled code by
1587 running one of the compile commands such as @code{byte-compile-file}.
1588 Byte compiled code is usually stored in a file that ends with a
1589 @file{.elc} extension rather than a @file{.el} extension.  You will
1590 see both kinds of file in the @file{emacs/lisp} directory; the files
1591 to read are those with @file{.el} extensions.
1593 As a practical matter, for most things you might do to customize or
1594 extend Emacs, you do not need to byte compile; and I will not discuss
1595 the topic here.  @xref{Byte Compilation, , Byte Compilation, elisp,
1596 The GNU Emacs Lisp Reference Manual}, for a full description of byte
1597 compilation.
1599 @node Evaluation, Variables, Lisp Interpreter, List Processing
1600 @comment  node-name,  next,  previous,  up
1601 @section Evaluation
1602 @cindex Evaluation
1604 When the Lisp interpreter works on an expression, the term for the
1605 activity is called @dfn{evaluation}.  We say that the interpreter
1606 `evaluates the expression'.  I've used this term several times before.
1607 The word comes from its use in everyday language, `to ascertain the
1608 value or amount of; to appraise', according to @cite{Webster's New
1609 Collegiate Dictionary}.
1611 After evaluating an expression, the Lisp interpreter will most likely
1612 @dfn{return} the value that the computer produces by carrying out the
1613 instructions it found in the function definition, or perhaps it will
1614 give up on that function and produce an error message.  (The interpreter
1615 may also find itself tossed, so to speak, to a different function or it
1616 may attempt to repeat continually what it is doing for ever and ever in
1617 what is called an `infinite loop'.  These actions are less common; and
1618 we can ignore them.)  Most frequently, the interpreter returns a value.
1620 @cindex @samp{side effect} defined
1621 At the same time the interpreter returns a value, it may do something
1622 else as well, such as move a cursor or copy a file; this other kind of
1623 action is called a @dfn{side effect}.  Actions that we humans think are
1624 important, such as printing results, are often ``side effects'' to the
1625 Lisp interpreter.  The jargon can sound peculiar, but it turns out that
1626 it is fairly easy to learn to use side effects.
1628 In summary, evaluating a symbolic expression most commonly causes the
1629 Lisp interpreter to return a value and perhaps carry out a side effect;
1630 or else produce an error.
1632 @menu
1633 * Evaluating Inner Lists::      Lists within lists...
1634 @end menu
1636 @node Evaluating Inner Lists,  , Evaluation, Evaluation
1637 @comment  node-name,  next,  previous,  up
1638 @subsection Evaluating Inner Lists
1639 @cindex Inner list evaluation
1640 @cindex Evaluating inner lists
1642 If evaluation applies to a list that is inside another list, the outer
1643 list may use the value returned by the first evaluation as information
1644 when the outer list is evaluated.  This explains why inner expressions
1645 are evaluated first: the values they return are used by the outer
1646 expressions.
1648 @need 1250
1649 We can investigate this process by evaluating another addition example.
1650 Place your cursor after the following expression and type @kbd{C-x C-e}:
1652 @smallexample
1653 (+ 2 (+ 3 3))
1654 @end smallexample
1656 @noindent
1657 The number 8 will appear in the echo area.
1659 What happens is that the Lisp interpreter first evaluates the inner
1660 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it
1661 evaluates the outer expression as if it were written @code{(+ 2 6)}, which
1662 returns the value 8.  Since there are no more enclosing expressions to
1663 evaluate, the interpreter prints that value in the echo area.
1665 Now it is easy to understand the name of the command invoked by the
1666 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}.  The
1667 letters @code{sexp} are an abbreviation for `symbolic expression', and
1668 @code{eval} is an abbreviation for `evaluate'.  The command means
1669 `evaluate last symbolic expression'.
1671 As an experiment, you can try evaluating the expression by putting the
1672 cursor at the beginning of the next line immediately following the
1673 expression, or inside the expression.
1675 @need 800
1676 Here is another copy of the expression:
1678 @smallexample
1679 (+ 2 (+ 3 3))
1680 @end smallexample
1682 @noindent
1683 If you place the cursor at the beginning of the blank line that
1684 immediately follows the expression and type @kbd{C-x C-e}, you will
1685 still get the value 8 printed in the echo area.  Now try putting the
1686 cursor inside the expression.  If you put it right after the next to
1687 last parenthesis (so it appears to sit on top of the last parenthesis),
1688 you will get a 6 printed in the echo area!  This is because the command
1689 evaluates the expression @code{(+ 3 3)}.
1691 Now put the cursor immediately after a number.  Type @kbd{C-x C-e} and
1692 you will get the number itself.  In Lisp, if you evaluate a number, you
1693 get the number itself---this is how numbers differ from symbols.  If you
1694 evaluate a list starting with a symbol like @code{+}, you will get a
1695 value returned that is the result of the computer carrying out the
1696 instructions in the function definition attached to that name.  If a
1697 symbol by itself is evaluated, something different happens, as we will
1698 see in the next section.
1700 @node Variables, Arguments, Evaluation, List Processing
1701 @comment  node-name,  next,  previous,  up
1702 @section Variables
1703 @cindex Variables
1705 In Emacs Lisp, a symbol can have a value attached to it just as it can
1706 have a function definition attached to it.  The two are different.
1707 The function definition is a set of instructions that a computer will
1708 obey.  A value, on the other hand, is something, such as number or a
1709 name, that can vary (which is why such a symbol is called a variable).
1710 The value of a symbol can be any expression in Lisp, such as a symbol,
1711 number, list, or string.  A symbol that has a value is often called a
1712 @dfn{variable}.
1714 A symbol can have both a function definition and a value attached to
1715 it at the same time.  Or it can have just one or the other.
1716 The two are separate.  This is somewhat similar
1717 to the way the name Cambridge can refer to the city in Massachusetts
1718 and have some information attached to the name as well, such as
1719 ``great programming center''.
1721 @ignore
1722 (Incidentally, in Emacs Lisp, a symbol can have two
1723 other things attached to it, too: a property list and a documentation
1724 string; these are discussed later.)
1725 @end ignore
1727 Another way to think about this is to imagine a symbol as being a chest
1728 of drawers.  The function definition is put in one drawer, the value in
1729 another, and so on.  What is put in the drawer holding the value can be
1730 changed without affecting the contents of the drawer holding the
1731 function definition, and vice-versa.
1733 @menu
1734 * fill-column Example::
1735 * Void Function::               The error message for a symbol
1736                                   without a function.
1737 * Void Variable::               The error message for a symbol without a value.
1738 @end menu
1740 @node fill-column Example, Void Function, Variables, Variables
1741 @ifnottex
1742 @unnumberedsubsec @code{fill-column}, an Example Variable
1743 @end ifnottex
1745 @findex fill-column, @r{an example variable}
1746 @cindex Example variable, @code{fill-column}
1747 @cindex Variable, example of, @code{fill-column}
1748 The variable @code{fill-column} illustrates a symbol with a value
1749 attached to it: in every GNU Emacs buffer, this symbol is set to some
1750 value, usually 72 or 70, but sometimes to some other value.  To find the
1751 value of this symbol, evaluate it by itself.  If you are reading this in
1752 Info inside of GNU Emacs, you can do this by putting the cursor after
1753 the symbol and typing @kbd{C-x C-e}:
1755 @smallexample
1756 fill-column
1757 @end smallexample
1759 @noindent
1760 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo
1761 area.  This is the value for which @code{fill-column} is set for me as I
1762 write this.  It may be different for you in your Info buffer.  Notice
1763 that the value returned as a variable is printed in exactly the same way
1764 as the value returned by a function carrying out its instructions.  From
1765 the point of view of the Lisp interpreter, a value returned is a value
1766 returned.  What kind of expression it came from ceases to matter once
1767 the value is known.
1769 A symbol can have any value attached to it or, to use the jargon, we can
1770 @dfn{bind} the variable to a value: to a number, such as 72; to a
1771 string, @code{"such as this"}; to a list, such as @code{(spruce pine
1772 oak)}; we can even bind a variable to a function definition.
1774 A symbol can be bound to a value in several ways.  @xref{set & setq, ,
1775 Setting the Value of a Variable}, for information about one way to do
1776 this.
1778 @node Void Function, Void Variable, fill-column Example, Variables
1779 @comment  node-name,  next,  previous,  up
1780 @subsection Error Message for a Symbol Without a Function
1781 @cindex Symbol without function error
1782 @cindex Error for symbol without function
1784 When we evaluated @code{fill-column} to find its value as a variable,
1785 we did not place parentheses around the word.  This is because we did
1786 not intend to use it as a function name.
1788 If @code{fill-column} were the first or only element of a list, the
1789 Lisp interpreter would attempt to find the function definition
1790 attached to it.  But @code{fill-column} has no function definition.
1791 Try evaluating this:
1793 @smallexample
1794 (fill-column)
1795 @end smallexample
1797 @need 1250
1798 @noindent
1799 In GNU Emacs version 21, you will create a @file{*Backtrace*} buffer
1800 that says:
1802 @smallexample
1803 @group
1804 ---------- Buffer: *Backtrace* ----------
1805 Debugger entered--Lisp error: (void-function fill-column)
1806   (fill-column)
1807   eval((fill-column))
1808   eval-last-sexp-1(nil)
1809   eval-last-sexp(nil)
1810   call-interactively(eval-last-sexp)
1811 ---------- Buffer: *Backtrace* ----------
1812 @end group
1813 @end smallexample
1815 @noindent
1816 (Remember, to quit the debugger and make the debugger window go away,
1817 type @kbd{q} in the @file{*Backtrace*} buffer.)
1819 @need 800
1820 In GNU Emacs 20 and before, you will produce an error message that says:
1822 @smallexample
1823 Symbol's function definition is void:@: fill-column
1824 @end smallexample
1826 @noindent
1827 (The message will go away away as soon as you move the cursor or type
1828 another key.)
1830 @node Void Variable,  , Void Function, Variables
1831 @comment  node-name,  next,  previous,  up
1832 @subsection Error Message for a Symbol Without a Value
1833 @cindex Symbol without value error
1834 @cindex Error for symbol without value
1836 If you attempt to evaluate a symbol that does not have a value bound to
1837 it, you will receive an error message.  You can see this by
1838 experimenting with our 2 plus 2 addition.  In the following expression,
1839 put your cursor right after the @code{+}, before the first number 2,
1840 type @kbd{C-x C-e}:
1842 @smallexample
1843 (+ 2 2)
1844 @end smallexample
1846 @need 1500
1847 @noindent
1848 In GNU Emacs 21, you will create a @file{*Backtrace*} buffer that
1849 says:
1851 @smallexample
1852 @group
1853 ---------- Buffer: *Backtrace* ----------
1854 Debugger entered--Lisp error: (void-variable +)
1855   eval(+)
1856   eval-last-sexp-1(nil)
1857   eval-last-sexp(nil)
1858   call-interactively(eval-last-sexp)
1859 ---------- Buffer: *Backtrace* ----------
1860 @end group
1861 @end smallexample
1863 @noindent
1864 (As with the other times we entered the debugger, you can quit by
1865 typing @kbd{q} in the @file{*Backtrace*} buffer.)
1867 This backtrace is different from the very first error message we saw,
1868 which said, @samp{Debugger entered--Lisp error: (void-function this)}.
1869 In this case, the function does not have a value as a variable; while
1870 in the other error message, the function (the word `this') did not
1871 have a definition.
1873 In this experiment with the @code{+}, what we did was cause the Lisp
1874 interpreter to evaluate the @code{+} and look for the value of the
1875 variable instead of the function definition.  We did this by placing the
1876 cursor right after the symbol rather than after the parenthesis of the
1877 enclosing list as we did before.  As a consequence, the Lisp interpreter
1878 evaluated the preceding s-expression, which in this case was the
1879 @code{+} by itself.
1881 Since @code{+} does not have a value bound to it, just the function
1882 definition, the error message reported that the symbol's value as a
1883 variable was void.
1885 @need 800
1886 In GNU Emacs version 20 and before, your error message will say:
1888 @example
1889 Symbol's value as variable is void:@: +
1890 @end example
1892 @noindent
1893 The meaning is the same as in GNU Emacs 21.
1895 @node Arguments, set & setq, Variables, List Processing
1896 @comment  node-name,  next,  previous,  up
1897 @section Arguments
1898 @cindex Arguments
1899 @cindex Passing information to functions
1901 To see how information is passed to functions, let's look again at
1902 our old standby, the addition of two plus two.  In Lisp, this is written
1903 as follows:
1905 @smallexample
1906 (+ 2 2)
1907 @end smallexample
1909 If you evaluate this expression, the number 4 will appear in your echo
1910 area.  What the Lisp interpreter does is add the numbers that follow
1911 the @code{+}.
1913 @cindex @samp{argument} defined
1914 The numbers added by @code{+} are called the @dfn{arguments} of the
1915 function @code{+}.  These numbers are the information that is given to
1916 or @dfn{passed} to the function.
1918 The word `argument' comes from the way it is used in mathematics and
1919 does not refer to a disputation between two people; instead it refers to
1920 the information presented to the function, in this case, to the
1921 @code{+}.  In Lisp, the arguments to a function are the atoms or lists
1922 that follow the function.  The values returned by the evaluation of
1923 these atoms or lists are passed to the function.  Different functions
1924 require different numbers of arguments; some functions require none at
1925 all.@footnote{It is curious to track the path by which the word `argument'
1926 came to have two different meanings, one in mathematics and the other in
1927 everyday English.  According to the @cite{Oxford English Dictionary},
1928 the word derives from the Latin for @samp{to make clear, prove}; thus it
1929 came to mean, by one thread of derivation, `the evidence offered as
1930 proof', which is to say, `the information offered', which led to its
1931 meaning in Lisp.  But in the other thread of derivation, it came to mean
1932 `to assert in a manner against which others may make counter
1933 assertions', which led to the meaning of the word as a disputation.
1934 (Note here that the English word has two different definitions attached
1935 to it at the same time.  By contrast, in Emacs Lisp, a symbol cannot
1936 have two different function definitions at the same time.)}
1938 @menu
1939 * Data types::                  Types of data passed to a function.
1940 * Args as Variable or List::    An argument can be the value
1941                                   of a variable or list.
1942 * Variable Number of Arguments::  Some functions may take a
1943                                   variable number of arguments.
1944 * Wrong Type of Argument::      Passing an argument of the wrong type
1945                                   to a function.
1946 * message::                     A useful function for sending messages.
1947 @end menu
1949 @node Data types, Args as Variable or List, Arguments, Arguments
1950 @comment  node-name,  next,  previous,  up
1951 @subsection Arguments' Data Types
1952 @cindex Data types
1953 @cindex Types of data
1954 @cindex Arguments' data types
1956 The type of data that should be passed to a function depends on what
1957 kind of information it uses.  The arguments to a function such as
1958 @code{+} must have values that are numbers, since @code{+} adds numbers.
1959 Other functions use different kinds of data for their arguments.
1961 @need 1250
1962 @findex concat
1963 For example, the @code{concat} function links together or unites two or
1964 more strings of text to produce a string.  The arguments are strings.
1965 Concatenating the two character strings @code{abc}, @code{def} produces
1966 the single string @code{abcdef}.  This can be seen by evaluating the
1967 following:
1969 @smallexample
1970 (concat "abc" "def")
1971 @end smallexample
1973 @noindent
1974 The value produced by evaluating this expression is @code{"abcdef"}.
1976 A function such as @code{substring} uses both a string and numbers as
1977 arguments.  The function returns a part of the string, a substring of
1978 the first argument.  This function takes three arguments.  Its first
1979 argument is the string of characters, the second and third arguments are
1980 numbers that indicate the beginning and end of the substring.  The
1981 numbers are a count of the number of characters (including spaces and
1982 punctuations) from the beginning of the string.
1984 @need 800
1985 For example, if you evaluate the following:
1987 @smallexample
1988 (substring "The quick brown fox jumped." 16 19)
1989 @end smallexample
1991 @noindent
1992 you will see @code{"fox"} appear in the echo area.  The arguments are the
1993 string and the two numbers.
1995 Note that the string passed to @code{substring} is a single atom even
1996 though it is made up of several words separated by spaces.  Lisp counts
1997 everything between the two quotation marks as part of the string,
1998 including the spaces.  You can think of the @code{substring} function as
1999 a kind of `atom smasher' since it takes an otherwise indivisible atom
2000 and extracts a part.  However, @code{substring} is only able to extract
2001 a substring from an argument that is a string, not from another type of
2002 atom such as a number or symbol.
2004 @node Args as Variable or List, Variable Number of Arguments, Data types, Arguments
2005 @comment  node-name,  next,  previous,  up
2006 @subsection An Argument as the Value of a Variable or List
2008 An argument can be a symbol that returns a value when it is evaluated.
2009 For example, when the symbol @code{fill-column} by itself is evaluated,
2010 it returns a number.  This number can be used in an addition.
2012 @need 1250
2013 Position the cursor after the following expression and type @kbd{C-x
2014 C-e}:
2016 @smallexample
2017 (+ 2 fill-column)
2018 @end smallexample
2020 @noindent
2021 The value will be a number two more than what you get by evaluating
2022 @code{fill-column} alone.  For me, this is 74, because the value of
2023 @code{fill-column} is 72.
2025 As we have just seen, an argument can be a symbol that returns a value
2026 when evaluated.  In addition, an argument can be a list that returns a
2027 value when it is evaluated.  For example, in the following expression,
2028 the arguments to the function @code{concat} are the strings
2029 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list
2030 @code{(number-to-string (+ 2 fill-column))}.
2032 @c For Emacs 21, need number-to-string
2033 @smallexample
2034 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
2035 @end smallexample
2037 @noindent
2038 If you evaluate this expression---and if, as with my Emacs,
2039 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will
2040 appear in the echo area.  (Note that you must put spaces after the
2041 word @samp{The} and before the word @samp{red} so they will appear in
2042 the final string.  The function @code{number-to-string} converts the
2043 integer that the addition function returns to a string.
2044 @code{number-to-string} is also known as @code{int-to-string}.)
2046 @node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments
2047 @comment  node-name,  next,  previous,  up
2048 @subsection Variable Number of Arguments
2049 @cindex Variable number of arguments
2050 @cindex Arguments, variable number of
2052 Some functions, such as @code{concat}, @code{+} or @code{*}, take any
2053 number of arguments.  (The @code{*} is the symbol for multiplication.)
2054 This can be seen by evaluating each of the following expressions in
2055 the usual way.  What you will see in the echo area is printed in this
2056 text after @samp{@result{}}, which you may read as `evaluates to'.
2058 @need 1250
2059 In the first set, the functions have no arguments:
2061 @smallexample
2062 @group
2063 (+)       @result{} 0
2065 (*)       @result{} 1
2066 @end group
2067 @end smallexample
2069 @need 1250
2070 In this set, the functions have one argument each:
2072 @smallexample
2073 @group
2074 (+ 3)     @result{} 3
2076 (* 3)     @result{} 3
2077 @end group
2078 @end smallexample
2080 @need 1250
2081 In this set, the functions have three arguments each:
2083 @smallexample
2084 @group
2085 (+ 3 4 5) @result{} 12
2087 (* 3 4 5) @result{} 60
2088 @end group
2089 @end smallexample
2091 @node Wrong Type of Argument, message, Variable Number of Arguments, Arguments
2092 @comment  node-name,  next,  previous,  up
2093 @subsection Using the Wrong Type Object as an Argument
2094 @cindex Wrong type of argument
2095 @cindex Argument, wrong type of
2097 When a function is passed an argument of the wrong type, the Lisp
2098 interpreter produces an error message.  For example, the @code{+}
2099 function expects the values of its arguments to be numbers.  As an
2100 experiment we can pass it the quoted symbol @code{hello} instead of a
2101 number.  Position the cursor after the following expression and type
2102 @kbd{C-x C-e}:
2104 @smallexample
2105 (+ 2 'hello)
2106 @end smallexample
2108 @noindent
2109 When you do this you will generate an error message.  What has happened
2110 is that @code{+} has tried to add the 2 to the value returned by
2111 @code{'hello}, but the value returned by @code{'hello} is the symbol
2112 @code{hello}, not a number.  Only numbers can be added.  So @code{+}
2113 could not carry out its addition.
2115 @need 1250
2116 In GNU Emacs version 21, you will create and enter a
2117 @file{*Backtrace*} buffer that says:
2119 @noindent
2120 @smallexample
2121 @group
2122 ---------- Buffer: *Backtrace* ----------
2123 Debugger entered--Lisp error:
2124          (wrong-type-argument number-or-marker-p hello)
2125   +(2 hello)
2126   eval((+ 2 (quote hello)))
2127   eval-last-sexp-1(nil)
2128   eval-last-sexp(nil)
2129   call-interactively(eval-last-sexp)
2130 ---------- Buffer: *Backtrace* ----------
2131 @end group
2132 @end smallexample
2134 @need 1250
2135 As usual, the error message tries to be helpful and makes sense after you
2136 learn how to read it.
2138 The first part of the error message is straightforward; it says
2139 @samp{wrong type argument}.  Next comes the mysterious jargon word
2140 @w{@samp{number-or-marker-p}}.  This word is trying to tell you what
2141 kind of argument the @code{+} expected.
2143 The symbol @code{number-or-marker-p} says that the Lisp interpreter is
2144 trying to determine whether the information presented it (the value of
2145 the argument) is a number or a marker (a special object representing a
2146 buffer position).  What it does is test to see whether the @code{+} is
2147 being given numbers to add.  It also tests to see whether the
2148 argument is something called a marker, which is a specific feature of
2149 Emacs Lisp.  (In Emacs, locations in a buffer are recorded as markers.
2150 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
2151 its position is kept as a marker.  The mark can be considered a
2152 number---the number of characters the location is from the beginning
2153 of the buffer.)  In Emacs Lisp, @code{+} can be used to add the
2154 numeric value of marker positions as numbers.
2156 The @samp{p} of @code{number-or-marker-p} is the embodiment of a
2157 practice started in the early days of Lisp programming.  The @samp{p}
2158 stands for `predicate'.  In the jargon used by the early Lisp
2159 researchers, a predicate refers to a function to determine whether some
2160 property is true or false.  So the @samp{p} tells us that
2161 @code{number-or-marker-p} is the name of a function that determines
2162 whether it is true or false that the argument supplied is a number or
2163 a marker.  Other Lisp symbols that end in @samp{p} include @code{zerop},
2164 a function that tests whether its argument has the value of zero, and
2165 @code{listp}, a function that tests whether its argument is a list.
2167 Finally, the last part of the error message is the symbol @code{hello}.
2168 This is the value of the argument that was passed to @code{+}.  If the
2169 addition had been passed the correct type of object, the value passed
2170 would have been a number, such as 37, rather than a symbol like
2171 @code{hello}.  But then you would not have got the error message.
2173 @need 1250
2174 In GNU Emacs version 20 and before, the echo area displays an error
2175 message that says:
2177 @smallexample
2178 Wrong type argument:@: number-or-marker-p, hello
2179 @end smallexample
2181 This says, in different words, the same as the top line of the
2182 @file{*Backtrace*} buffer.
2184 @node message,  , Wrong Type of Argument, Arguments
2185 @comment  node-name,  next,  previous,  up
2186 @subsection The @code{message} Function
2187 @findex message
2189 Like @code{+}, the @code{message} function takes a variable number of
2190 arguments.  It is used to send messages to the user and is so useful
2191 that we will describe it here.
2193 @need 1250
2194 A message is printed in the echo area.  For example, you can print a
2195 message in your echo area by evaluating the following list:
2197 @smallexample
2198 (message "This message appears in the echo area!")
2199 @end smallexample
2201 The whole string between double quotation marks is a single argument
2202 and is printed @i{in toto}.  (Note that in this example, the message
2203 itself will appear in the echo area within double quotes; that is
2204 because you see the value returned by the @code{message} function.  In
2205 most uses of @code{message} in programs that you write, the text will
2206 be printed in the echo area as a side-effect, without the quotes.
2207 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in
2208 detail}, for an example of this.)
2210 However, if there is a @samp{%s} in the quoted string of characters, the
2211 @code{message} function does not print the @samp{%s} as such, but looks
2212 to the argument that follows the string.  It evaluates the second
2213 argument and prints the value at the location in the string where the
2214 @samp{%s} is.
2216 @need 1250
2217 You can see this by positioning the cursor after the following
2218 expression and typing @kbd{C-x C-e}:
2220 @smallexample
2221 (message "The name of this buffer is: %s." (buffer-name))
2222 @end smallexample
2224 @noindent
2225 In Info, @code{"The name of this buffer is: *info*."} will appear in the
2226 echo area.  The function @code{buffer-name} returns the name of the
2227 buffer as a string, which the @code{message} function inserts in place
2228 of @code{%s}.
2230 To print a value as an integer, use @samp{%d} in the same way as
2231 @samp{%s}.  For example, to print a message in the echo area that
2232 states the value of the @code{fill-column}, evaluate the following:
2234 @smallexample
2235 (message "The value of fill-column is %d." fill-column)
2236 @end smallexample
2238 @noindent
2239 On my system, when I evaluate this list, @code{"The value of
2240 fill-column is 72."} appears in my echo area@footnote{Actually, you
2241 can use @code{%s} to print a number.  It is non-specific.  @code{%d}
2242 prints only the part of a number left of a decimal point, and not
2243 anything that is not a number.}.
2245 If there is more than one @samp{%s} in the quoted string, the value of
2246 the first argument following the quoted string is printed at the
2247 location of the first @samp{%s} and the value of the second argument is
2248 printed at the location of the second @samp{%s}, and so on.
2250 @need 1250
2251 For example, if you evaluate the following,
2253 @smallexample
2254 @group
2255 (message "There are %d %s in the office!"
2256          (- fill-column 14) "pink elephants")
2257 @end group
2258 @end smallexample
2260 @noindent
2261 a rather whimsical message will appear in your echo area.  On my system
2262 it says, @code{"There are 58 pink elephants in the office!"}.
2264 The expression @code{(- fill-column 14)} is evaluated and the resulting
2265 number is inserted in place of the @samp{%d}; and the string in double
2266 quotes, @code{"pink elephants"}, is treated as a single argument and
2267 inserted in place of the @samp{%s}.  (That is to say, a string between
2268 double quotes evaluates to itself, like a number.)
2270 Finally, here is a somewhat complex example that not only illustrates
2271 the computation of a number, but also shows how you can use an
2272 expression within an expression to generate the text that is substituted
2273 for @samp{%s}:
2275 @smallexample
2276 @group
2277 (message "He saw %d %s"
2278          (- fill-column 32)
2279          (concat "red "
2280                  (substring
2281                   "The quick brown foxes jumped." 16 21)
2282                  " leaping."))
2283 @end group
2284 @end smallexample
2286 In this example, @code{message} has three arguments: the string,
2287 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and
2288 the expression beginning with the function @code{concat}.  The value
2289 resulting from the evaluation of @code{(- fill-column 32)} is inserted
2290 in place of the @samp{%d}; and the value returned by the expression
2291 beginning with @code{concat} is inserted in place of the @samp{%s}.
2293 When I evaluate the expression, the message @code{"He saw 38 red
2294 foxes leaping."} appears in my echo area.
2296 @node set & setq, Summary, Arguments, List Processing
2297 @comment  node-name,  next,  previous,  up
2298 @section Setting the Value of a Variable
2299 @cindex Variable, setting value
2300 @cindex Setting value of variable
2302 @cindex @samp{bind} defined
2303 There are several ways by which a variable can be given a value.  One of
2304 the ways is to use either the function @code{set} or the function
2305 @code{setq}.  Another way is to use @code{let} (@pxref{let}).  (The
2306 jargon for this process is to @dfn{bind} a variable to a value.)
2308 The following sections not only describe how @code{set} and @code{setq}
2309 work but also illustrate how arguments are passed.
2311 @menu
2312 * Using set::                   Setting values.
2313 * Using setq::                  Setting a quoted value.
2314 * Counting::                    Using @code{setq} to count.
2315 @end menu
2317 @node Using set, Using setq, set & setq, set & setq
2318 @comment  node-name,  next,  previous,  up
2319 @subsection Using @code{set}
2320 @findex set
2322 To set the value of the symbol @code{flowers} to the list @code{'(rose
2323 violet daisy buttercup)}, evaluate the following expression by
2324 positioning the cursor after the expression and typing @kbd{C-x C-e}.
2326 @smallexample
2327 (set 'flowers '(rose violet daisy buttercup))
2328 @end smallexample
2330 @noindent
2331 The list @code{(rose violet daisy buttercup)} will appear in the echo
2332 area.  This is what is @emph{returned} by the @code{set} function.  As a
2333 side effect, the symbol @code{flowers} is bound to the list ; that is,
2334 the symbol @code{flowers}, which can be viewed as a variable, is given
2335 the list as its value.  (This process, by the way, illustrates how a
2336 side effect to the Lisp interpreter, setting the value, can be the
2337 primary effect that we humans are interested in.  This is because every
2338 Lisp function must return a value if it does not get an error, but it
2339 will only have a side effect if it is designed to have one.)
2341 After evaluating the @code{set} expression, you can evaluate the symbol
2342 @code{flowers} and it will return the value you just set.  Here is the
2343 symbol.  Place your cursor after it and type @kbd{C-x C-e}.
2345 @smallexample
2346 flowers
2347 @end smallexample
2349 @noindent
2350 When you evaluate @code{flowers}, the list
2351 @code{(rose violet daisy buttercup)} appears in the echo area.
2353 Incidentally, if you evaluate @code{'flowers}, the variable with a quote
2354 in front of it, what you will see in the echo area is the symbol itself,
2355 @code{flowers}.  Here is the quoted symbol, so you can try this:
2357 @smallexample
2358 'flowers
2359 @end smallexample
2361 Note also, that when you use @code{set}, you need to quote both
2362 arguments to @code{set}, unless you want them evaluated.  Since we do
2363 not want either argument evaluated, neither the variable
2364 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
2365 are quoted.  (When you use @code{set} without quoting its first
2366 argument, the first argument is evaluated before anything else is
2367 done.  If you did this and @code{flowers} did not have a value
2368 already, you would get an error message that the @samp{Symbol's value
2369 as variable is void}; on the other hand, if @code{flowers} did return
2370 a value after it was evaluated, the @code{set} would attempt to set
2371 the value that was returned.  There are situations where this is the
2372 right thing for the function to do; but such situations are rare.)
2374 @node Using setq, Counting, Using set, set & setq
2375 @comment  node-name,  next,  previous,  up
2376 @subsection Using @code{setq}
2377 @findex setq
2379 As a practical matter, you almost always quote the first argument to
2380 @code{set}.  The combination of @code{set} and a quoted first argument
2381 is so common that it has its own name: the special form @code{setq}.
2382 This special form is just like @code{set} except that the first argument
2383 is quoted automatically, so you don't need to type the quote mark
2384 yourself.  Also, as an added convenience, @code{setq} permits you to set
2385 several different variables to different values, all in one expression.
2387 To set the value of the variable @code{carnivores} to the list
2388 @code{'(lion tiger leopard)} using @code{setq}, the following expression
2389 is used:
2391 @smallexample
2392 (setq carnivores '(lion tiger leopard))
2393 @end smallexample
2395 @noindent
2396 This is exactly the same as using @code{set} except the first argument
2397 is automatically quoted by @code{setq}.  (The @samp{q} in @code{setq}
2398 means @code{quote}.)
2400 @need 1250
2401 With @code{set}, the expression would look like this:
2403 @smallexample
2404 (set 'carnivores '(lion tiger leopard))
2405 @end smallexample
2407 Also, @code{setq} can be used to assign different values to
2408 different variables.  The first argument is bound to the value
2409 of the second argument, the third argument is bound to the value of the
2410 fourth argument, and so on.  For example, you could use the following to
2411 assign a list of trees to the symbol @code{trees} and a list of herbivores
2412 to the symbol @code{herbivores}:
2414 @smallexample
2415 @group
2416 (setq trees '(pine fir oak maple)
2417       herbivores '(gazelle antelope zebra))
2418 @end group
2419 @end smallexample
2421 @noindent
2422 (The expression could just as well have been on one line, but it might
2423 not have fit on a page; and humans find it easier to read nicely
2424 formatted lists.)
2426 Although I have been using the term `assign', there is another way of
2427 thinking about the workings of @code{set} and @code{setq}; and that is to
2428 say that @code{set} and @code{setq} make the symbol @emph{point} to the
2429 list.  This latter way of thinking is very common and in forthcoming
2430 chapters we shall come upon at least one symbol that has `pointer' as
2431 part of its name.  The name is chosen because the symbol has a value,
2432 specifically a list, attached to it; or, expressed another way,
2433 the symbol is set to ``point'' to the list.
2435 @node Counting,  , Using setq, set & setq
2436 @comment  node-name,  next,  previous,  up
2437 @subsection Counting
2438 @cindex Counting
2440 Here is an example that shows how to use @code{setq} in a counter.  You
2441 might use this to count how many times a part of your program repeats
2442 itself.  First set a variable to zero; then add one to the number each
2443 time the program repeats itself.  To do this, you need a variable that
2444 serves as a counter, and two expressions: an initial @code{setq}
2445 expression that sets the counter variable to zero; and a second
2446 @code{setq} expression that increments the counter each time it is
2447 evaluated.
2449 @smallexample
2450 @group
2451 (setq counter 0)                ; @r{Let's call this the initializer.}
2453 (setq counter (+ counter 1))    ; @r{This is the incrementer.}
2455 counter                         ; @r{This is the counter.}
2456 @end group
2457 @end smallexample
2459 @noindent
2460 (The text following the @samp{;} are comments.  @xref{Change a
2461 defun, , Change a Function Definition}.)
2463 If you evaluate the first of these expressions, the initializer,
2464 @code{(setq counter 0)}, and then evaluate the third expression,
2465 @code{counter}, the number @code{0} will appear in the echo area.  If
2466 you then evaluate the second expression, the incrementer, @code{(setq
2467 counter (+ counter 1))}, the counter will get the value 1.  So if you
2468 again evaluate @code{counter}, the number @code{1} will appear in the
2469 echo area.  Each time you evaluate the second expression, the value of
2470 the counter will be incremented.
2472 When you evaluate the incrementer, @code{(setq counter (+ counter 1))},
2473 the Lisp interpreter first evaluates the innermost list; this is the
2474 addition.  In order to evaluate this list, it must evaluate the variable
2475 @code{counter} and the number @code{1}.  When it evaluates the variable
2476 @code{counter}, it receives its current value.  It passes this value and
2477 the number @code{1} to the @code{+} which adds them together.  The sum
2478 is then returned as the value of the inner list and passed to the
2479 @code{setq} which sets the variable @code{counter} to this new value.
2480 Thus, the value of the variable, @code{counter}, is changed.
2482 @node Summary, Error Message Exercises, set & setq, List Processing
2483 @comment  node-name,  next,  previous,  up
2484 @section Summary
2486 Learning Lisp is like climbing a hill in which the first part is the
2487 steepest.  You have now climbed the most difficult part; what remains
2488 becomes easier as you progress onwards.
2490 @need 1000
2491 In summary,
2493 @itemize @bullet
2495 @item
2496 Lisp programs are made up of expressions, which are lists or single atoms.
2498 @item
2499 Lists are made up of zero or more atoms or inner lists, separated by whitespace and
2500 surrounded by parentheses.  A list can be empty.
2502 @item
2503 Atoms are multi-character symbols, like @code{forward-paragraph}, single
2504 character symbols like @code{+}, strings of characters between double
2505 quotation marks, or numbers.
2507 @item
2508 A number evaluates to itself.
2510 @item
2511 A string between double quotes also evaluates to itself.
2513 @item
2514 When you evaluate a symbol by itself, its value is returned.
2516 @item
2517 When you evaluate a list, the Lisp interpreter looks at the first symbol
2518 in the list and then at the function definition bound to that symbol.
2519 Then the instructions in the function definition are carried out.
2521 @item
2522 A single-quote, @code{'}, tells the Lisp interpreter that it should
2523 return the following expression as written, and not evaluate it as it
2524 would if the quote were not there.
2526 @item
2527 Arguments are the information passed to a function.  The arguments to a
2528 function are computed by evaluating the rest of the elements of the list
2529 of which the function is the first element.
2531 @item
2532 A function always returns a value when it is evaluated (unless it gets
2533 an error); in addition, it may also carry out some action called a
2534 ``side effect''.  In many cases, a function's primary purpose is to
2535 create a side effect.
2536 @end itemize
2538 @node Error Message Exercises,  , Summary, List Processing
2539 @comment  node-name,  next,  previous,  up
2540 @section Exercises
2542 A few simple exercises:
2544 @itemize @bullet
2545 @item
2546 Generate an error message by evaluating an appropriate symbol that is
2547 not within parentheses.
2549 @item
2550 Generate an error message by evaluating an appropriate symbol that is
2551 between parentheses.
2553 @item
2554 Create a counter that increments by two rather than one.
2556 @item
2557 Write an expression that prints a message in the echo area when
2558 evaluated.
2559 @end itemize
2561 @node Practicing Evaluation, Writing Defuns, List Processing, Top
2562 @comment  node-name,  next,  previous,  up
2563 @chapter Practicing Evaluation
2564 @cindex Practicing evaluation
2565 @cindex Evaluation practice
2567 Before learning how to write a function definition in Emacs Lisp, it is
2568 useful to spend a little time evaluating various expressions that have
2569 already been written.  These expressions will be lists with the
2570 functions as their first (and often only) element.  Since some of the
2571 functions associated with buffers are both simple and interesting, we
2572 will start with those.  In this section, we will evaluate a few of
2573 these.  In another section, we will study the code of several other
2574 buffer-related functions, to see how they were written.
2576 @menu
2577 * How to Evaluate::             Typing editing commands or @kbd{C-x C-e}
2578                                   causes evaluation.
2579 * Buffer Names::                Buffers and files are different.
2580 * Getting Buffers::             Getting a buffer itself, not merely its name.
2581 * Switching Buffers::           How to change to another buffer.
2582 * Buffer Size & Locations::     Where point is located and the size of
2583                                 the buffer.
2584 * Evaluation Exercise::
2585 @end menu
2587 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
2588 @ifnottex
2589 @unnumberedsec How to Evaluate
2590 @end ifnottex
2592 @i{Whenever you give an editing command} to Emacs Lisp, such as the
2593 command to move the cursor or to scroll the screen, @i{you are evaluating
2594 an expression,} the first element of which is a function.  @i{This is
2595 how Emacs works.}
2597 @cindex @samp{interactive function} defined
2598 @cindex @samp{command} defined
2599 When you type keys, you cause the Lisp interpreter to evaluate an
2600 expression and that is how you get your results.  Even typing plain text
2601 involves evaluating an Emacs Lisp function, in this case, one that uses
2602 @code{self-insert-command}, which simply inserts the character you
2603 typed.  The functions you evaluate by typing keystrokes are called
2604 @dfn{interactive} functions, or @dfn{commands}; how you make a function
2605 interactive will be illustrated in the chapter on how to write function
2606 definitions.  @xref{Interactive, , Making a Function Interactive}.
2608 In addition to typing keyboard commands, we have seen a second way to
2609 evaluate an expression: by positioning the cursor after a list and
2610 typing @kbd{C-x C-e}.  This is what we will do in the rest of this
2611 section.  There are other ways to evaluate an expression as well; these
2612 will be described as we come to them.
2614 Besides being used for practicing evaluation, the functions shown in the
2615 next few sections are important in their own right.  A study of these
2616 functions makes clear the distinction between buffers and files, how to
2617 switch to a buffer, and how to determine a location within it.
2619 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation
2620 @comment  node-name,  next,  previous,  up
2621 @section Buffer Names
2622 @findex buffer-name
2623 @findex buffer-file-name
2625 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
2626 the difference between a file and a buffer.  When you evaluate the
2627 following expression, @code{(buffer-name)}, the name of the buffer
2628 appears in the echo area.  When you evaluate @code{(buffer-file-name)},
2629 the name of the file to which the buffer refers appears in the echo
2630 area.  Usually, the name returned by @code{(buffer-name)} is the same as
2631 the name of the file to which it refers, and the name returned by
2632 @code{(buffer-file-name)} is the full path-name of the file.
2634 A file and a buffer are two different entities.  A file is information
2635 recorded permanently in the computer (unless you delete it).  A buffer,
2636 on the other hand, is information inside of Emacs that will vanish at
2637 the end of the editing session (or when you kill the buffer).  Usually,
2638 a buffer contains information that you have copied from a file; we say
2639 the buffer is @dfn{visiting} that file.  This copy is what you work on
2640 and modify.  Changes to the buffer do not change the file, until you
2641 save the buffer.  When you save the buffer, the buffer is copied to the file
2642 and is thus saved permanently.
2644 @need 1250
2645 If you are reading this in Info inside of GNU Emacs, you can evaluate
2646 each of the following expressions by positioning the cursor after it and
2647 typing @kbd{C-x C-e}.
2649 @smallexample
2650 @group
2651 (buffer-name)
2653 (buffer-file-name)
2654 @end group
2655 @end smallexample
2657 @noindent
2658 When I do this, @file{"introduction.texinfo"} is the value returned by
2659 evaluating @code{(buffer-name)}, and
2660 @file{"/gnu/work/intro/introduction.texinfo"} is the value returned by
2661 evaluating @code{(buffer-file-name)}.  The former is the name of the
2662 buffer and the latter is the name of the file.  (In the expressions, the
2663 parentheses tell the Lisp interpreter to treat @code{buffer-name} and
2664 @code{buffer-file-name} as functions; without the parentheses, the
2665 interpreter would attempt to evaluate the symbols as variables.
2666 @xref{Variables}.)
2668 In spite of the distinction between files and buffers, you will often
2669 find that people refer to a file when they mean a buffer and vice-versa.
2670 Indeed, most people say, ``I am editing a file,'' rather than saying,
2671 ``I am editing a buffer which I will soon save to a file.''  It is
2672 almost always clear from context what people mean.  When dealing with
2673 computer programs, however, it is important to keep the distinction in mind,
2674 since the computer is not as smart as a person.
2676 @cindex Buffer, history of word
2677 The word `buffer', by the way, comes from the meaning of the word as a
2678 cushion that deadens the force of a collision.  In early computers, a
2679 buffer cushioned the interaction between files and the computer's
2680 central processing unit.  The drums or tapes that held a file and the
2681 central processing unit were pieces of equipment that were very
2682 different from each other, working at their own speeds, in spurts.  The
2683 buffer made it possible for them to work together effectively.
2684 Eventually, the buffer grew from being an intermediary, a temporary
2685 holding place, to being the place where work is done.  This
2686 transformation is rather like that of a small seaport that grew into a
2687 great city: once it was merely the place where cargo was warehoused
2688 temporarily before being loaded onto ships; then it became a business
2689 and cultural center in its own right.
2691 Not all buffers are associated with files.  For example, when you start
2692 an Emacs session by typing the command @code{emacs} alone, without
2693 naming any files, Emacs will start with the @file{*scratch*} buffer on
2694 the screen.  This buffer is not visiting any file.  Similarly, a
2695 @file{*Help*} buffer is not associated with any file.
2697 @cindex @code{nil}, history of word
2698 If you switch to the @file{*scratch*} buffer, type @code{(buffer-name)},
2699 position the cursor after it, and type @kbd{C-x C-e} to evaluate the
2700 expression, the name @code{"*scratch*"} is returned and will appear in
2701 the echo area.  @code{"*scratch*"} is the name of the buffer.  However,
2702 if you type @code{(buffer-file-name)} in the @file{*scratch*} buffer and
2703 evaluate that, @code{nil} will appear in the echo area.  @code{nil} is
2704 from the Latin word for `nothing'; in this case, it means that the
2705 @file{*scratch*} buffer is not associated with any file.  (In Lisp,
2706 @code{nil} is also used to mean `false' and is a synonym for the empty
2707 list, @code{()}.)
2709 Incidentally, if you are in the @file{*scratch*} buffer and want the
2710 value returned by an expression to appear in the @file{*scratch*}
2711 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
2712 instead of @kbd{C-x C-e}.  This causes the value returned to appear
2713 after the expression.  The buffer will look like this:
2715 @smallexample
2716 (buffer-name)"*scratch*"
2717 @end smallexample
2719 @noindent
2720 You cannot do this in Info since Info is read-only and it will not allow
2721 you to change the contents of the buffer.  But you can do this in any
2722 buffer you can edit; and when you write code or documentation (such as
2723 this book), this feature is very useful.
2725 @node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation
2726 @comment  node-name,  next,  previous,  up
2727 @section Getting Buffers
2728 @findex current-buffer
2729 @findex other-buffer
2730 @cindex Getting a buffer
2732 The @code{buffer-name} function returns the @emph{name} of the buffer;
2733 to get the buffer @emph{itself}, a different function is needed: the
2734 @code{current-buffer} function.  If you use this function in code, what
2735 you get is the buffer itself.
2737 A name and the object or entity to which the name refers are different
2738 from each other.  You are not your name.  You are a person to whom
2739 others refer by name.  If you ask to speak to George and someone hands you
2740 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
2741 @samp{g}, and @samp{e} written on it, you might be amused, but you would
2742 not be satisfied.  You do not want to speak to the name, but to the
2743 person to whom the name refers.  A buffer is similar: the name of the
2744 scratch buffer is @file{*scratch*}, but the name is not the buffer.  To
2745 get a buffer itself, you need to use a function such as
2746 @code{current-buffer}.
2748 However, there is a slight complication: if you evaluate
2749 @code{current-buffer} in an expression on its own, as we will do here,
2750 what you see is a printed representation of the name of the buffer
2751 without the contents of the buffer.  Emacs works this way for two
2752 reasons: the buffer may be thousands of lines long---too long to be
2753 conveniently displayed; and, another buffer may have the same contents
2754 but a different name, and it is important to distinguish between them.
2756 @need 800
2757 Here is an expression containing the function:
2759 @smallexample
2760 (current-buffer)
2761 @end smallexample
2763 @noindent
2764 If you evaluate the expression in the usual way, @file{#<buffer *info*>}
2765 appears in the echo area.  The special format indicates that the
2766 buffer itself is being returned, rather than just its name.
2768 Incidentally, while you can type a number or symbol into a program, you
2769 cannot do that with the printed representation of a buffer: the only way
2770 to get a buffer itself is with a function such as @code{current-buffer}.
2772 A related function is @code{other-buffer}.  This returns the most
2773 recently selected buffer other than the one you are in currently.  If
2774 you have recently switched back and forth from the @file{*scratch*}
2775 buffer, @code{other-buffer} will return that buffer.
2777 @need 800
2778 You can see this by evaluating the expression:
2780 @smallexample
2781 (other-buffer)
2782 @end smallexample
2784 @noindent
2785 You should see @file{#<buffer *scratch*>} appear in the echo area, or
2786 the name of whatever other buffer you switched back from most
2787 recently@footnote{Actually, by default, if the buffer from which you
2788 just switched is visible to you in another window, @code{other-buffer}
2789 will choose the most recent buffer that you cannot see; this is a
2790 subtlety that I often forget.}.
2792 @node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation
2793 @comment  node-name,  next,  previous,  up
2794 @section Switching Buffers
2795 @findex switch-to-buffer
2796 @findex set-buffer
2797 @cindex Switching to a buffer
2799 The @code{other-buffer} function actually provides a buffer when it is
2800 used as an argument to a function that requires one.  We can see this
2801 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
2802 different buffer.
2804 But first, a brief introduction to the @code{switch-to-buffer}
2805 function.  When you switched back and forth from Info to the
2806 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
2807 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
2808 rather, to save typing, you probably typed just part of the name, such
2809 as @code{*sc}, and then pressed your @kbd{TAB} key to cause it to
2810 expand to the full name; and then typed your @kbd{RET} key.} when
2811 prompted in the minibuffer for the name of the buffer to which you
2812 wanted to switch.  The keystrokes, @kbd{C-x b}, cause the Lisp
2813 interpreter to evaluate the interactive function
2814 @code{switch-to-buffer}.  As we said before, this is how Emacs works:
2815 different keystrokes call or run different functions.  For example,
2816 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
2817 @code{forward-sentence}, and so on.
2819 By writing @code{switch-to-buffer} in an expression, and giving it a
2820 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
2821 does.
2823 @need 1000
2824 Here is the Lisp expression:
2826 @smallexample
2827 (switch-to-buffer (other-buffer))
2828 @end smallexample
2830 @noindent
2831 The symbol @code{switch-to-buffer} is the first element of the list,
2832 so the Lisp interpreter will treat it as a function and carry out the
2833 instructions that are attached to it.  But before doing that, the
2834 interpreter will note that @code{other-buffer} is inside parentheses
2835 and work on that symbol first.  @code{other-buffer} is the first (and
2836 in this case, the only) element of this list, so the Lisp interpreter
2837 calls or runs the function.  It returns another buffer.  Next, the
2838 interpreter runs @code{switch-to-buffer}, passing to it, as an
2839 argument, the other buffer, which is what Emacs will switch to.  If
2840 you are reading this in Info, try this now.  Evaluate the expression.
2841 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
2842 expression will move you to your most recent other buffer that you
2843 cannot see.  If you really want to go to your most recently selected
2844 buffer, even if you can still see it, you need to evaluate the
2845 following more complex expression:
2847 @smallexample
2848 (switch-to-buffer (other-buffer (current-buffer) t))
2849 @end smallexample
2851 @c noindent
2852 In this case, the first argument to @code{other-buffer} tells it which
2853 buffer to skip---the current one---and the second argument tells
2854 @code{other-buffer} it is OK to switch to a visible buffer.
2855 In regular use, @code{switch-to-buffer} takes you to an invisible
2856 window since you would most likely use @kbd{C-x o} (@code{other-window})
2857 to go to another visible buffer.}
2859 In the programming examples in later sections of this document, you will
2860 see the function @code{set-buffer} more often than
2861 @code{switch-to-buffer}.  This is because of a difference between
2862 computer programs and humans: humans have eyes and expect to see the
2863 buffer on which they are working on their computer terminals.  This is
2864 so obvious, it almost goes without saying.  However, programs do not
2865 have eyes.  When a computer program works on a buffer, that buffer does
2866 not need to be visible on the screen.
2868 @code{switch-to-buffer} is designed for humans and does two different
2869 things: it switches the buffer to which Emacs' attention is directed; and
2870 it switches the buffer displayed in the window to the new buffer.
2871 @code{set-buffer}, on the other hand, does only one thing: it switches
2872 the attention of the computer program to a different buffer.  The buffer
2873 on the screen remains unchanged (of course, normally nothing happens
2874 there until the command finishes running).
2876 @cindex @samp{call} defined
2877 Also, we have just introduced another jargon term, the word @dfn{call}.
2878 When you evaluate a list in which the first symbol is a function, you
2879 are calling that function.  The use of the term comes from the notion of
2880 the function as an entity that can do something for you if you `call'
2881 it---just as a plumber is an entity who can fix a leak if you call him
2882 or her.
2884 @node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation
2885 @comment  node-name,  next,  previous,  up
2886 @section Buffer Size and the Location of Point
2887 @cindex Size of buffer
2888 @cindex Buffer size
2889 @cindex Point location
2890 @cindex Location of point
2892 Finally, let's look at several rather simple functions,
2893 @code{buffer-size}, @code{point}, @code{point-min}, and
2894 @code{point-max}.  These give information about the size of a buffer and
2895 the location of point within it.
2897 The function @code{buffer-size} tells you the size of the current
2898 buffer; that is, the function returns a count of the number of
2899 characters in the buffer.
2901 @smallexample
2902 (buffer-size)
2903 @end smallexample
2905 @noindent
2906 You can evaluate this in the usual way, by positioning the
2907 cursor after the expression and typing @kbd{C-x C-e}.
2909 @cindex @samp{point} defined
2910 In Emacs, the current  position of the cursor is called @dfn{point}.
2911 The expression @code{(point)} returns a number that tells you where the
2912 cursor is located as a count of the number of characters from the
2913 beginning of the buffer up to point.
2915 @need 1250
2916 You can see the character count for point in this buffer by evaluating
2917 the following expression in the usual way:
2919 @smallexample
2920 (point)
2921 @end smallexample
2923 @noindent
2924 As I write this, the value of @code{point} is 65724.  The @code{point}
2925 function is frequently used in some of the examples later in this
2926 book.
2928 @need 1250
2929 The value of point depends, of course, on its location within the
2930 buffer.  If you evaluate point in this spot, the number will be larger:
2932 @smallexample
2933 (point)
2934 @end smallexample
2936 @noindent
2937 For me, the value of point in this location is 66043, which means that
2938 there are 319 characters (including spaces) between the two expressions.
2940 @cindex @samp{narrowing} defined
2941 The function @code{point-min} is somewhat similar to @code{point}, but
2942 it returns the value of the minimum permissible value of point in the
2943 current buffer.  This is the number 1 unless @dfn{narrowing} is in
2944 effect.  (Narrowing is a mechanism whereby you can restrict yourself,
2945 or a program, to operations on just a part of a buffer.
2946 @xref{Narrowing & Widening, , Narrowing and Widening}.)  Likewise, the
2947 function @code{point-max} returns the value of the maximum permissible
2948 value of point in the current buffer.
2950 @node Evaluation Exercise,  , Buffer Size & Locations, Practicing Evaluation
2951 @section Exercise
2953 Find a file with which you are working and move towards its middle.
2954 Find its buffer name, file name, length, and your position in the file.
2956 @node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top
2957 @comment  node-name,  next,  previous,  up
2958 @chapter How To Write Function Definitions
2959 @cindex Definition writing
2960 @cindex Function definition writing
2961 @cindex Writing a function definition
2963 When the Lisp interpreter evaluates a list, it looks to see whether the
2964 first symbol on the list has a function definition attached to it; or,
2965 put another way, whether the symbol points to a function definition.  If
2966 it does, the computer carries out the instructions in the definition.  A
2967 symbol that has a function definition is called, simply, a function
2968 (although, properly speaking, the definition is the function and the
2969 symbol refers to it.)
2971 @menu
2972 * Primitive Functions::
2973 * defun::                       The @code{defun} special form.
2974 * Install::                     Install a function definition.
2975 * Interactive::                 Making a function interactive.
2976 * Interactive Options::         Different options for @code{interactive}.
2977 * Permanent Installation::      Installing code permanently.
2978 * let::                         Creating and initializing local variables.
2979 * if::                          What if?
2980 * else::                        If--then--else expressions.
2981 * Truth & Falsehood::           What Lisp considers false and true.
2982 * save-excursion::              Keeping track of point, mark, and buffer.
2983 * Review::
2984 * defun Exercises::
2985 @end menu
2987 @node Primitive Functions, defun, Writing Defuns, Writing Defuns
2988 @ifnottex
2989 @unnumberedsec An Aside about Primitive Functions
2990 @end ifnottex
2991 @cindex Primitive functions
2992 @cindex Functions, primitive
2994 @cindex C language primitives
2995 @cindex Primitives written in C
2996 All functions are defined in terms of other functions, except for a few
2997 @dfn{primitive} functions that are written in the C programming
2998 language.  When you write functions' definitions, you will write them in
2999 Emacs Lisp and use other functions as your building blocks.  Some of the
3000 functions you will use will themselves be written in Emacs Lisp (perhaps
3001 by you) and some will be primitives written in C.  The primitive
3002 functions are used exactly like those written in Emacs Lisp and behave
3003 like them.  They are written in C so we can easily run GNU Emacs on any
3004 computer that has sufficient power and can run C.
3006 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
3007 distinguish between the use of functions written in C and the use of
3008 functions written in Emacs Lisp.  The difference is irrelevant.  I
3009 mention the distinction only because it is interesting to know.  Indeed,
3010 unless you investigate, you won't know whether an already-written
3011 function is written in Emacs Lisp or C.
3013 @node defun, Install, Primitive Functions, Writing Defuns
3014 @comment  node-name,  next,  previous,  up
3015 @section The @code{defun} Special Form
3016 @findex defun
3017 @cindex Special form of @code{defun}
3019 @cindex @samp{function definition} defined
3020 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
3021 it that tells the computer what to do when the function is called.
3022 This code is called the @dfn{function definition} and is created by
3023 evaluating a Lisp expression that starts with the symbol @code{defun}
3024 (which is an abbreviation for @emph{define function}).  Because
3025 @code{defun} does not evaluate its arguments in the usual way, it is
3026 called a @dfn{special form}.
3028 In subsequent sections, we will look at function definitions from the
3029 Emacs source code, such as @code{mark-whole-buffer}.  In this section,
3030 we will describe a simple function definition so you can see how it
3031 looks.  This function definition uses arithmetic because it makes for a
3032 simple example.  Some people dislike examples using arithmetic; however,
3033 if you are such a person, do not despair.  Hardly any of the code we
3034 will study in the remainder of this introduction involves arithmetic or
3035 mathematics.  The examples mostly involve text in one way or another.
3037 A function definition has up to five parts following the word
3038 @code{defun}:
3040 @enumerate
3041 @item
3042 The name of the symbol to which the function definition should be
3043 attached.
3045 @item
3046 A list of the arguments that will be passed to the function.  If no
3047 arguments will be passed to the function, this is an empty list,
3048 @code{()}.
3050 @item
3051 Documentation describing the function.  (Technically optional, but
3052 strongly recommended.)
3054 @item
3055 Optionally, an expression to make the function interactive so you can
3056 use it by typing @kbd{M-x} and then the name of the function; or by
3057 typing an appropriate key or keychord.
3059 @cindex @samp{body} defined
3060 @item
3061 The code that instructs the computer what to do: the @dfn{body} of the
3062 function definition.
3063 @end enumerate
3065 It is helpful to think of the five parts of a function definition as
3066 being organized in a template, with slots for each part:
3068 @smallexample
3069 @group
3070 (defun @var{function-name} (@var{arguments}@dots{})
3071   "@var{optional-documentation}@dots{}"
3072   (interactive @var{argument-passing-info})     ; @r{optional}
3073   @var{body}@dots{})
3074 @end group
3075 @end smallexample
3077 As an example, here is the code for a function that multiplies its
3078 argument by 7.  (This example is not interactive.  @xref{Interactive,
3079 , Making a Function Interactive}, for that information.)
3081 @smallexample
3082 @group
3083 (defun multiply-by-seven (number)
3084   "Multiply NUMBER by seven."
3085   (* 7 number))
3086 @end group
3087 @end smallexample
3089 This definition begins with a parenthesis and the symbol @code{defun},
3090 followed by the name of the function.
3092 @cindex @samp{argument list} defined
3093 The name of the function is followed by a list that contains the
3094 arguments that will be passed to the function.  This list is called
3095 the @dfn{argument list}.  In this example, the list has only one
3096 element, the symbol, @code{number}.  When the function is used, the
3097 symbol will be bound to the value that is used as the argument to the
3098 function.
3100 Instead of choosing the word @code{number} for the name of the argument,
3101 I could have picked any other name.  For example, I could have chosen
3102 the word @code{multiplicand}.  I picked the word `number' because it
3103 tells what kind of value is intended for this slot; but I could just as
3104 well have chosen the word `multiplicand' to indicate the role that the
3105 value placed in this slot will play in the workings of the function.  I
3106 could have called it @code{foogle}, but that would have been a bad
3107 choice because it would not tell humans what it means.  The choice of
3108 name is up to the programmer and should be chosen to make the meaning of
3109 the function clear.
3111 Indeed, you can choose any name you wish for a symbol in an argument
3112 list, even the name of a symbol used in some other function: the name
3113 you use in an argument list is private to that particular definition.
3114 In that definition, the name refers to a different entity than any use
3115 of the same name outside the function definition.  Suppose you have a
3116 nick-name `Shorty' in your family; when your family members refer to
3117 `Shorty', they mean you.  But outside your family, in a movie, for
3118 example, the name `Shorty' refers to someone else.  Because a name in an
3119 argument list is private to the function definition, you can change the
3120 value of such a symbol inside the body of a function without changing
3121 its value outside the function.  The effect is similar to that produced
3122 by a @code{let} expression.  (@xref{let, , @code{let}}.)
3124 @ignore
3125 Note also that we discuss the word `number' in two different ways: as a
3126 symbol that appears in the code, and as the name of something that will
3127 be replaced by a something else during the evaluation of the function.
3128 In the first case, @code{number} is a symbol, not a number; it happens
3129 that within the function, it is a variable who value is the number in
3130 question, but our primary interest in it is as a symbol.  On the other
3131 hand, when we are talking about the function, our interest is that we
3132 will substitute a number for the word @var{number}.  To keep this
3133 distinction clear, we use different typography for the two
3134 circumstances.  When we talk about this function, or about how it works,
3135 we refer to this number by writing @var{number}.  In the function
3136 itself, we refer to it by writing @code{number}.
3137 @end ignore
3139 The argument list is followed by the documentation string that
3140 describes the function.  This is what you see when you type
3141 @w{@kbd{C-h f}} and the name of a function.  Incidentally, when you
3142 write a documentation string like this, you should make the first line
3143 a complete sentence since some commands, such as @code{apropos}, print
3144 only the first line of a multi-line documentation string.  Also, you
3145 should not indent the second line of a documentation string, if you
3146 have one, because that looks odd when you use @kbd{C-h f}
3147 (@code{describe-function}).  The documentation string is optional, but
3148 it is so useful, it should be included in almost every function you
3149 write.
3151 @findex * @r{(multiplication)}
3152 The third line of the example consists of the body of the function
3153 definition.  (Most functions' definitions, of course, are longer than
3154 this.)  In this function, the body is the list, @code{(* 7 number)}, which
3155 says to multiply the value of @var{number} by 7.  (In Emacs Lisp,
3156 @code{*} is the function for multiplication, just as @code{+} is the
3157 function for addition.)
3159 When you use the @code{multiply-by-seven} function, the argument
3160 @code{number} evaluates to the actual number you want used.  Here is an
3161 example that shows how @code{multiply-by-seven} is used; but don't try
3162 to evaluate this yet!
3164 @smallexample
3165 (multiply-by-seven 3)
3166 @end smallexample
3168 @noindent
3169 The symbol @code{number}, specified in the function definition in the
3170 next section, is given or ``bound to'' the value 3 in the actual use of
3171 the function.  Note that although @code{number} was inside parentheses
3172 in the function definition, the argument passed to the
3173 @code{multiply-by-seven} function is not in parentheses.  The
3174 parentheses are written in the function definition so the computer can
3175 figure out where the argument list ends and the rest of the function
3176 definition begins.
3178 If you evaluate this example, you are likely to get an error message.
3179 (Go ahead, try it!)  This is because we have written the function
3180 definition, but not yet told the computer about the definition---we have
3181 not yet installed (or `loaded') the function definition in Emacs.
3182 Installing a function is the process that tells the Lisp interpreter the
3183 definition of the function.  Installation is described in the next
3184 section.
3186 @node Install, Interactive, defun, Writing Defuns
3187 @comment  node-name,  next,  previous,  up
3188 @section Install a Function Definition
3189 @cindex Install a Function Definition
3190 @cindex Definition installation
3191 @cindex Function definition installation
3193 If you are reading this inside of Info in Emacs, you can try out the
3194 @code{multiply-by-seven} function by first evaluating the function
3195 definition and then evaluating @code{(multiply-by-seven 3)}.  A copy of
3196 the function definition follows.  Place the cursor after the last
3197 parenthesis of the function definition and type @kbd{C-x C-e}.  When you
3198 do this, @code{multiply-by-seven} will appear in the echo area.  (What
3199 this means is that when a function definition is evaluated, the value it
3200 returns is the name of the defined function.)  At the same time, this
3201 action installs the function definition.
3203 @smallexample
3204 @group
3205 (defun multiply-by-seven (number)
3206   "Multiply NUMBER by seven."
3207   (* 7 number))
3208 @end group
3209 @end smallexample
3211 @noindent
3212 By evaluating this @code{defun}, you have just installed
3213 @code{multiply-by-seven} in Emacs.  The function is now just as much a
3214 part of Emacs as @code{forward-word} or any other editing function you
3215 use.  (@code{multiply-by-seven} will stay installed until you quit
3216 Emacs.  To reload code automatically whenever you start Emacs, see
3217 @ref{Permanent Installation, , Installing Code Permanently}.)
3220 @menu
3221 * Effect of installation::
3222 * Change a defun::              How to change a function definition.
3223 @end menu
3225 @node Effect of installation, Change a defun, Install, Install
3226 @ifnottex
3227 @unnumberedsubsec The effect of installation
3228 @end ifnottex
3231 You can see the effect of installing @code{multiply-by-seven} by
3232 evaluating the following sample.  Place the cursor after the following
3233 expression and type @kbd{C-x C-e}.  The number 21 will appear in the
3234 echo area.
3236 @smallexample
3237 (multiply-by-seven 3)
3238 @end smallexample
3240 If you wish, you can read the documentation for the function by typing
3241 @kbd{C-h f} (@code{describe-function}) and then the name of the
3242 function, @code{multiply-by-seven}.  When you do this, a
3243 @file{*Help*} window will appear on your screen that says:
3245 @smallexample
3246 @group
3247 multiply-by-seven:
3248 Multiply NUMBER by seven.
3249 @end group
3250 @end smallexample
3252 @noindent
3253 (To return to a single window on your screen, type @kbd{C-x 1}.)
3255 @node Change a defun,  , Effect of installation, Install
3256 @comment  node-name,  next,  previous,  up
3257 @subsection Change a Function Definition
3258 @cindex Changing a function definition
3259 @cindex Function definition, how to change
3260 @cindex Definition, how to change
3262 If you want to change the code in @code{multiply-by-seven}, just rewrite
3263 it.  To install the new version in place of the old one, evaluate the
3264 function definition again.  This is how you modify code in Emacs.  It is
3265 very simple.
3267 As an example, you can change the @code{multiply-by-seven} function to
3268 add the number to itself seven times instead of multiplying the number
3269 by seven.  It produces the same answer, but by a different path.  At
3270 the same time, we will add a comment to the code; a comment is text
3271 that the Lisp interpreter ignores, but that a human reader may find
3272 useful or enlightening.  The comment is that this is the ``second
3273 version''.
3275 @smallexample
3276 @group
3277 (defun multiply-by-seven (number)       ; @r{Second version.}
3278   "Multiply NUMBER by seven."
3279   (+ number number number number number number number))
3280 @end group
3281 @end smallexample
3283 @cindex Comments in Lisp code
3284 The comment follows a semicolon, @samp{;}.  In Lisp, everything on a
3285 line that follows a semicolon is a comment.  The end of the line is the
3286 end of the comment.  To stretch a comment over two or more lines, begin
3287 each line with a semicolon.
3289 @xref{Beginning a .emacs File, , Beginning a @file{.emacs}
3290 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
3291 Reference Manual}, for more about comments.
3293 You can install this version of the @code{multiply-by-seven} function by
3294 evaluating it in the same way you evaluated the first function: place
3295 the cursor after the last parenthesis and type @kbd{C-x C-e}.
3297 In summary, this is how you write code in Emacs Lisp: you write a
3298 function; install it; test it; and then make fixes or enhancements and
3299 install it again.
3301 @node Interactive, Interactive Options, Install, Writing Defuns
3302 @comment  node-name,  next,  previous,  up
3303 @section Make a Function Interactive
3304 @cindex Interactive functions
3305 @findex interactive
3307 You make a function interactive by placing a list that begins with
3308 the special form @code{interactive} immediately after the
3309 documentation.  A user can invoke an interactive function by typing
3310 @kbd{M-x} and then the name of the function; or by typing the keys to
3311 which it is bound, for example, by typing @kbd{C-n} for
3312 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
3314 Interestingly, when you call an interactive function interactively,
3315 the value returned is not automatically displayed in the echo area.
3316 This is because you often call an interactive function for its side
3317 effects, such as moving forward by a word or line, and not for the
3318 value returned.  If the returned value were displayed in the echo area
3319 each time you typed a key, it would be very distracting.
3321 @menu
3322 * Interactive multiply-by-seven::  An overview.
3323 * multiply-by-seven in detail::  The interactive version.
3324 @end menu
3326 @node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
3327 @ifnottex
3328 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
3329 @end ifnottex
3331 Both the use of the special form @code{interactive} and one way to
3332 display a value in the echo area can be illustrated by creating an
3333 interactive version of @code{multiply-by-seven}.
3335 @need 1250
3336 Here is the code:
3338 @smallexample
3339 @group
3340 (defun multiply-by-seven (number)       ; @r{Interactive version.}
3341   "Multiply NUMBER by seven."
3342   (interactive "p")
3343   (message "The result is %d" (* 7 number)))
3344 @end group
3345 @end smallexample
3347 @noindent
3348 You can install this code by placing your cursor after it and typing
3349 @kbd{C-x C-e}.  The name of the function will appear in your echo area.
3350 Then, you can use this code by typing @kbd{C-u} and a number and then
3351 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}.  The phrase
3352 @samp{The result is @dots{}} followed by the product will appear in the
3353 echo area.
3355 Speaking more generally, you invoke a function like this in either of two
3356 ways:
3358 @enumerate
3359 @item
3360 By typing a prefix argument that contains the number to be passed, and
3361 then typing @kbd{M-x} and the name of the function, as with
3362 @kbd{C-u 3 M-x forward-sentence}; or,
3364 @item
3365 By typing whatever key or keychord the function is bound to, as with
3366 @kbd{C-u 3 M-e}.
3367 @end enumerate
3369 @noindent
3370 Both the examples just mentioned work identically to move point forward
3371 three sentences.  (Since @code{multiply-by-seven} is not bound to a key,
3372 it could not be used as an example of key binding.)
3374 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
3375 to a key.)
3377 A prefix argument is passed to an interactive function by typing the
3378 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
3379 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
3380 type @kbd{C-u} without a number, it defaults to 4).
3382 @node multiply-by-seven in detail,  , Interactive multiply-by-seven, Interactive
3383 @comment  node-name,  next,  previous,  up
3384 @subsection An Interactive @code{multiply-by-seven}
3386 Let's look at the use of the special form @code{interactive} and then at
3387 the function @code{message} in the interactive version of
3388 @code{multiply-by-seven}.  You will recall that the function definition
3389 looks like this:
3391 @smallexample
3392 @group
3393 (defun multiply-by-seven (number)       ; @r{Interactive version.}
3394   "Multiply NUMBER by seven."
3395   (interactive "p")
3396   (message "The result is %d" (* 7 number)))
3397 @end group
3398 @end smallexample
3400 In this function, the expression, @code{(interactive "p")}, is a list of
3401 two elements.  The @code{"p"} tells Emacs to pass the prefix argument to
3402 the function and use its value for the argument of the function.
3404 @need 1000
3405 The argument will be a number.  This means that the symbol
3406 @code{number} will be bound to a number in the line:
3408 @smallexample
3409 (message "The result is %d" (* 7 number))
3410 @end smallexample
3412 @need 1250
3413 @noindent
3414 For example, if your prefix argument is 5, the Lisp interpreter will
3415 evaluate the line as if it were:
3417 @smallexample
3418 (message "The result is %d" (* 7 5))
3419 @end smallexample
3421 @noindent
3422 (If you are reading this in GNU Emacs, you can evaluate this expression
3423 yourself.)  First, the interpreter will evaluate the inner list, which
3424 is @code{(* 7 5)}.  This returns a value of 35.  Next, it
3425 will evaluate the outer list, passing the values of the second and
3426 subsequent elements of the list to the function @code{message}.
3428 As we have seen, @code{message} is an Emacs Lisp function especially
3429 designed for sending a one line message to a user.  (@xref{message, , The
3430 @code{message} function}.)
3431 In summary, the @code{message} function prints its first argument in the
3432 echo area as is, except for occurrences of @samp{%d}, @samp{%s}, or
3433 @samp{%c}.  When it sees one of these control sequences, the function
3434 looks to the second and subsequent arguments and prints the value of the
3435 argument in the location in the string where the control sequence is
3436 located.
3438 In the interactive @code{multiply-by-seven} function, the control string
3439 is @samp{%d}, which requires a number, and the value returned by
3440 evaluating @code{(* 7 5)} is the number 35.  Consequently, the number 35
3441 is printed in place of the @samp{%d} and the message is @samp{The result
3442 is 35}.
3444 (Note that when you call the function @code{multiply-by-seven}, the
3445 message is printed without quotes, but when you call @code{message}, the
3446 text is printed in double quotes.  This is because the value returned by
3447 @code{message} is what appears in the echo area when you evaluate an
3448 expression whose first element is @code{message}; but when embedded in a
3449 function, @code{message} prints the text as a side effect without
3450 quotes.)
3452 @node Interactive Options, Permanent Installation, Interactive, Writing Defuns
3453 @comment  node-name,  next,  previous,  up
3454 @section Different Options for @code{interactive}
3455 @cindex Options for @code{interactive}
3456 @cindex Interactive options
3458 In the example, @code{multiply-by-seven} used @code{"p"} as the
3459 argument to @code{interactive}.  This argument told Emacs to interpret
3460 your typing either @kbd{C-u} followed by a number or @key{META}
3461 followed by a number as a command to pass that number to the function
3462 as its argument.  Emacs has more than twenty characters predefined for
3463 use with @code{interactive}.  In almost every case, one of these
3464 options will enable you to pass the right information interactively to
3465 a function.  (@xref{Interactive Codes, , Code Characters for
3466 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
3468 @need 1250
3469 For example, the character @samp{r} causes Emacs to pass the beginning
3470 and end of the region (the current values of point and mark) to the
3471 function as two separate arguments.  It is used as follows:
3473 @smallexample
3474 (interactive "r")
3475 @end smallexample
3477 On the other hand, a @samp{B} tells Emacs to ask for the name of a
3478 buffer that will be passed to the function.  When it sees a @samp{B},
3479 Emacs will ask for the name by prompting the user in the minibuffer,
3480 using a string that follows the @samp{B}, as in @code{"BAppend to
3481 buffer:@: "}.  Not only will Emacs prompt for the name, but Emacs will
3482 complete the name if you type enough of it and press @key{TAB}.
3484 A function with two or more arguments can have information passed to
3485 each argument by adding parts to the string that follows
3486 @code{interactive}.  When you do this, the information is passed to
3487 each argument in the same order it is specified in the
3488 @code{interactive} list.  In the string, each part is separated from
3489 the next part by a @samp{\n}, which is a newline.  For example, you
3490 could follow @code{"BAppend to buffer:@: "} with a @samp{\n} and an
3491 @samp{r}.  This would cause Emacs to pass the values of point and mark
3492 to the function as well as prompt you for the buffer---three arguments
3493 in all.
3495 In this case, the function definition would look like the following,
3496 where @code{buffer}, @code{start}, and @code{end} are the symbols to
3497 which @code{interactive} binds the buffer and the current values of the
3498 beginning and ending of the region:
3500 @smallexample
3501 @group
3502 (defun @var{name-of-function} (buffer start end)
3503   "@var{documentation}@dots{}"
3504   (interactive "BAppend to buffer:@: \nr")
3505   @var{body-of-function}@dots{})
3506 @end group
3507 @end smallexample
3509 @noindent
3510 (The space after the colon in the prompt makes it look better when you
3511 are prompted.  The @code{append-to-buffer} function looks exactly like
3512 this.  @xref{append-to-buffer, , The Definition of
3513 @code{append-to-buffer}}.)
3515 If a function does not have arguments, then @code{interactive} does not
3516 require any.  Such a function contains the simple expression
3517 @code{(interactive)}.  The @code{mark-whole-buffer} function is like
3518 this.
3520 Alternatively, if the special letter-codes are not right for your
3521 application, you can pass your own arguments to @code{interactive} as
3522 a list.  @xref{Using Interactive, , Using @code{Interactive}, elisp, The
3523 GNU Emacs Lisp Reference Manual}, for more information about this advanced
3524 technique.
3526 @node Permanent Installation, let, Interactive Options, Writing Defuns
3527 @comment  node-name,  next,  previous,  up
3528 @section Install Code Permanently
3529 @cindex Install code permanently
3530 @cindex Permanent code installation
3531 @cindex Code installation
3533 When you install a function definition by evaluating it, it will stay
3534 installed until you quit Emacs.  The next time you start a new session
3535 of Emacs, the function will not be installed unless you evaluate the
3536 function definition again.
3538 At some point, you may want to have code installed automatically
3539 whenever you start a new session of Emacs.  There are several ways of
3540 doing this:
3542 @itemize @bullet
3543 @item
3544 If you have code that is just for yourself, you can put the code for the
3545 function definition in your @file{.emacs} initialization file.  When you
3546 start Emacs, your @file{.emacs} file is automatically evaluated and all
3547 the function definitions within it are installed.
3548 @xref{Emacs Initialization, , Your @file{.emacs} File}.
3550 @item
3551 Alternatively, you can put the function definitions that you want
3552 installed in one or more files of their own and use the @code{load}
3553 function to cause Emacs to evaluate and thereby install each of the
3554 functions in the files.
3555 @xref{Loading Files, , Loading Files}.
3557 @item
3558 On the other hand, if you have code that your whole site will use, it
3559 is usual to put it in a file called @file{site-init.el} that is loaded
3560 when Emacs is built.  This makes the code available to everyone who
3561 uses your machine.  (See the @file{INSTALL} file that is part of the
3562 Emacs distribution.)
3563 @end itemize
3565 Finally, if you have code that everyone who uses Emacs may want, you
3566 can post it on a computer network or send a copy to the Free Software
3567 Foundation.  (When you do this, please license the code and its
3568 documentation under a license that permits other people to run, copy,
3569 study, modify, and redistribute the code and which protects you from
3570 having your work taken from you.)  If you send a copy of your code to
3571 the Free Software Foundation, and properly protect yourself and
3572 others, it may be included in the next release of Emacs.  In large
3573 part, this is how Emacs has grown over the past years, by donations.
3575 @node let, if, Permanent Installation, Writing Defuns
3576 @comment  node-name,  next,  previous,  up
3577 @section @code{let}
3578 @findex let
3580 The @code{let} expression is a special form in Lisp that you will need
3581 to use in most function definitions.
3583 @code{let} is used to attach or bind a symbol to a value in such a way
3584 that the Lisp interpreter will not confuse the variable with a
3585 variable of the same name that is not part of the function.
3587 To understand why the @code{let} special form is necessary, consider
3588 the situation in which you own a home that you generally refer to as
3589 `the house', as in the sentence, ``The house needs painting.''  If you
3590 are visiting a friend and your host refers to `the house', he is
3591 likely to be referring to @emph{his} house, not yours, that is, to a
3592 different house.
3594 If your friend is referring to his house and you think he is referring
3595 to your house, you may be in for some confusion.  The same thing could
3596 happen in Lisp if a variable that is used inside of one function has
3597 the same name as a variable that is used inside of another function,
3598 and the two are not intended to refer to the same value.  The
3599 @code{let} special form prevents this kind of confusion.
3601 @menu
3602 * Prevent confusion::
3603 * Parts of let Expression::
3604 * Sample let Expression::
3605 * Uninitialized let Variables::
3606 @end menu
3608 @node Prevent confusion, Parts of let Expression, let, let
3609 @ifnottex
3610 @unnumberedsubsec @code{let} Prevents Confusion
3611 @end ifnottex
3613 @cindex @samp{local variable} defined
3614 The @code{let} special form prevents confusion.  @code{let} creates a
3615 name for a @dfn{local variable} that overshadows any use of the same
3616 name outside the @code{let} expression.  This is like understanding
3617 that whenever your host refers to `the house', he means his house, not
3618 yours.  (Symbols used in argument lists work the same way.
3619 @xref{defun, , The @code{defun} Special Form}.)
3621 Local variables created by a @code{let} expression retain their value
3622 @emph{only} within the @code{let} expression itself (and within
3623 expressions called within the @code{let} expression); the local
3624 variables have no effect outside the @code{let} expression.
3626 Another way to think about @code{let} is that it is like a @code{setq}
3627 that is temporary and local.  The values set by @code{let} are
3628 automatically undone when the @code{let} is finished.  The setting
3629 only affects expressions that are inside the bounds of the @code{let}
3630 expression.  In computer science jargon, we would say ``the binding of
3631 a symbol is visible only in functions called in the @code{let} form;
3632 in Emacs Lisp, scoping is dynamic, not lexical.''
3634 @code{let} can create more than one variable at once.  Also,
3635 @code{let} gives each variable it creates an initial value, either a
3636 value specified by you, or @code{nil}.  (In the jargon, this is called
3637 `binding the variable to the value'.)  After @code{let} has created
3638 and bound the variables, it executes the code in the body of the
3639 @code{let}, and returns the value of the last expression in the body,
3640 as the value of the whole @code{let} expression.  (`Execute' is a jargon
3641 term that means to evaluate a list; it comes from the use of the word
3642 meaning `to give practical effect to' (@cite{Oxford English
3643 Dictionary}).  Since you evaluate an expression to perform an action,
3644 `execute' has evolved as a synonym to `evaluate'.)
3646 @node Parts of let Expression, Sample let Expression, Prevent confusion, let
3647 @comment  node-name,  next,  previous,  up
3648 @subsection The Parts of a @code{let} Expression
3649 @cindex @code{let} expression, parts of
3650 @cindex Parts of @code{let} expression
3652 @cindex @samp{varlist} defined
3653 A @code{let} expression is a list of three parts.  The first part is
3654 the symbol @code{let}.  The second part is a list, called a
3655 @dfn{varlist}, each element of which is either a symbol by itself or a
3656 two-element list, the first element of which is a symbol.  The third
3657 part of the @code{let} expression is the body of the @code{let}.  The
3658 body usually consists of one or more lists.
3660 @need 800
3661 A template for a @code{let} expression looks like this:
3663 @smallexample
3664 (let @var{varlist} @var{body}@dots{})
3665 @end smallexample
3667 @noindent
3668 The symbols in the varlist are the variables that are given initial
3669 values by the @code{let} special form.  Symbols by themselves are given
3670 the initial value of @code{nil}; and each symbol that is the first
3671 element of a two-element list is bound to the value that is returned
3672 when the Lisp interpreter evaluates the second element.
3674 Thus, a varlist might look like this: @code{(thread (needles 3))}.  In
3675 this case, in a @code{let} expression, Emacs binds the symbol
3676 @code{thread} to an initial value of @code{nil}, and binds the symbol
3677 @code{needles} to an initial value of 3.
3679 When you write a @code{let} expression, what you do is put the
3680 appropriate expressions in the slots of the @code{let} expression
3681 template.
3683 If the varlist is composed of two-element lists, as is often the case,
3684 the template for the @code{let} expression looks like this:
3686 @smallexample
3687 @group
3688 (let ((@var{variable} @var{value})
3689       (@var{variable} @var{value})
3690       @dots{})
3691   @var{body}@dots{})
3692 @end group
3693 @end smallexample
3695 @node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let
3696 @comment  node-name,  next,  previous,  up
3697 @subsection Sample @code{let} Expression
3698 @cindex Sample @code{let} expression
3699 @cindex @code{let} expression sample
3701 The following expression creates and gives initial values
3702 to the two variables @code{zebra} and @code{tiger}.  The body of the
3703 @code{let} expression is a list which calls the @code{message} function.
3705 @smallexample
3706 @group
3707 (let ((zebra 'stripes)
3708       (tiger 'fierce))
3709   (message "One kind of animal has %s and another is %s."
3710            zebra tiger))
3711 @end group
3712 @end smallexample
3714 Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}.
3716 The two variables are @code{zebra} and @code{tiger}.  Each variable is
3717 the first element of a two-element list and each value is the second
3718 element of its two-element list.  In the varlist, Emacs binds the
3719 variable @code{zebra} to the value @code{stripes}, and binds the
3720 variable @code{tiger} to the value @code{fierce}.  In this example,
3721 both values are symbols preceded by a quote.  The values could just as
3722 well have been another list or a string.  The body of the @code{let}
3723 follows after the list holding the variables.  In this example, the body
3724 is a list that uses the @code{message} function to print a string in
3725 the echo area.
3727 @need 1500
3728 You may evaluate the example in the usual fashion, by placing the
3729 cursor after the last parenthesis and typing @kbd{C-x C-e}.  When you do
3730 this, the following will appear in the echo area:
3732 @smallexample
3733 "One kind of animal has stripes and another is fierce."
3734 @end smallexample
3736 As we have seen before, the @code{message} function prints its first
3737 argument, except for @samp{%s}.  In this example, the value of the variable
3738 @code{zebra} is printed at the location of the first @samp{%s} and the
3739 value of the variable @code{tiger} is printed at the location of the
3740 second @samp{%s}.
3742 @node Uninitialized let Variables,  , Sample let Expression, let
3743 @comment  node-name,  next,  previous,  up
3744 @subsection Uninitialized Variables in a @code{let} Statement
3745 @cindex Uninitialized @code{let} variables
3746 @cindex @code{let} variables uninitialized
3748 If you do not bind the variables in a @code{let} statement to specific
3749 initial values, they will automatically be bound to an initial value of
3750 @code{nil}, as in the following expression:
3752 @smallexample
3753 @group
3754 (let ((birch 3)
3755       pine
3756       fir
3757       (oak 'some))
3758   (message
3759    "Here are %d variables with %s, %s, and %s value."
3760    birch pine fir oak))
3761 @end group
3762 @end smallexample
3764 @noindent
3765 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
3767 @need 1250
3768 If you evaluate this expression in the usual way, the following will
3769 appear in your echo area:
3771 @smallexample
3772 "Here are 3 variables with nil, nil, and some value."
3773 @end smallexample
3775 @noindent
3776 In this example, Emacs binds the symbol @code{birch} to the number 3,
3777 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
3778 the symbol @code{oak} to the value @code{some}.
3780 Note that in the first part of the @code{let}, the variables @code{pine}
3781 and @code{fir} stand alone as atoms that are not surrounded by
3782 parentheses; this is because they are being bound to @code{nil}, the
3783 empty list.  But @code{oak} is bound to @code{some} and so is a part of
3784 the list @code{(oak 'some)}.  Similarly, @code{birch} is bound to the
3785 number 3 and so is in a list with that number.  (Since a number
3786 evaluates to itself, the number does not need to be quoted.  Also, the
3787 number is printed in the message using a @samp{%d} rather than a
3788 @samp{%s}.)  The four variables as a group are put into a list to
3789 delimit them from the body of the @code{let}.
3791 @node if, else, let, Writing Defuns
3792 @comment  node-name,  next,  previous,  up
3793 @section The @code{if} Special Form
3794 @findex if
3795 @cindex Conditional with @code{if}
3797 A third special form, in addition to @code{defun} and @code{let}, is the
3798 conditional @code{if}.  This form is used to instruct the computer to
3799 make decisions.  You can write function definitions without using
3800 @code{if}, but it is used often enough, and is important enough, to be
3801 included here.  It is used, for example, in the code for the
3802 function @code{beginning-of-buffer}.
3804 The basic idea behind an @code{if}, is that ``@emph{if} a test is true,
3805 @emph{then} an expression is evaluated.''  If the test is not true, the
3806 expression is not evaluated.  For example, you might make a decision
3807 such as, ``if it is warm and sunny, then go to the beach!''
3809 @menu
3810 * if in more detail::
3811 * type-of-animal in detail::    An example of an @code{if} expression.
3812 @end menu
3814 @node if in more detail, type-of-animal in detail, if, if
3815 @ifnottex
3816 @unnumberedsubsec @code{if} in more detail
3817 @end ifnottex
3819 @cindex @samp{if-part} defined
3820 @cindex @samp{then-part} defined
3821 An @code{if} expression written in Lisp does not use the word `then';
3822 the test and the action are the second and third elements of the list
3823 whose first element is @code{if}.  Nonetheless, the test part of an
3824 @code{if} expression is often called the @dfn{if-part} and the second
3825 argument is often called the @dfn{then-part}.
3827 Also, when an @code{if} expression is written, the true-or-false-test
3828 is usually written on the same line as the symbol @code{if}, but the
3829 action to carry out if the test is true, the ``then-part'', is written
3830 on the second and subsequent lines.  This makes the @code{if}
3831 expression easier to read.
3833 @smallexample
3834 @group
3835 (if @var{true-or-false-test}
3836     @var{action-to-carry-out-if-test-is-true})
3837 @end group
3838 @end smallexample
3840 @noindent
3841 The true-or-false-test will be an expression that
3842 is evaluated by the Lisp interpreter.
3844 Here is an example that you can evaluate in the usual manner.  The test
3845 is whether the number 5 is greater than the number 4.  Since it is, the
3846 message @samp{5 is greater than 4!} will be printed.
3848 @smallexample
3849 @group
3850 (if (> 5 4)                             ; @r{if-part}
3851     (message "5 is greater than 4!"))   ; @r{then-part}
3852 @end group
3853 @end smallexample
3855 @noindent
3856 (The function @code{>} tests whether its first argument is greater than
3857 its second argument and returns true if it is.)
3858 @findex > (greater than)
3860 Of course, in actual use, the test in an @code{if} expression will not
3861 be fixed for all time as it is by the expression @code{(> 5 4)}.
3862 Instead, at least one of the variables used in the test will be bound to
3863 a value that is not known ahead of time.  (If the value were known ahead
3864 of time, we would not need to run the test!)
3866 For example, the value may be bound to an argument of a function
3867 definition.  In the following function definition, the character of the
3868 animal is a value that is passed to the function.  If the value bound to
3869 @code{characteristic} is @code{fierce}, then the message, @samp{It's a
3870 tiger!} will be printed; otherwise, @code{nil} will be returned.
3872 @smallexample
3873 @group
3874 (defun type-of-animal (characteristic)
3875   "Print message in echo area depending on CHARACTERISTIC.
3876 If the CHARACTERISTIC is the symbol `fierce',
3877 then warn of a tiger."
3878   (if (equal characteristic 'fierce)
3879       (message "It's a tiger!")))
3880 @end group
3881 @end smallexample
3883 @need 1500
3884 @noindent
3885 If you are reading this inside of GNU Emacs, you can evaluate the
3886 function definition in the usual way to install it in Emacs, and then you
3887 can evaluate the following two expressions to see the results:
3889 @smallexample
3890 @group
3891 (type-of-animal 'fierce)
3893 (type-of-animal 'zebra)
3895 @end group
3896 @end smallexample
3898 @c Following sentences rewritten to prevent overfull hbox.
3899 @noindent
3900 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
3901 following message printed in the echo area: @code{"It's a tiger!"}; and
3902 when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil}
3903 printed in the echo area.
3905 @node type-of-animal in detail,  , if in more detail, if
3906 @comment  node-name,  next,  previous,  up
3907 @subsection The @code{type-of-animal} Function in Detail
3909 Let's look at the @code{type-of-animal} function in detail.
3911 The function definition for @code{type-of-animal} was written by filling
3912 the slots of two templates, one for a function definition as a whole, and
3913 a second for an @code{if} expression.
3915 @need 1250
3916 The template for every function that is not interactive is:
3918 @smallexample
3919 @group
3920 (defun @var{name-of-function} (@var{argument-list})
3921   "@var{documentation}@dots{}"
3922   @var{body}@dots{})
3923 @end group
3924 @end smallexample
3926 @need 800
3927 The parts of the function that match this template look like this:
3929 @smallexample
3930 @group
3931 (defun type-of-animal (characteristic)
3932   "Print message in echo area depending on CHARACTERISTIC.
3933 If the CHARACTERISTIC is the symbol `fierce',
3934 then warn of a tiger."
3935   @var{body: the} @code{if} @var{expression})
3936 @end group
3937 @end smallexample
3939 The name of function is @code{type-of-animal}; it is passed the value
3940 of one argument.  The argument list is followed by a multi-line
3941 documentation string.  The documentation string is included in the
3942 example because it is a good habit to write documentation string for
3943 every function definition.  The body of the function definition
3944 consists of the @code{if} expression.
3946 @need 800
3947 The template for an @code{if} expression looks like this:
3949 @smallexample
3950 @group
3951 (if @var{true-or-false-test}
3952     @var{action-to-carry-out-if-the-test-returns-true})
3953 @end group
3954 @end smallexample
3956 @need 1250
3957 In the @code{type-of-animal} function, the code for the @code{if}
3958 looks like this:
3960 @smallexample
3961 @group
3962 (if (equal characteristic 'fierce)
3963     (message "It's a tiger!")))
3964 @end group
3965 @end smallexample
3967 @need 800
3968 Here, the true-or-false-test is the expression:
3970 @smallexample
3971 (equal characteristic 'fierce)
3972 @end smallexample
3974 @noindent
3975 In Lisp, @code{equal} is a function that determines whether its first
3976 argument is equal to its second argument.  The second argument is the
3977 quoted symbol @code{'fierce} and the first argument is the value of the
3978 symbol @code{characteristic}---in other words, the argument passed to
3979 this function.
3981 In the first exercise of @code{type-of-animal}, the argument
3982 @code{fierce} is passed to @code{type-of-animal}.  Since @code{fierce}
3983 is equal to @code{fierce}, the expression, @code{(equal characteristic
3984 'fierce)}, returns a value of true.  When this happens, the @code{if}
3985 evaluates the second argument or then-part of the @code{if}:
3986 @code{(message "It's tiger!")}.
3988 On the other hand, in the second exercise of @code{type-of-animal}, the
3989 argument @code{zebra} is passed to @code{type-of-animal}.  @code{zebra}
3990 is not equal to @code{fierce}, so the then-part is not evaluated and
3991 @code{nil} is returned by the @code{if} expression.
3993 @node else, Truth & Falsehood, if, Writing Defuns
3994 @comment  node-name,  next,  previous,  up
3995 @section If--then--else Expressions
3996 @cindex Else
3998 An @code{if} expression may have an optional third argument, called
3999 the @dfn{else-part}, for the case when the true-or-false-test returns
4000 false.  When this happens, the second argument or then-part of the
4001 overall @code{if} expression is @emph{not} evaluated, but the third or
4002 else-part @emph{is} evaluated.  You might think of this as the cloudy
4003 day alternative for the decision `if it is warm and sunny, then go to
4004 the beach, else read a book!''.
4006 The word ``else'' is not written in the Lisp code; the else-part of an
4007 @code{if} expression comes after the then-part.  In the written Lisp, the
4008 else-part is usually written to start on a line of its own and is
4009 indented less than the then-part:
4011 @smallexample
4012 @group
4013 (if @var{true-or-false-test}
4014     @var{action-to-carry-out-if-the-test-returns-true}
4015   @var{action-to-carry-out-if-the-test-returns-false})
4016 @end group
4017 @end smallexample
4019 For example, the following @code{if} expression prints the message @samp{4
4020 is not greater than 5!} when you evaluate it in the usual way:
4022 @smallexample
4023 @group
4024 (if (> 4 5)                             ; @r{if-part}
4025     (message "5 is greater than 4!")    ; @r{then-part}
4026   (message "4 is not greater than 5!")) ; @r{else-part}
4027 @end group
4028 @end smallexample
4030 @noindent
4031 Note that the different levels of indentation make it easy to
4032 distinguish the then-part from the else-part.  (GNU Emacs has several
4033 commands that automatically indent @code{if} expressions correctly.
4034 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
4036 We can extend the @code{type-of-animal} function to include an
4037 else-part by simply incorporating an additional part to the @code{if}
4038 expression.
4040 @need 1500
4041 You can see the consequences of doing this if you evaluate the following
4042 version of the @code{type-of-animal} function definition to install it
4043 and then evaluate the two subsequent expressions to pass different
4044 arguments to the function.
4046 @smallexample
4047 @group
4048 (defun type-of-animal (characteristic)  ; @r{Second version.}
4049   "Print message in echo area depending on CHARACTERISTIC.
4050 If the CHARACTERISTIC is the symbol `fierce',
4051 then warn of a tiger;
4052 else say it's not fierce."
4053   (if (equal characteristic 'fierce)
4054       (message "It's a tiger!")
4055     (message "It's not fierce!")))
4056 @end group
4057 @end smallexample
4058 @sp 1
4060 @smallexample
4061 @group
4062 (type-of-animal 'fierce)
4064 (type-of-animal 'zebra)
4066 @end group
4067 @end smallexample
4069 @c Following sentence rewritten to prevent overfull hbox.
4070 @noindent
4071 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
4072 following message printed in the echo area: @code{"It's a tiger!"}; but
4073 when you evaluate @code{(type-of-animal 'zebra)}, you will see
4074 @code{"It's not fierce!"}.
4076 (Of course, if the @var{characteristic} were @code{ferocious}, the
4077 message @code{"It's not fierce!"} would be printed; and it would be
4078 misleading!  When you write code, you need to take into account the
4079 possibility that some such argument will be tested by the @code{if} and
4080 write your program accordingly.)
4082 @node Truth & Falsehood, save-excursion, else, Writing Defuns
4083 @comment  node-name,  next,  previous,  up
4084 @section Truth and Falsehood in Emacs Lisp
4085 @cindex Truth and falsehood in Emacs Lisp
4086 @cindex Falsehood and truth in Emacs Lisp
4087 @findex nil
4089 There is an important aspect to the truth test in an @code{if}
4090 expression.  So far, we have spoken of `true' and `false' as values of
4091 predicates as if they were new kinds of Emacs Lisp objects.  In fact,
4092 `false' is just our old friend @code{nil}.  Anything else---anything
4093 at all---is `true'.
4095 The expression that tests for truth is interpreted as @dfn{true}
4096 if the result of evaluating it is a value that is not @code{nil}.  In
4097 other words, the result of the test is considered true if the value
4098 returned is a number such as 47, a string such as @code{"hello"}, or a
4099 symbol (other than @code{nil}) such as @code{flowers}, or a list, or
4100 even a buffer!
4102 @menu
4103 * nil explained::               @code{nil} has two meanings.
4104 @end menu
4106 @node nil explained,  , Truth & Falsehood, Truth & Falsehood
4107 @ifnottex
4108 @unnumberedsubsec An explanation of @code{nil}
4109 @end ifnottex
4111 Before illustrating a test for truth, we need an explanation of @code{nil}.
4113 In Emacs Lisp, the symbol @code{nil} has two meanings.  First, it means the
4114 empty list.  Second, it means false and is the value returned when a
4115 true-or-false-test tests false.  @code{nil} can be written as an empty
4116 list, @code{()}, or as @code{nil}.  As far as the Lisp interpreter is
4117 concerned, @code{()} and @code{nil} are the same.  Humans, however, tend
4118 to use @code{nil} for false and @code{()} for the empty list.
4120 In Emacs Lisp, any value that is not @code{nil}---is not the empty
4121 list---is considered true.  This means that if an evaluation returns
4122 something that is not an empty list, an @code{if} expression will test
4123 true.  For example, if a number is put in the slot for the test, it
4124 will be evaluated and will return itself, since that is what numbers
4125 do when evaluated.  In this conditional, the @code{if} expression will
4126 test true.  The expression tests false only when @code{nil}, an empty
4127 list, is returned by evaluating the expression.
4129 You can see this by evaluating the two expressions in the following examples.
4131 In the first example, the number 4 is evaluated as the test in the
4132 @code{if} expression and returns itself; consequently, the then-part
4133 of the expression is evaluated and returned: @samp{true} appears in
4134 the echo area.  In the second example, the @code{nil} indicates false;
4135 consequently, the else-part of the expression is evaluated and
4136 returned: @samp{false} appears in the echo area.
4138 @smallexample
4139 @group
4140 (if 4
4141     'true
4142   'false)
4143 @end group
4145 @group
4146 (if nil
4147     'true
4148   'false)
4149 @end group
4150 @end smallexample
4152 @need 1250
4153 Incidentally, if some other useful value is not available for a test that
4154 returns true, then the Lisp interpreter will return the symbol @code{t}
4155 for true.  For example, the expression @code{(> 5 4)} returns @code{t}
4156 when evaluated, as you can see by evaluating it in the usual way:
4158 @smallexample
4159 (> 5 4)
4160 @end smallexample
4162 @need 1250
4163 @noindent
4164 On the other hand, this function returns @code{nil} if the test is false.
4166 @smallexample
4167 (> 4 5)
4168 @end smallexample
4170 @node save-excursion, Review, Truth & Falsehood, Writing Defuns
4171 @comment  node-name,  next,  previous,  up
4172 @section @code{save-excursion}
4173 @findex save-excursion
4174 @cindex Region, what it is
4175 @cindex Preserving point, mark, and buffer
4176 @cindex Point, mark, buffer preservation
4177 @findex point
4178 @findex mark
4180 The @code{save-excursion} function is the fourth and final special form
4181 that we will discuss in this chapter.
4183 In Emacs Lisp programs used for editing, the @code{save-excursion}
4184 function is very common.  It saves the location of point and mark,
4185 executes the body of the function, and then restores point and mark to
4186 their previous positions if their locations were changed.  Its primary
4187 purpose is to keep the user from being surprised and disturbed by
4188 unexpected movement of point or mark.
4190 @menu
4191 * Point and mark::              A review of various locations.
4192 * Template for save-excursion::
4193 @end menu
4195 @node Point and mark, Template for save-excursion, save-excursion, save-excursion
4196 @ifnottex
4197 @unnumberedsubsec Point and Mark
4198 @end ifnottex
4200 Before discussing @code{save-excursion}, however, it may be useful
4201 first to review what point and mark are in GNU Emacs.  @dfn{Point} is
4202 the current location of the cursor.  Wherever the cursor
4203 is, that is point.  More precisely, on terminals where the cursor
4204 appears to be on top of a character, point is immediately before the
4205 character.  In Emacs Lisp, point is an integer.  The first character in
4206 a buffer is number one, the second is number two, and so on.  The
4207 function @code{point} returns the current position of the cursor as a
4208 number.  Each buffer has its own value for point.
4210 The @dfn{mark} is another position in the buffer; its value can be set
4211 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}).  If
4212 a mark has been set, you can use the command @kbd{C-x C-x}
4213 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
4214 and set the mark to be the previous position of point.  In addition, if
4215 you set another mark, the position of the previous mark is saved in the
4216 mark ring.  Many mark positions can be saved this way.  You can jump the
4217 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
4218 times.
4220 The part of the buffer between point and mark is called @dfn{the
4221 region}.  Numerous commands work on the region, including
4222 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
4223 @code{print-region}.
4225 The @code{save-excursion} special form saves the locations of point and
4226 mark and restores those positions after the code within the body of the
4227 special form is evaluated by the Lisp interpreter.  Thus, if point were
4228 in the beginning of a piece of text and some code moved point to the end
4229 of the buffer, the @code{save-excursion} would put point back to where
4230 it was before, after the expressions in the body of the function were
4231 evaluated.
4233 In Emacs, a function frequently moves point as part of its internal
4234 workings even though a user would not expect this.  For example,
4235 @code{count-lines-region} moves point.  To prevent the user from being
4236 bothered by jumps that are both unexpected and (from the user's point of
4237 view) unnecessary, @code{save-excursion} is often used to keep point and
4238 mark in the location expected by the user.  The use of
4239 @code{save-excursion} is good housekeeping.
4241 To make sure the house stays clean, @code{save-excursion} restores the
4242 values of point and mark even if something goes wrong in the code inside
4243 of it (or, to be more precise and to use the proper jargon, ``in case of
4244 abnormal exit'').  This feature is very helpful.
4246 In addition to recording the values of point and mark,
4247 @code{save-excursion} keeps track of the current buffer, and restores
4248 it, too.  This means you can write code that will change the buffer and
4249 have @code{save-excursion} switch you back to the original buffer.  This
4250 is how @code{save-excursion} is used in @code{append-to-buffer}.
4251 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
4253 @node Template for save-excursion,  , Point and mark, save-excursion
4254 @comment  node-name,  next,  previous,  up
4255 @subsection Template for a @code{save-excursion} Expression
4257 @need 800
4258 The template for code using @code{save-excursion} is simple:
4260 @smallexample
4261 @group
4262 (save-excursion
4263   @var{body}@dots{})
4264 @end group
4265 @end smallexample
4267 @noindent
4268 The body of the function is one or more expressions that will be
4269 evaluated in sequence by the Lisp interpreter.  If there is more than
4270 one expression in the body, the value of the last one will be returned
4271 as the value of the @code{save-excursion} function.  The other
4272 expressions in the body are evaluated only for their side effects; and
4273 @code{save-excursion} itself is used only for its side effect (which
4274 is restoring the positions of point and mark).
4276 @need 1250
4277 In more detail, the template for a @code{save-excursion} expression
4278 looks like this:
4280 @smallexample
4281 @group
4282 (save-excursion
4283   @var{first-expression-in-body}
4284   @var{second-expression-in-body}
4285   @var{third-expression-in-body}
4286    @dots{}
4287   @var{last-expression-in-body})
4288 @end group
4289 @end smallexample
4291 @noindent
4292 An expression, of course, may be a symbol on its own or a list.
4294 In Emacs Lisp code, a @code{save-excursion} expression often occurs
4295 within the body of a @code{let} expression.  It looks like this:
4297 @smallexample
4298 @group
4299 (let @var{varlist}
4300   (save-excursion
4301     @var{body}@dots{}))
4302 @end group
4303 @end smallexample
4305 @node Review, defun Exercises, save-excursion, Writing Defuns
4306 @comment  node-name,  next,  previous,  up
4307 @section Review
4309 In the last few chapters we have introduced a fair number of functions
4310 and special forms.  Here they are described in brief, along with a few
4311 similar functions that have not been mentioned yet.
4313 @table @code
4314 @item eval-last-sexp
4315 Evaluate the last symbolic expression before the current location of
4316 point.  The value is printed in the echo area unless the function is
4317 invoked with an argument; in that case, the output is printed in the
4318 current buffer.  This command is normally bound to @kbd{C-x C-e}.
4320 @item defun
4321 Define function.  This special form has up to five parts: the name,
4322 a template for the arguments that will be passed to the function,
4323 documentation, an optional interactive declaration, and the body of the
4324 definition.
4326 @need 1250
4327 For example:
4329 @smallexample
4330 @group
4331 (defun back-to-indentation ()
4332   "Move point to first visible character on line."
4333   (interactive)
4334   (beginning-of-line 1)
4335   (skip-chars-forward " \t"))
4336 @end group
4337 @end smallexample
4339 @item interactive
4340 Declare to the interpreter that the function can be used
4341 interactively.  This special form may be followed by a string with one
4342 or more parts that pass the information to the arguments of the
4343 function, in sequence.  These parts may also tell the interpreter to
4344 prompt for information.  Parts of the string are separated by
4345 newlines, @samp{\n}.
4347 @need 1000
4348 Common code characters are:
4350 @table @code
4351 @item b
4352 The name of an existing buffer.
4354 @item f
4355 The name of an existing file.
4357 @item p
4358 The numeric prefix argument.  (Note that this `p' is lower case.)
4360 @item r
4361 Point and the mark, as two numeric arguments, smallest first.  This
4362 is the only code letter that specifies two successive arguments
4363 rather than one.
4364 @end table
4366 @xref{Interactive Codes, , Code Characters for @samp{interactive},
4367 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
4368 code characters.
4370 @item let
4371 Declare that a list of variables is for use within the body of the
4372 @code{let} and give them an initial value, either @code{nil} or a
4373 specified value; then evaluate the rest of the expressions in the body
4374 of the @code{let} and return the value of the last one.  Inside the
4375 body of the @code{let}, the Lisp interpreter does not see the values of
4376 the variables of the same names that are bound outside of the
4377 @code{let}.
4379 @need 1250
4380 For example,
4382 @smallexample
4383 @group
4384 (let ((foo (buffer-name))
4385       (bar (buffer-size)))
4386   (message
4387    "This buffer is %s and has %d characters."
4388    foo bar))
4389 @end group
4390 @end smallexample
4392 @item save-excursion
4393 Record the values of point and mark and the current buffer before
4394 evaluating the body of this special form.  Restore the values of point
4395 and mark and buffer afterward.
4397 @need 1250
4398 For example,
4400 @smallexample
4401 @group
4402 (message "We are %d characters into this buffer."
4403          (- (point)
4404             (save-excursion
4405               (goto-char (point-min)) (point))))
4406 @end group
4407 @end smallexample
4409 @item if
4410 Evaluate the first argument to the function; if it is true, evaluate
4411 the second argument; else evaluate the third argument, if there is one.
4413 The @code{if} special form is called a @dfn{conditional}.  There are
4414 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
4415 commonly used.
4417 @need 1250
4418 For example,
4420 @smallexample
4421 @group
4422 (if (string-equal
4423      (number-to-string 21)
4424      (substring (emacs-version) 10 12))
4425     (message "This is version 21 Emacs")
4426   (message "This is not version 21 Emacs"))
4427 @end group
4428 @end smallexample
4430 @item equal
4431 @itemx eq
4432 Test whether two objects are the same.  @code{equal} uses one meaning
4433 of the word `same' and @code{eq} uses another:  @code{equal} returns
4434 true if the two objects have a similar structure and contents, such as
4435 two copies of the same book.  On the other hand, @code{eq}, returns
4436 true if both arguments are actually the same object.
4437 @findex equal
4438 @findex eq
4440 @need 1250
4441 @item <
4442 @itemx >
4443 @itemx <=
4444 @itemx >=
4445 The @code{<} function tests whether its first argument is smaller than
4446 its second argument.  A corresponding function, @code{>}, tests whether
4447 the first argument is greater than the second.  Likewise, @code{<=}
4448 tests whether the first argument is less than or equal to the second and
4449 @code{>=} tests whether the first argument is greater than or equal to
4450 the second.  In all cases, both arguments must be numbers or markers
4451 (markers indicate positions in buffers).
4453 @item string<
4454 @itemx string-lessp
4455 @itemx string=
4456 @itemx string-equal
4457 The @code{string-lessp} function tests whether its first argument is
4458 smaller than the second argument.  A shorter, alternative name for the
4459 same function (a @code{defalias}) is @code{string<}.
4461 The arguments to @code{string-lessp} must be strings or symbols; the
4462 ordering is lexicographic, so case is significant.  The print names of
4463 symbols are used instead of the symbols themselves.
4465 @cindex @samp{empty string} defined
4466 An empty string, @samp{""}, a string with no characters in it, is
4467 smaller than any string of characters.
4469 @code{string-equal} provides the corresponding test for equality.  Its
4470 shorter, alternative name is @code{string=}.  There are no string test
4471 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
4473 @item message
4474 Print a message in the echo area. The first argument is a string that
4475 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
4476 arguments that follow the string.  The argument used by @samp{%s} must
4477 be a string or a symbol; the argument used by @samp{%d} must be a
4478 number.  The argument used by @samp{%c} must be an @sc{ascii} code
4479 number; it will be printed as the character with that @sc{ascii} code.
4481 @item setq
4482 @itemx set
4483 The @code{setq} function sets the value of its first argument to the
4484 value of the second argument.  The first argument is automatically
4485 quoted by @code{setq}.  It does the same for succeeding pairs of
4486 arguments.  Another function, @code{set}, takes only two arguments and
4487 evaluates both of them before setting the value returned by its first
4488 argument to the value returned by its second argument.
4490 @item buffer-name
4491 Without an argument, return the name of the buffer, as a string.
4493 @itemx buffer-file-name
4494 Without an argument, return the name of the file the buffer is
4495 visiting.
4497 @item current-buffer
4498 Return the buffer in which Emacs is active; it may not be
4499 the buffer that is visible on the screen.
4501 @item other-buffer
4502 Return the most recently selected buffer (other than the buffer passed
4503 to @code{other-buffer} as an argument and other than the current
4504 buffer).
4506 @item switch-to-buffer
4507 Select a buffer for Emacs to be active in and display it in the current
4508 window so users can look at it.  Usually bound to @kbd{C-x b}.
4510 @item set-buffer
4511 Switch Emacs' attention to a buffer on which programs will run.  Don't
4512 alter what the window is showing.
4514 @item buffer-size
4515 Return the number of characters in the current buffer.
4517 @item point
4518 Return the value of the current position of the cursor, as an
4519 integer counting the number of characters from the beginning of the
4520 buffer.
4522 @item point-min
4523 Return the minimum permissible value of point in
4524 the current buffer.  This is 1, unless narrowing is in effect.
4526 @item point-max
4527 Return the value of the maximum permissible value of point in the
4528 current buffer.  This is the end of the buffer, unless narrowing is in
4529 effect.
4530 @end table
4532 @need 1500
4533 @node defun Exercises,  , Review, Writing Defuns
4534 @section Exercises
4536 @itemize @bullet
4537 @item
4538 Write a non-interactive function that doubles the value of its
4539 argument, a number.  Make that function interactive.
4541 @item
4542 Write a function that tests whether the current value of
4543 @code{fill-column} is greater than the argument passed to the function,
4544 and if so, prints an appropriate message.
4545 @end itemize
4547 @node Buffer Walk Through, More Complex, Writing Defuns, Top
4548 @comment  node-name,  next,  previous,  up
4549 @chapter A Few Buffer--Related Functions
4551 In this chapter we study in detail several of the functions used in GNU
4552 Emacs.  This is called a ``walk-through''.  These functions are used as
4553 examples of Lisp code, but are not imaginary examples; with the
4554 exception of the first, simplified function definition, these functions
4555 show the actual code used in GNU Emacs.  You can learn a great deal from
4556 these definitions.  The functions described here are all related to
4557 buffers.  Later, we will study other functions.
4559 @menu
4560 * Finding More::                How to find more information.
4561 * simplified-beginning-of-buffer::  Shows @code{goto-char},
4562                                 @code{point-min}, and @code{push-mark}.
4563 * mark-whole-buffer::           Almost the same as @code{beginning-of-buffer}.
4564 * append-to-buffer::            Uses @code{save-excursion} and
4565                                 @code{insert-buffer-substring}.
4566 * Buffer Related Review::       Review.
4567 * Buffer Exercises::
4568 @end menu
4570 @node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
4571 @section Finding More Information
4573 @findex describe-function, @r{introduced}
4574 @cindex Find function documentation
4575 In this walk-through, I will describe each new function as we come to
4576 it, sometimes in detail and sometimes briefly.  If you are interested,
4577 you can get the full documentation of any Emacs Lisp function at any
4578 time by typing @kbd{C-h f} and then the name of the function (and then
4579 @key{RET}).  Similarly, you can get the full documentation for a
4580 variable by typing @kbd{C-h v} and then the name of the variable (and
4581 then @key{RET}).
4583 @cindex Find source of function
4584 In versions 20 and higher, when a function is written in Emacs Lisp,
4585 @code{describe-function} will also tell you the location of the
4586 function definition.  If you move point over the file name and press
4587 the @key{RET} key, which in this case means @code{help-follow} rather
4588 than `return' or `enter', Emacs will take you directly to the function
4589 definition.
4591 More generally, if you want to see a function in its original source
4592 file, you can use the @code{find-tags} function to jump to it.
4593 @code{find-tags} works with a wide variety of languages, not just
4594 Lisp, and C, and it works with non-programming text as well.  For
4595 example, @code{find-tags} will jump to the various nodes in the
4596 Texinfo source file of this document.
4598 The @code{find-tags} function depends on `tags tables' that record
4599 the locations of the functions, variables, and other items to which
4600 @code{find-tags} jumps.
4602 To use the @code{find-tags} command, type @kbd{M-.}  (i.e., press the
4603 period key while holding down the @key{META} key, or else type the
4604 @key{ESC} key and then type the period key), and then, at the prompt,
4605 type in the name of the function whose source code you want to see,
4606 such as @code{mark-whole-buffer}, and then type @key{RET}.  Emacs will
4607 switch buffers and display the source code for the function on your
4608 screen.  To switch back to your current buffer, type @kbd{C-x b
4609 @key{RET}}.  (On some keyboards, the @key{META} key is labelled
4610 @key{ALT}.)
4612 @c !!! 21.0.100 tags table location in this paragraph
4613 @cindex TAGS table, specifying
4614 @findex find-tags
4615 Depending on how the initial default values of your copy of Emacs are
4616 set, you may also need to specify the location of your `tags table',
4617 which is a file called @file{TAGS}.  For example, if you are
4618 interested in Emacs sources, the tags table you will most likely want,
4619 if it has already been created for you, will be in a subdirectory of
4620 the @file{/usr/local/share/emacs/} directory; thus you would use the
4621 @code{M-x visit-tags-table} command and specify a pathname such as
4622 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or
4623 @file{/usr/local/src/emacs/src/TAGS}.  If the tags table has
4624 not already been created, you will have to create it yourself.
4626 @need 1250
4627 To create a @file{TAGS} file in a specific directory, switch to that
4628 directory in Emacs using @kbd{M-x cd} command, or list the directory
4629 with @kbd{C-x d} (@code{dired}).  Then run the compile command, with
4630 @w{@code{etags *.el}} as the command to execute
4632 @smallexample
4633 M-x compile RET etags *.el RET
4634 @end smallexample
4636 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
4638 After you become more familiar with Emacs Lisp, you will find that you will
4639 frequently use @code{find-tags} to navigate your way around source code;
4640 and you will create your own @file{TAGS} tables.
4642 @cindex Library, as term for `file'
4643 Incidentally, the files that contain Lisp code are conventionally
4644 called @dfn{libraries}.  The metaphor is derived from that of a
4645 specialized library, such as a law library or an engineering library,
4646 rather than a general library.  Each library, or file, contains
4647 functions that relate to a particular topic or activity, such as
4648 @file{abbrev.el} for handling abbreviations and other typing
4649 shortcuts, and @file{help.el} for on-line help.  (Sometimes several
4650 libraries provide code for a single activity, as the various
4651 @file{rmail@dots{}} files provide code for reading electronic mail.)
4652 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
4653 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
4654 by topic keywords.''
4656 @node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through
4657 @comment  node-name,  next,  previous,  up
4658 @section A Simplified @code{beginning-of-buffer} Definition
4659 @findex simplified-beginning-of-buffer
4661 The @code{beginning-of-buffer} command is a good function to start with
4662 since you are likely to be familiar with it and it is easy to
4663 understand.  Used as an interactive command, @code{beginning-of-buffer}
4664 moves the cursor to the beginning of the buffer, leaving the mark at the
4665 previous position.  It is generally bound to @kbd{M-<}.
4667 In this section, we will discuss a shortened version of the function
4668 that shows how it is most frequently used.  This shortened function
4669 works as written, but it does not contain the code for a complex option.
4670 In another section, we will describe the entire function.
4671 (@xref{beginning-of-buffer, , Complete Definition of
4672 @code{beginning-of-buffer}}.)
4674 Before looking at the code, let's consider what the function
4675 definition has to contain: it must include an expression that makes
4676 the function interactive so it can be called by typing @kbd{M-x
4677 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
4678 must include code to leave a mark at the original position in the
4679 buffer; and it must include code to move the cursor to the beginning
4680 of the buffer.
4682 @need 1250
4683 Here is the complete text of the shortened version of the function:
4685 @smallexample
4686 @group
4687 (defun simplified-beginning-of-buffer ()
4688   "Move point to the beginning of the buffer;
4689 leave mark at previous position."
4690   (interactive)
4691   (push-mark)
4692   (goto-char (point-min)))
4693 @end group
4694 @end smallexample
4696 Like all function definitions, this definition has five parts following
4697 the special form @code{defun}:
4699 @enumerate
4700 @item
4701 The name: in this example, @code{simplified-beginning-of-buffer}.
4703 @item
4704 A list of the arguments: in this example, an empty list, @code{()},
4706 @item
4707 The documentation string.
4709 @item
4710 The interactive expression.
4712 @item
4713 The body.
4714 @end enumerate
4716 @noindent
4717 In this function definition, the argument list is empty; this means that
4718 this function does not require any arguments.  (When we look at the
4719 definition for the complete function, we will see that it may be passed
4720 an optional argument.)
4722 The interactive expression tells Emacs that the function is intended to
4723 be used interactively.  In this example, @code{interactive} does not have
4724 an argument because @code{simplified-beginning-of-buffer} does not
4725 require one.
4727 @need 800
4728 The body of the function consists of the two lines:
4730 @smallexample
4731 @group
4732 (push-mark)
4733 (goto-char (point-min))
4734 @end group
4735 @end smallexample
4737 The first of these lines is the expression, @code{(push-mark)}.  When
4738 this expression is evaluated by the Lisp interpreter, it sets a mark at
4739 the current position of the cursor, wherever that may be.  The position
4740 of this mark is saved in the mark ring.
4742 The next line is @code{(goto-char (point-min))}.  This expression
4743 jumps the cursor to the minimum point in the buffer, that is, to the
4744 beginning of the buffer (or to the beginning of the accessible portion
4745 of the buffer if it is narrowed.  @xref{Narrowing & Widening, ,
4746 Narrowing and Widening}.)
4748 The @code{push-mark} command sets a mark at the place where the cursor
4749 was located before it was moved to the beginning of the buffer by the
4750 @code{(goto-char (point-min))} expression.  Consequently, you can, if
4751 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
4753 That is all there is to the function definition!
4755 @findex describe-function
4756 When you are reading code such as this and come upon an unfamiliar
4757 function, such as @code{goto-char}, you can find out what it does by
4758 using the @code{describe-function} command.  To use this command, type
4759 @kbd{C-h f} and then type in the name of the function and press
4760 @key{RET}.  The @code{describe-function} command will print the
4761 function's documentation string in a @file{*Help*} window.  For
4762 example, the documentation for @code{goto-char} is:
4764 @smallexample
4765 @group
4766 One arg, a number.  Set point to that number.
4767 Beginning of buffer is position (point-min),
4768 end is (point-max).
4769 @end group
4770 @end smallexample
4772 @noindent
4773 (The prompt for @code{describe-function} will offer you the symbol
4774 under or preceding the cursor, so you can save typing by positioning
4775 the cursor right over or after the function and then typing @kbd{C-h f
4776 @key{RET}}.)
4778 The @code{end-of-buffer} function definition is written in the same way as
4779 the @code{beginning-of-buffer} definition except that the body of the
4780 function contains the expression @code{(goto-char (point-max))} in place
4781 of @code{(goto-char (point-min))}.
4783 @node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through
4784 @comment  node-name,  next,  previous,  up
4785 @section The Definition of @code{mark-whole-buffer}
4786 @findex mark-whole-buffer
4788 The @code{mark-whole-buffer} function is no harder to understand than the
4789 @code{simplified-beginning-of-buffer} function.  In this case, however,
4790 we will look at the complete function, not a shortened version.
4792 The @code{mark-whole-buffer} function is not as commonly used as the
4793 @code{beginning-of-buffer} function, but is useful nonetheless: it
4794 marks a whole buffer as a region by putting point at the beginning and
4795 a mark at the end of the buffer.  It is generally bound to @kbd{C-x
4799 @menu
4800 * mark-whole-buffer overview::
4801 * Body of mark-whole-buffer::   Only three lines of code.
4802 @end menu
4805 @node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
4806 @ifnottex
4807 @unnumberedsubsec An overview of @code{mark-whole-buffer}
4808 @end ifnottex
4810 @need 1250
4811 In GNU Emacs 20, the code for the complete function looks like this:
4813 @smallexample
4814 @group
4815 (defun mark-whole-buffer ()
4816   "Put point at beginning and mark at end of buffer."
4817   (interactive)
4818   (push-mark (point))
4819   (push-mark (point-max))
4820   (goto-char (point-min)))
4821 @end group
4822 @end smallexample
4824 @need 1250
4825 Like all other functions, the @code{mark-whole-buffer} function fits
4826 into the template for a function definition.  The template looks like
4827 this:
4829 @smallexample
4830 @group
4831 (defun @var{name-of-function} (@var{argument-list})
4832   "@var{documentation}@dots{}"
4833   (@var{interactive-expression}@dots{})
4834   @var{body}@dots{})
4835 @end group
4836 @end smallexample
4838 Here is how the function works: the name of the function is
4839 @code{mark-whole-buffer}; it is followed by an empty argument list,
4840 @samp{()}, which means that the function does not require arguments.
4841 The documentation comes next.
4843 The next line is an @code{(interactive)} expression that tells Emacs
4844 that the function will be used interactively.  These details are similar
4845 to the @code{simplified-beginning-of-buffer} function described in the
4846 previous section.
4848 @need 1250
4849 @node Body of mark-whole-buffer,  , mark-whole-buffer overview, mark-whole-buffer
4850 @comment  node-name,  next,  previous,  up
4851 @subsection Body of @code{mark-whole-buffer}
4853 The body of the @code{mark-whole-buffer} function consists of three
4854 lines of code:
4856 @smallexample
4857 @group
4858 (push-mark (point))
4859 (push-mark (point-max))
4860 (goto-char (point-min))
4861 @end group
4862 @end smallexample
4864 The first of these lines is the expression, @code{(push-mark (point))}.
4866 This line does exactly the same job as the first line of the body of
4867 the @code{simplified-beginning-of-buffer} function, which is written
4868 @code{(push-mark)}.  In both cases, the Lisp interpreter sets a mark
4869 at the current position of the cursor.
4871 I don't know why the expression in @code{mark-whole-buffer} is written
4872 @code{(push-mark (point))} and the expression in
4873 @code{beginning-of-buffer} is written @code{(push-mark)}.  Perhaps
4874 whoever wrote the code did not know that the arguments for
4875 @code{push-mark} are optional and that if @code{push-mark} is not
4876 passed an argument, the function automatically sets mark at the
4877 location of point by default.  Or perhaps the expression was written
4878 so as to parallel the structure of the next line.  In any case, the
4879 line causes Emacs to determine the position of point and set a mark
4880 there.
4882 The next line of @code{mark-whole-buffer} is @code{(push-mark (point-max)}.
4883 This expression sets a mark at the point in the buffer
4884 that has the highest number.  This will be the end of the buffer (or,
4885 if the buffer is narrowed, the end of the accessible portion of the
4886 buffer.  @xref{Narrowing & Widening, , Narrowing and Widening}, for
4887 more about narrowing.)  After this mark has been set, the previous
4888 mark, the one set at point, is no longer set, but Emacs remembers its
4889 position, just as all other recent marks are always remembered.  This
4890 means that you can, if you wish, go back to that position by typing
4891 @kbd{C-u C-@key{SPC}} twice.
4893 (In GNU Emacs 21, the @code{(push-mark (point-max)} is slightly more
4894 complicated than shown here.  The line reads
4896 @smallexample
4897 (push-mark (point-max) nil t)
4898 @end smallexample
4900 @noindent
4901 (The expression works nearly the same as before.  It sets a mark at
4902 the highest numbered place in the buffer that it can.  However, in
4903 this version, @code{push-mark} has two additional arguments.  The
4904 second argument to @code{push-mark} is @code{nil}.  This tells the
4905 function it @emph{should} display a message that says `Mark set' when
4906 it pushes the mark.  The third argument is @code{t}.  This tells
4907 @code{push-mark} to activate the mark when Transient Mark mode is
4908 turned on.  Transient Mark mode highlights the currently active
4909 region.  It is usually turned off.)
4911 Finally, the last line of the function is @code{(goto-char
4912 (point-min)))}.  This is written exactly the same way as it is written
4913 in @code{beginning-of-buffer}.  The expression moves the cursor to
4914 the minimum point in the buffer, that is, to the beginning of the buffer
4915 (or to the beginning of the accessible portion of the buffer).  As a
4916 result of this, point is placed at the beginning of the buffer and mark
4917 is set at the end of the buffer.  The whole buffer is, therefore, the
4918 region.
4920 @node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through
4921 @comment  node-name,  next,  previous,  up
4922 @section The Definition of @code{append-to-buffer}
4923 @findex append-to-buffer
4925 The @code{append-to-buffer} command is very nearly as simple as the
4926 @code{mark-whole-buffer} command.  What it does is copy the region (that
4927 is, the part of the buffer between point and mark) from the current
4928 buffer to a specified buffer.
4930 @menu
4931 * append-to-buffer overview::
4932 * append interactive::          A two part interactive expression.
4933 * append-to-buffer body::       Incorporates a @code{let} expression.
4934 * append save-excursion::       How the @code{save-excursion} works.
4935 @end menu
4937 @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
4938 @ifnottex
4939 @unnumberedsubsec An Overview of @code{append-to-buffer}
4940 @end ifnottex
4942 @findex insert-buffer-substring
4943 The @code{append-to-buffer} command uses the
4944 @code{insert-buffer-substring} function to copy the region.
4945 @code{insert-buffer-substring} is described by its name: it takes a
4946 string of characters from part of a buffer, a ``substring'', and
4947 inserts them into another buffer.  Most of @code{append-to-buffer} is
4948 concerned with setting up the conditions for
4949 @code{insert-buffer-substring} to work: the code must specify both the
4950 buffer to which the text will go and the region that will be copied.
4951 Here is the complete text of the function:
4953 @smallexample
4954 @group
4955 (defun append-to-buffer (buffer start end)
4956   "Append to specified buffer the text of the region.
4957 It is inserted into that buffer before its point.
4958 @end group
4960 @group
4961 When calling from a program, give three arguments:
4962 a buffer or the name of one, and two character numbers
4963 specifying the portion of the current buffer to be copied."
4964   (interactive "BAppend to buffer:@: \nr")
4965   (let ((oldbuf (current-buffer)))
4966     (save-excursion
4967       (set-buffer (get-buffer-create buffer))
4968       (insert-buffer-substring oldbuf start end))))
4969 @end group
4970 @end smallexample
4972 The function can be understood by looking at it as a series of
4973 filled-in templates.
4975 The outermost template is for the function definition.  In this
4976 function, it looks like this (with several slots filled in):
4978 @smallexample
4979 @group
4980 (defun append-to-buffer (buffer start end)
4981   "@var{documentation}@dots{}"
4982   (interactive "BAppend to buffer:@: \nr")
4983   @var{body}@dots{})
4984 @end group
4985 @end smallexample
4987 The first line of the function includes its name and three arguments.
4988 The arguments are the @code{buffer} to which the text will be copied, and
4989 the @code{start} and @code{end} of the region in the current buffer that
4990 will be copied.
4992 The next part of the function is the documentation, which is clear and
4993 complete.
4995 @node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
4996 @comment  node-name,  next,  previous,  up
4997 @subsection The @code{append-to-buffer} Interactive Expression
4999 Since the @code{append-to-buffer} function will be used interactively,
5000 the function must have an @code{interactive} expression.  (For a
5001 review of @code{interactive}, see @ref{Interactive, , Making a
5002 Function Interactive}.)  The expression reads as follows:
5004 @smallexample
5005 (interactive "BAppend to buffer:@: \nr")
5006 @end smallexample
5008 @noindent
5009 This expression has an argument inside of quotation marks and that
5010 argument has two parts, separated by @samp{\n}.
5012 The first part is @samp{BAppend to buffer:@: }.  Here, the @samp{B}
5013 tells Emacs to ask for the name of the buffer that will be passed to the
5014 function.  Emacs will ask for the name by prompting the user in the
5015 minibuffer, using the string following the @samp{B}, which is the string
5016 @samp{Append to buffer:@: }.  Emacs then binds the variable @code{buffer}
5017 in the function's argument list to the specified buffer.
5019 The newline, @samp{\n}, separates the first part of the argument from
5020 the second part.  It is followed by an @samp{r} that tells Emacs to bind
5021 the two arguments that follow the symbol @code{buffer} in the function's
5022 argument list (that is, @code{start} and @code{end}) to the values of
5023 point and mark.
5025 @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
5026 @comment  node-name,  next,  previous,  up
5027 @subsection The Body of @code{append-to-buffer}
5029 The body of the @code{append-to-buffer} function begins with @code{let}.
5031 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
5032 @code{let} expression is to create and give initial values to one or
5033 more variables that will only be used within the body of the
5034 @code{let}.  This means that such a variable will not be confused with
5035 any variable of the same name outside the @code{let} expression.
5037 We can see how the @code{let} expression fits into the function as a
5038 whole by showing a template for @code{append-to-buffer} with the
5039 @code{let} expression in outline:
5041 @smallexample
5042 @group
5043 (defun append-to-buffer (buffer start end)
5044   "@var{documentation}@dots{}"
5045   (interactive "BAppend to buffer:@: \nr")
5046   (let ((@var{variable} @var{value}))
5047         @var{body}@dots{})
5048 @end group
5049 @end smallexample
5051 The @code{let} expression has three elements:
5053 @enumerate
5054 @item
5055 The symbol @code{let};
5057 @item
5058 A varlist containing, in this case, a single two-element list,
5059 @code{(@var{variable} @var{value})};
5061 @item
5062 The body of the @code{let} expression.
5063 @end enumerate
5065 @need 800
5066 In the @code{append-to-buffer} function, the varlist looks like this:
5068 @smallexample
5069 (oldbuf (current-buffer))
5070 @end smallexample
5072 @noindent
5073 In this part of the @code{let} expression, the one variable,
5074 @code{oldbuf}, is bound to the value returned by the
5075 @code{(current-buffer)} expression.  The variable, @code{oldbuf}, is
5076 used to keep track of the buffer in which you are working and from
5077 which you will copy.
5079 The element or elements of a varlist are surrounded by a set of
5080 parentheses so the Lisp interpreter can distinguish the varlist from
5081 the body of the @code{let}.  As a consequence, the two-element list
5082 within the varlist is surrounded by a circumscribing set of parentheses.
5083 The line looks like this:
5085 @smallexample
5086 @group
5087 (let ((oldbuf (current-buffer)))
5088   @dots{} )
5089 @end group
5090 @end smallexample
5092 @noindent
5093 The two parentheses before @code{oldbuf} might surprise you if you did
5094 not realize that the first parenthesis before @code{oldbuf} marks the
5095 boundary of the varlist and the second parenthesis marks the beginning
5096 of the two-element list, @code{(oldbuf (current-buffer))}.
5098 @node append save-excursion,  , append-to-buffer body, append-to-buffer
5099 @comment  node-name,  next,  previous,  up
5100 @subsection @code{save-excursion} in @code{append-to-buffer}
5102 The body of the @code{let} expression in @code{append-to-buffer}
5103 consists of a @code{save-excursion} expression.
5105 The @code{save-excursion} function saves the locations of point and
5106 mark, and restores them to those positions after the expressions in the
5107 body of the @code{save-excursion} complete execution.  In addition,
5108 @code{save-excursion} keeps track of the original buffer, and
5109 restores it.  This is how @code{save-excursion} is used in
5110 @code{append-to-buffer}.
5112 @need 1500
5113 @cindex Indentation for formatting
5114 @cindex Formatting convention
5115 Incidentally, it is worth noting here that a Lisp function is normally
5116 formatted so that everything that is enclosed in a multi-line spread is
5117 indented more to the right than the first symbol.  In this function
5118 definition, the @code{let} is indented more than the @code{defun}, and
5119 the @code{save-excursion} is indented more than the @code{let}, like
5120 this:
5122 @smallexample
5123 @group
5124 (defun @dots{}
5125   @dots{}
5126   @dots{}
5127   (let@dots{}
5128     (save-excursion
5129       @dots{}
5130 @end group
5131 @end smallexample
5133 @need 1500
5134 @noindent
5135 This formatting convention makes it easy to see that the two lines in
5136 the body of the @code{save-excursion} are enclosed by the parentheses
5137 associated with @code{save-excursion}, just as the
5138 @code{save-excursion} itself is enclosed by the parentheses associated
5139 with the @code{let}:
5141 @smallexample
5142 @group
5143 (let ((oldbuf (current-buffer)))
5144   (save-excursion
5145     (set-buffer (get-buffer-create buffer))
5146     (insert-buffer-substring oldbuf start end))))
5147 @end group
5148 @end smallexample
5150 @need 1200
5151 The use of the @code{save-excursion} function can be viewed as a process
5152 of filling in the slots of a template:
5154 @smallexample
5155 @group
5156 (save-excursion
5157   @var{first-expression-in-body}
5158   @var{second-expression-in-body}
5159    @dots{}
5160   @var{last-expression-in-body})
5161 @end group
5162 @end smallexample
5164 @need 1200
5165 @noindent
5166 In this function, the body of the @code{save-excursion} contains only
5167 two expressions.  The body looks like this:
5169 @smallexample
5170 @group
5171 (set-buffer (get-buffer-create buffer))
5172 (insert-buffer-substring oldbuf start end)
5173 @end group
5174 @end smallexample
5176 When the @code{append-to-buffer} function is evaluated, the two
5177 expressions in the body of the @code{save-excursion} are evaluated in
5178 sequence.  The value of the last expression is returned as the value of
5179 the @code{save-excursion} function; the other expression is evaluated
5180 only for its side effects.
5182 The first line in the body of the @code{save-excursion} uses the
5183 @code{set-buffer} function to change the current buffer to the one
5184 specified in the first argument to @code{append-to-buffer}.  (Changing
5185 the buffer is the side effect; as we have said before, in Lisp, a side
5186 effect is often the primary thing we want.)  The second line does the
5187 primary work of the function.
5189 The @code{set-buffer} function changes Emacs' attention to the buffer to
5190 which the text will be copied and from which @code{save-excursion} will
5191 return.
5193 @need 800
5194 The line looks like this:
5196 @smallexample
5197 (set-buffer (get-buffer-create buffer))
5198 @end smallexample
5200 The innermost expression of this list is @code{(get-buffer-create
5201 buffer)}.  This expression uses the @code{get-buffer-create} function,
5202 which either gets the named buffer, or if it does not exist, creates one
5203 with the given name.  This means you can use @code{append-to-buffer} to
5204 put text into a buffer that did not previously exist.
5206 @code{get-buffer-create} also keeps @code{set-buffer} from getting an
5207 unnecessary error: @code{set-buffer} needs a buffer to go to; if you
5208 were to specify a buffer that does not exist, Emacs would baulk.
5209 Since @code{get-buffer-create} will create a buffer if none exists,
5210 @code{set-buffer} is always provided with a buffer.
5212 @need 1250
5213 The last line of @code{append-to-buffer} does the work of appending
5214 the text:
5216 @smallexample
5217 (insert-buffer-substring oldbuf start end)
5218 @end smallexample
5220 @noindent
5221 The @code{insert-buffer-substring} function copies a string @emph{from}
5222 the buffer specified as its first argument and inserts the string into
5223 the present buffer.  In this case, the argument to
5224 @code{insert-buffer-substring} is the value of the variable created and
5225 bound by the @code{let}, namely the value of @code{oldbuf}, which was
5226 the current buffer when you gave the @code{append-to-buffer} command.
5228 After @code{insert-buffer-substring} has done its work,
5229 @code{save-excursion} will restore the action to the original buffer and
5230 @code{append-to-buffer} will have done its job.
5232 @need 800
5233 Written in skeletal form, the workings of the body look like this:
5235 @smallexample
5236 @group
5237 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5238   (save-excursion                       ; @r{Keep track of buffer.}
5239     @var{change-buffer}
5240     @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
5242   @var{change-back-to-original-buffer-when-finished}
5243 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
5245 @end group
5246 @end smallexample
5248 In summary, @code{append-to-buffer} works as follows: it saves the value
5249 of the current buffer in the variable called @code{oldbuf}.  It gets the
5250 new buffer, creating one if need be, and switches Emacs to it.  Using
5251 the value of @code{oldbuf}, it inserts the region of text from the old
5252 buffer into the new buffer; and then using @code{save-excursion}, it
5253 brings you back to your original buffer.
5255 In looking at @code{append-to-buffer}, you have explored a fairly
5256 complex function.  It shows how to use @code{let} and
5257 @code{save-excursion}, and how to change to and come back from another
5258 buffer.  Many function definitions use @code{let},
5259 @code{save-excursion}, and @code{set-buffer} this way.
5261 @node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through
5262 @comment  node-name,  next,  previous,  up
5263 @section Review
5265 Here is a brief summary of the various functions discussed in this chapter.
5267 @table @code
5268 @item describe-function
5269 @itemx describe-variable
5270 Print the documentation for a function or variable.
5271 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
5273 @item find-tag
5274 Find the file containing the source for a function or variable and
5275 switch buffers to it, positioning point at the beginning of the item.
5276 Conventionally bound to @kbd{M-.} (that's a period following the
5277 @key{META} key).
5279 @item save-excursion
5280 Save the location of point and mark and restore their values after the
5281 arguments to @code{save-excursion} have been evaluated.  Also, remember
5282 the current buffer and return to it.
5284 @item push-mark
5285 Set mark at a location and record the value of the previous mark on the
5286 mark ring.  The mark is a location in the buffer that will keep its
5287 relative position even if text is added to or removed from the buffer.
5289 @item goto-char
5290 Set point to the location specified by the value of the argument, which
5291 can be a number, a marker,  or an expression that returns the number of
5292 a position, such as @code{(point-min)}.
5294 @item insert-buffer-substring
5295 Copy a region of text from a buffer that is passed to the function as
5296 an argument and insert the region into the current buffer.
5298 @item mark-whole-buffer
5299 Mark the whole buffer as a region.  Normally bound to @kbd{C-x h}.
5301 @item set-buffer
5302 Switch the attention of Emacs to another buffer, but do not change the
5303 window being displayed.  Used when the program rather than a human is
5304 to work on a different buffer.
5306 @item get-buffer-create
5307 @itemx get-buffer
5308 Find a named buffer or create one if a buffer of that name does not
5309 exist.  The @code{get-buffer} function returns @code{nil} if the named
5310 buffer does not exist.
5311 @end table
5313 @need 1500
5314 @node Buffer Exercises,  , Buffer Related Review, Buffer Walk Through
5315 @section Exercises
5317 @itemize @bullet
5318 @item
5319 Write your own @code{simplified-end-of-buffer} function definition;
5320 then test it to see whether it works.
5322 @item
5323 Use @code{if} and @code{get-buffer} to write a function that prints a
5324 message telling you whether a buffer exists.
5326 @item
5327 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
5328 function.
5329 @end itemize
5331 @node More Complex, Narrowing & Widening, Buffer Walk Through, Top
5332 @comment  node-name,  next,  previous,  up
5333 @chapter A Few More Complex Functions
5335 In this chapter, we build on what we have learned in previous chapters
5336 by looking at more complex functions.  The @code{copy-to-buffer}
5337 function illustrates use of two @code{save-excursion} expressions in
5338 one definition, while the @code{insert-buffer} function illustrates
5339 use of an asterisk in an @code{interactive} expression, use of
5340 @code{or}, and the important distinction between a name and the object
5341 to which the name refers.
5343 @menu
5344 * copy-to-buffer::              With @code{set-buffer}, @code{get-buffer-create}.
5345 * insert-buffer::               Read-only, and with @code{or}.
5346 * beginning-of-buffer::         Shows @code{goto-char},
5347                                 @code{point-min}, and @code{push-mark}.
5348 * Second Buffer Related Review::
5349 * optional Exercise::
5350 @end menu
5352 @node copy-to-buffer, insert-buffer, More Complex, More Complex
5353 @comment  node-name,  next,  previous,  up
5354 @section The Definition of @code{copy-to-buffer}
5355 @findex copy-to-buffer
5357 After understanding how @code{append-to-buffer} works, it is easy to
5358 understand @code{copy-to-buffer}.  This function copies text into a
5359 buffer, but instead of adding to the second buffer, it replaces the
5360 previous text in the second buffer.  The code for the
5361 @code{copy-to-buffer} function is almost the same as the code for
5362 @code{append-to-buffer}, except that @code{erase-buffer} and a second
5363 @code{save-excursion} are used.  (@xref{append-to-buffer, , The
5364 Definition of @code{append-to-buffer}}, for the description of
5365 @code{append-to-buffer}.)
5367 @need 800
5368 The body of @code{copy-to-buffer} looks like this
5370 @smallexample
5371 @group
5372 @dots{}
5373 (interactive "BCopy to buffer:@: \nr")
5374   (let ((oldbuf (current-buffer)))
5375     (save-excursion
5376       (set-buffer (get-buffer-create buffer))
5377       (erase-buffer)
5378       (save-excursion
5379         (insert-buffer-substring oldbuf start end)))))
5380 @end group
5381 @end smallexample
5383 This code is similar to the code in @code{append-to-buffer}: it is
5384 only after changing to the buffer to which the text will be copied
5385 that the definition for this function diverges from the definition for
5386 @code{append-to-buffer}: the @code{copy-to-buffer} function erases the
5387 buffer's former contents.  (This is what is meant by `replacement'; to
5388 replace text, Emacs erases the previous text and then inserts new
5389 text.)  After erasing the previous contents of the buffer,
5390 @code{save-excursion} is used for a second time and the new text is
5391 inserted.
5393 Why is @code{save-excursion} used twice?  Consider again what the
5394 function does.
5396 @need 1250
5397 In outline, the body of @code{copy-to-buffer} looks like this:
5399 @smallexample
5400 @group
5401 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5402   (save-excursion         ; @r{First use of @code{save-excursion}.}
5403     @var{change-buffer}
5404       (erase-buffer)
5405       (save-excursion     ; @r{Second use of @code{save-excursion}.}
5406         @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
5407 @end group
5408 @end smallexample
5410 The first use of @code{save-excursion} returns Emacs to the buffer from
5411 which the text is being copied.  That is clear, and is just like its use
5412 in @code{append-to-buffer}.  Why the second use?  The reason is that
5413 @code{insert-buffer-substring} always leaves point at the @emph{end} of
5414 the region being inserted.  The second @code{save-excursion} causes
5415 Emacs to leave point at the beginning of the text being inserted.  In
5416 most circumstances, users prefer to find point at the beginning of
5417 inserted text.  (Of course, the @code{copy-to-buffer} function returns
5418 the user to the original buffer when done---but if the user @emph{then}
5419 switches to the copied-to buffer, point will go to the beginning of the
5420 text.  Thus, this use of a second @code{save-excursion} is a little
5421 nicety.)
5423 @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
5424 @comment  node-name,  next,  previous,  up
5425 @section The Definition of @code{insert-buffer}
5426 @findex insert-buffer
5428 @code{insert-buffer} is yet another buffer-related function.  This
5429 command copies another buffer @emph{into} the current buffer.  It is the
5430 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
5431 copy a region of text @emph{from} the current buffer to another buffer.
5433 Here is a discussion based on the original code.  The code was
5434 simplified in 2003 and is harder to understand.
5436 In addition, this code illustrates the use of @code{interactive} with a
5437 buffer that might be @dfn{read-only} and the important distinction
5438 between the name of an object and the object actually referred to.
5440 @menu
5441 * insert-buffer code::
5442 * insert-buffer interactive::   When you can read, but not write.
5443 * insert-buffer body::          The body has an @code{or} and a @code{let}.
5444 * if & or::                     Using an @code{if} instead of an @code{or}.
5445 * Insert or::                   How the @code{or} expression works.
5446 * Insert let::                  Two @code{save-excursion} expressions.
5447 @end menu
5449 @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
5450 @ifnottex
5451 @unnumberedsubsec The Code for @code{insert-buffer}
5452 @end ifnottex
5454 @need 800
5455 Here is the code:
5457 @smallexample
5458 @group
5459 (defun insert-buffer (buffer)
5460   "Insert after point the contents of BUFFER.
5461 Puts mark after the inserted text.
5462 BUFFER may be a buffer or a buffer name."
5463   (interactive "*bInsert buffer:@: ")
5464 @end group
5465 @group
5466   (or (bufferp buffer)
5467       (setq buffer (get-buffer buffer)))
5468   (let (start end newmark)
5469     (save-excursion
5470       (save-excursion
5471         (set-buffer buffer)
5472         (setq start (point-min) end (point-max)))
5473 @end group
5474 @group
5475       (insert-buffer-substring buffer start end)
5476       (setq newmark (point)))
5477     (push-mark newmark)))
5478 @end group
5479 @end smallexample
5481 @need 1200
5482 As with other function definitions, you can use a template to see an
5483 outline of the function:
5485 @smallexample
5486 @group
5487 (defun insert-buffer (buffer)
5488   "@var{documentation}@dots{}"
5489   (interactive "*bInsert buffer:@: ")
5490   @var{body}@dots{})
5491 @end group
5492 @end smallexample
5494 @node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer
5495 @comment  node-name,  next,  previous,  up
5496 @subsection The Interactive Expression in @code{insert-buffer}
5497 @findex interactive, @r{example use of}
5499 In @code{insert-buffer}, the argument to the @code{interactive}
5500 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
5501 buffer:@: }.
5503 @menu
5504 * Read-only buffer::            When a buffer cannot be modified.
5505 * b for interactive::           An existing buffer or else its name.
5506 @end menu
5508 @node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
5509 @comment  node-name,  next,  previous,  up
5510 @unnumberedsubsubsec A Read-only Buffer
5511 @cindex Read-only buffer
5512 @cindex Asterisk for read-only buffer
5513 @findex * @r{for read-only buffer}
5515 The asterisk is for the situation when the current buffer is a
5516 read-only buffer---a buffer that cannot be modified.  If
5517 @code{insert-buffer} is called when the current buffer is read-only, a
5518 message to this effect is printed in the echo area and the terminal
5519 may beep or blink at you; you will not be permitted to insert anything
5520 into current buffer.  The asterisk does not need to be followed by a
5521 newline to separate it from the next argument.
5523 @node b for interactive,  , Read-only buffer, insert-buffer interactive
5524 @comment  node-name,  next,  previous,  up
5525 @unnumberedsubsubsec @samp{b} in an Interactive Expression
5527 The next argument in the interactive expression starts with a lower
5528 case @samp{b}.  (This is different from the code for
5529 @code{append-to-buffer}, which uses an upper-case @samp{B}.
5530 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
5531 The lower-case @samp{b} tells the Lisp interpreter that the argument
5532 for @code{insert-buffer} should be an existing buffer or else its
5533 name.  (The upper-case @samp{B} option provides for the possibility
5534 that the buffer does not exist.)  Emacs will prompt you for the name
5535 of the buffer, offering you a default buffer, with name completion
5536 enabled.  If the buffer does not exist, you receive a message that
5537 says ``No match''; your terminal may beep at you as well.
5539 @node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
5540 @comment  node-name,  next,  previous,  up
5541 @subsection The Body of the @code{insert-buffer} Function
5543 The body of the @code{insert-buffer} function has two major parts: an
5544 @code{or} expression and a @code{let} expression.  The purpose of the
5545 @code{or} expression is to ensure that the argument @code{buffer} is
5546 bound to a buffer and not just the name of a buffer.  The body of the
5547 @code{let} expression contains the code which copies the other buffer
5548 into the current buffer.
5550 @need 1250
5551 In outline, the two expressions fit into the @code{insert-buffer}
5552 function like this:
5554 @smallexample
5555 @group
5556 (defun insert-buffer (buffer)
5557   "@var{documentation}@dots{}"
5558   (interactive "*bInsert buffer:@: ")
5559   (or @dots{}
5560       @dots{}
5561 @end group
5562 @group
5563   (let (@var{varlist})
5564       @var{body-of-}@code{let}@dots{} )
5565 @end group
5566 @end smallexample
5568 To understand how the @code{or} expression ensures that the argument
5569 @code{buffer} is bound to a buffer and not to the name of a buffer, it
5570 is first necessary to understand the @code{or} function.
5572 Before doing this, let me rewrite this part of the function using
5573 @code{if} so that you can see what is done in a manner that will be familiar.
5575 @node if & or, Insert or, insert-buffer body, insert-buffer
5576 @comment  node-name,  next,  previous,  up
5577 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
5579 The job to be done is to make sure the value of @code{buffer} is a
5580 buffer itself and not the name of a buffer.  If the value is the name,
5581 then the buffer itself must be got.
5583 You can imagine yourself at a conference where an usher is wandering
5584 around holding a list with your name on it and looking for you: the
5585 usher is ``bound'' to your name, not to you; but when the usher finds
5586 you and takes your arm, the usher becomes ``bound'' to you.
5588 @need 800
5589 In Lisp, you might describe this situation like this:
5591 @smallexample
5592 @group
5593 (if (not (holding-on-to-guest))
5594     (find-and-take-arm-of-guest))
5595 @end group
5596 @end smallexample
5598 We want to do the same thing with a buffer---if we do not have the
5599 buffer itself, we want to get it.
5601 @need 1200
5602 Using a predicate called @code{bufferp} that tells us whether we have a
5603 buffer (rather than its name), we can write the code like this:
5605 @smallexample
5606 @group
5607 (if (not (bufferp buffer))              ; @r{if-part}
5608     (setq buffer (get-buffer buffer)))  ; @r{then-part}
5609 @end group
5610 @end smallexample
5612 @noindent
5613 Here, the true-or-false-test of the @code{if} expression is
5614 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
5615 @w{@code{(setq buffer (get-buffer buffer))}}.
5617 In the test, the function @code{bufferp} returns true if its argument is
5618 a buffer---but false if its argument is the name of the buffer.  (The
5619 last character of the function name @code{bufferp} is the character
5620 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
5621 indicates that the function is a predicate, which is a term that means
5622 that the function will determine whether some property is true or false.
5623 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
5624 Argument}.)
5626 @need 1200
5627 The function @code{not} precedes the expression @code{(bufferp buffer)},
5628 so the true-or-false-test looks like this:
5630 @smallexample
5631 (not (bufferp buffer))
5632 @end smallexample
5634 @noindent
5635 @code{not} is a function that returns true if its argument is false
5636 and false if its argument is true.  So if @code{(bufferp buffer)}
5637 returns true, the @code{not} expression returns false and vice-versa:
5638 what is ``not true'' is false and what is ``not false'' is true.
5640 Using this test, the @code{if} expression works as follows: when the
5641 value of the variable @code{buffer} is actually a buffer rather than
5642 its name, the true-or-false-test returns false and the @code{if}
5643 expression does not evaluate the then-part.  This is fine, since we do
5644 not need to do anything to the variable @code{buffer} if it really is
5645 a buffer.
5647 On the other hand, when the value of @code{buffer} is not a buffer
5648 itself, but the name of a buffer, the true-or-false-test returns true
5649 and the then-part of the expression is evaluated.  In this case, the
5650 then-part is @code{(setq buffer (get-buffer buffer))}.  This
5651 expression uses the @code{get-buffer} function to return an actual
5652 buffer itself, given its name.  The @code{setq} then sets the variable
5653 @code{buffer} to the value of the buffer itself, replacing its previous
5654 value (which was the name of the buffer).
5656 @node Insert or, Insert let, if & or, insert-buffer
5657 @comment  node-name,  next,  previous,  up
5658 @subsection The @code{or} in the Body
5660 The purpose of the @code{or} expression in the @code{insert-buffer}
5661 function is to ensure that the argument @code{buffer} is bound to a
5662 buffer and not just to the name of a buffer.  The previous section shows
5663 how the job could have been done using an @code{if} expression.
5664 However, the @code{insert-buffer} function actually uses @code{or}.
5665 To understand this, it is necessary to understand how @code{or} works.
5667 @findex or
5668 An @code{or} function can have any number of arguments.  It evaluates
5669 each argument in turn and returns the value of the first of its
5670 arguments that is not @code{nil}.  Also, and this is a crucial feature
5671 of @code{or}, it does not evaluate any subsequent arguments after
5672 returning the first non-@code{nil} value.
5674 @need 800
5675 The @code{or} expression looks like this:
5677 @smallexample
5678 @group
5679 (or (bufferp buffer)
5680     (setq buffer (get-buffer buffer)))
5681 @end group
5682 @end smallexample
5684 @noindent
5685 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
5686 This expression returns true (a non-@code{nil} value) if the buffer is
5687 actually a buffer, and not just the name of a buffer.  In the @code{or}
5688 expression, if this is the case, the @code{or} expression returns this
5689 true value and does not evaluate the next expression---and this is fine
5690 with us, since we do not want to do anything to the value of
5691 @code{buffer} if it really is a buffer.
5693 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
5694 which it will be if the value of @code{buffer} is the name of a buffer,
5695 the Lisp interpreter evaluates the next element of the @code{or}
5696 expression.  This is the expression @code{(setq buffer (get-buffer
5697 buffer))}.  This expression returns a non-@code{nil} value, which
5698 is the value to which it sets the variable @code{buffer}---and this
5699 value is a buffer itself, not the name of a buffer.
5701 The result of all this is that the symbol @code{buffer} is always
5702 bound to a buffer itself rather than to the name of a buffer.  All
5703 this is necessary because the @code{set-buffer} function in a
5704 following line only works with a buffer itself, not with the name to a
5705 buffer.
5707 @need 1250
5708 Incidentally, using @code{or}, the situation with the usher would be
5709 written like this:
5711 @smallexample
5712 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
5713 @end smallexample
5715 @node Insert let,  , Insert or, insert-buffer
5716 @comment  node-name,  next,  previous,  up
5717 @subsection The @code{let} Expression in @code{insert-buffer}
5719 After ensuring that the variable @code{buffer} refers to a buffer itself
5720 and not just to the name of a buffer, the @code{insert-buffer function}
5721 continues with a @code{let} expression.  This specifies three local
5722 variables, @code{start}, @code{end}, and @code{newmark} and binds them
5723 to the initial value @code{nil}.  These variables are used inside the
5724 remainder of the @code{let} and temporarily hide any other occurrence of
5725 variables of the same name in Emacs until the end of the @code{let}.
5727 @need 1200
5728 The body of the @code{let} contains two @code{save-excursion}
5729 expressions.  First, we will look at the inner @code{save-excursion}
5730 expression in detail.  The expression looks like this:
5732 @smallexample
5733 @group
5734 (save-excursion
5735   (set-buffer buffer)
5736   (setq start (point-min) end (point-max)))
5737 @end group
5738 @end smallexample
5740 @noindent
5741 The expression @code{(set-buffer buffer)} changes Emacs' attention
5742 from the current buffer to the one from which the text will copied.
5743 In that buffer, the variables @code{start} and @code{end} are set to
5744 the beginning and end of the buffer, using the commands
5745 @code{point-min} and @code{point-max}.  Note that we have here an
5746 illustration of how @code{setq} is able to set two variables in the
5747 same expression.  The first argument of @code{setq} is set to the
5748 value of its second, and its third argument is set to the value of its
5749 fourth.
5751 After the body of the inner @code{save-excursion} is evaluated, the
5752 @code{save-excursion} restores the original buffer, but @code{start} and
5753 @code{end} remain set to the values of the beginning and end of the
5754 buffer from which the text will be copied.
5756 @need 1250
5757 The outer @code{save-excursion} expression looks like this:
5759 @smallexample
5760 @group
5761 (save-excursion
5762   (@var{inner-}@code{save-excursion}@var{-expression}
5763      (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
5764   (insert-buffer-substring buffer start end)
5765   (setq newmark (point)))
5766 @end group
5767 @end smallexample
5769 @noindent
5770 The @code{insert-buffer-substring} function copies the text
5771 @emph{into} the current buffer @emph{from} the region indicated by
5772 @code{start} and @code{end} in @code{buffer}.  Since the whole of the
5773 second buffer lies between @code{start} and @code{end}, the whole of
5774 the second buffer is copied into the buffer you are editing.  Next,
5775 the value of point, which will be at the end of the inserted text, is
5776 recorded in the variable @code{newmark}.
5778 After the body of the outer @code{save-excursion} is evaluated, point
5779 and mark are relocated to their original places.
5781 However, it is convenient to locate a mark at the end of the newly
5782 inserted text and locate point at its beginning.  The @code{newmark}
5783 variable records the end of the inserted text.  In the last line of
5784 the @code{let} expression, the @code{(push-mark newmark)} expression
5785 function sets a mark to this location.  (The previous location of the
5786 mark is still accessible; it is recorded on the mark ring and you can
5787 go back to it with @kbd{C-u C-@key{SPC}}.)  Meanwhile, point is
5788 located at the beginning of the inserted text, which is where it was
5789 before you called the insert function, the position of which was saved
5790 by the first @code{save-excursion}.
5792 @need 1250
5793 The whole @code{let} expression looks like this:
5795 @smallexample
5796 @group
5797 (let (start end newmark)
5798   (save-excursion
5799     (save-excursion
5800       (set-buffer buffer)
5801       (setq start (point-min) end (point-max)))
5802     (insert-buffer-substring buffer start end)
5803     (setq newmark (point)))
5804   (push-mark newmark))
5805 @end group
5806 @end smallexample
5808 Like the @code{append-to-buffer} function, the @code{insert-buffer}
5809 function uses @code{let}, @code{save-excursion}, and
5810 @code{set-buffer}.  In addition, the function illustrates one way to
5811 use @code{or}.  All these functions are building blocks that we will
5812 find and use again and again.
5814 @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
5815 @comment  node-name,  next,  previous,  up
5816 @section Complete Definition of @code{beginning-of-buffer}
5817 @findex beginning-of-buffer
5819 The basic structure of the @code{beginning-of-buffer} function has
5820 already been discussed.  (@xref{simplified-beginning-of-buffer, , A
5821 Simplified @code{beginning-of-buffer} Definition}.)
5822 This section describes the complex part of the definition.
5824 As previously described, when invoked without an argument,
5825 @code{beginning-of-buffer} moves the cursor to the beginning of the
5826 buffer, leaving the mark at the previous position.  However, when the
5827 command is invoked with a number between one and ten, the function
5828 considers that number to be a fraction of the length of the buffer,
5829 measured in tenths, and Emacs moves the cursor that fraction of the way
5830 from the beginning of the buffer.  Thus, you can either call this
5831 function with the key command @kbd{M-<}, which will move the cursor to
5832 the beginning of the buffer, or with a key command such as @kbd{C-u 7
5833 M-<} which will move the cursor to a point 70% of the way through the
5834 buffer.  If a number bigger than ten is used for the argument, it moves
5835 to the end of the buffer.
5837 The @code{beginning-of-buffer} function can be called with or without an
5838 argument.  The use of the argument is optional.
5840 @menu
5841 * Optional Arguments::
5842 * beginning-of-buffer opt arg::  Example with optional argument.
5843 * beginning-of-buffer complete::
5844 @end menu
5846 @node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
5847 @subsection Optional Arguments
5849 Unless told otherwise, Lisp expects that a function with an argument in
5850 its function definition will be called with a value for that argument.
5851 If that does not happen, you get an error and a message that says
5852 @samp{Wrong number of arguments}.
5854 @cindex Optional arguments
5855 @cindex Keyword
5856 @findex optional
5857 However, optional arguments are a feature of Lisp: a @dfn{keyword} may
5858 be used to tell the Lisp interpreter that an argument is optional.
5859 The keyword is @code{&optional}.  (The @samp{&} in front of
5860 @samp{optional} is part of the keyword.)  In a function definition, if
5861 an argument follows the keyword @code{&optional}, a value does not
5862 need to be passed to that argument when the function is called.
5864 @need 1200
5865 The first line of the function definition of @code{beginning-of-buffer}
5866 therefore looks like this:
5868 @smallexample
5869 (defun beginning-of-buffer (&optional arg)
5870 @end smallexample
5872 @need 1250
5873 In outline, the whole function looks like this:
5875 @smallexample
5876 @group
5877 (defun beginning-of-buffer (&optional arg)
5878   "@var{documentation}@dots{}"
5879   (interactive "P")
5880   (push-mark)
5881   (goto-char
5882     (@var{if-there-is-an-argument}
5883         @var{figure-out-where-to-go}
5884       @var{else-go-to}
5885       (point-min))))
5886 @end group
5887 @end smallexample
5889 The function is similar to the @code{simplified-beginning-of-buffer}
5890 function except that the @code{interactive} expression has @code{"P"}
5891 as an argument and the @code{goto-char} function is followed by an
5892 if-then-else expression that figures out where to put the cursor if
5893 there is an argument.
5895 The @code{"P"} in the @code{interactive} expression tells Emacs to pass
5896 a prefix argument, if there is one, to the function.  A prefix argument
5897 is made by typing the @key{META} key followed by a number, or by typing
5898 @kbd{C-u} and then a number (if you don't type a number, @kbd{C-u}
5899 defaults to 4).
5901 The true-or-false-test of the @code{if} expression is simple: it is
5902 simply the argument @code{arg}.  If @code{arg} has a value that is not
5903 @code{nil}, which will be the case if @code{beginning-of-buffer} is
5904 called with an argument, then this true-or-false-test will return true
5905 and the then-part of the @code{if} expression will be evaluated.  On the
5906 other hand, if @code{beginning-of-buffer} is not called with an
5907 argument, the value of @code{arg} will be @code{nil} and the else-part
5908 of the @code{if} expression will be evaluated.  The else-part is simply
5909 @code{point-min}, and when this is the outcome, the whole
5910 @code{goto-char} expression is @code{(goto-char (point-min))}, which is
5911 how we saw the @code{beginning-of-buffer} function in its simplified
5912 form.
5914 @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
5915 @subsection @code{beginning-of-buffer} with an Argument
5917 When @code{beginning-of-buffer} is called with an argument, an
5918 expression is evaluated which calculates what value to pass to
5919 @code{goto-char}.  This expression is rather complicated at first sight.
5920 It includes an inner @code{if} expression and much arithmetic.  It looks
5921 like this:
5923 @smallexample
5924 @group
5925 (if (> (buffer-size) 10000)
5926     ;; @r{Avoid overflow for large buffer sizes!}
5927     (* (prefix-numeric-value arg) (/ (buffer-size) 10))
5928   (/
5929    (+ 10
5930       (*
5931        (buffer-size) (prefix-numeric-value arg))) 10))
5932 @end group
5933 @end smallexample
5935 @menu
5936 * Disentangle beginning-of-buffer::
5937 * Large buffer case::
5938 * Small buffer case::
5939 @end menu
5941 @node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg
5942 @ifnottex
5943 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
5944 @end ifnottex
5946 Like other complex-looking expressions, the conditional expression
5947 within @code{beginning-of-buffer} can be disentangled by looking at it
5948 as parts of a template, in this case, the template for an if-then-else
5949 expression.  In skeletal form, the expression looks like this:
5951 @smallexample
5952 @group
5953 (if (@var{buffer-is-large}
5954     @var{divide-buffer-size-by-10-and-multiply-by-arg}
5955   @var{else-use-alternate-calculation}
5956 @end group
5957 @end smallexample
5959 The true-or-false-test of this inner @code{if} expression checks the
5960 size of the buffer.  The reason for this is that the old Version 18
5961 Emacs used numbers that are no bigger than eight million or so
5962 and in the computation that followed, the programmer feared that Emacs
5963 might try to use over-large numbers if the buffer were large.  The
5964 term `overflow', mentioned in the comment, means numbers that are over
5965 large.  Version 21 Emacs uses larger numbers, but this code has not
5966 been touched, if only because people now look at buffers that are far,
5967 far larger than ever before.
5969 There are two cases:  if the buffer is large and if it is not.
5971 @node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg
5972 @comment  node-name,  next,  previous,  up
5973 @unnumberedsubsubsec What happens in a large buffer
5975 In @code{beginning-of-buffer}, the inner @code{if} expression tests
5976 whether the size of the buffer is greater than 10,000 characters.  To do
5977 this, it uses the @code{>} function and the @code{buffer-size} function.
5979 @need 800
5980 The line looks like this:
5982 @smallexample
5983 (if (> (buffer-size) 10000)
5984 @end smallexample
5986 @need 1200
5987 @noindent
5988 When the buffer is large, the then-part of the @code{if} expression is
5989 evaluated.  It reads like this (after formatting for easy reading):
5991 @smallexample
5992 @group
5994   (prefix-numeric-value arg)
5995   (/ (buffer-size) 10))
5996 @end group
5997 @end smallexample
5999 @noindent
6000 This expression is a multiplication, with two arguments to the function
6001 @code{*}.
6003 The first argument is @code{(prefix-numeric-value arg)}.  When
6004 @code{"P"} is used as the argument for @code{interactive}, the value
6005 passed to the function as its argument is passed a ``raw prefix
6006 argument'', and not a number.  (It is a number in a list.)  To perform
6007 the arithmetic, a conversion is necessary, and
6008 @code{prefix-numeric-value} does the job.
6010 @findex / @r{(division)}
6011 @cindex Division
6012 The second argument is @code{(/ (buffer-size) 10)}.  This expression
6013 divides the numeric value of the buffer by ten.  This produces a number
6014 that tells how many characters make up one tenth of the buffer size.
6015 (In Lisp, @code{/} is used for division, just as @code{*} is
6016 used for multiplication.)
6018 @need 1200
6019 In the multiplication expression as a whole, this amount is multiplied
6020 by the value of the prefix argument---the multiplication looks like this:
6022 @smallexample
6023 @group
6024 (* @var{numeric-value-of-prefix-arg}
6025    @var{number-of-characters-in-one-tenth-of-the-buffer})
6026 @end group
6027 @end smallexample
6029 @noindent
6030 If, for example, the prefix argument is @samp{7}, the one-tenth value
6031 will be multiplied by 7 to give a position 70% of the way through the
6032 buffer.
6034 @need 1200
6035 The result of all this is that if the buffer is large, the
6036 @code{goto-char} expression reads like this:
6038 @smallexample
6039 @group
6040 (goto-char (* (prefix-numeric-value arg)
6041               (/ (buffer-size) 10)))
6042 @end group
6043 @end smallexample
6045 This puts the cursor where we want it.
6047 @node Small buffer case,  , Large buffer case, beginning-of-buffer opt arg
6048 @comment  node-name,  next,  previous,  up
6049 @unnumberedsubsubsec What happens in a small buffer
6051 If the buffer contains fewer than 10,000 characters, a slightly
6052 different computation is performed.  You might think this is not
6053 necessary, since the first computation could do the job.  However, in
6054 a small buffer, the first method may not put the cursor on exactly the
6055 desired line; the second method does a better job.
6057 @need 800
6058 The code looks like this:
6060 @c Keep this on one line.
6061 @smallexample
6062 (/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10))
6063 @end smallexample
6065 @need 1200
6066 @noindent
6067 This is code in which you figure out what happens by discovering how the
6068 functions are embedded in parentheses.  It is easier to read if you
6069 reformat it with each expression indented more deeply than its
6070 enclosing expression:
6072 @smallexample
6073 @group
6074   (/
6075    (+ 10
6076       (*
6077        (buffer-size)
6078        (prefix-numeric-value arg)))
6079    10))
6080 @end group
6081 @end smallexample
6083 @need 1200
6084 @noindent
6085 Looking at parentheses, we see that the innermost operation is
6086 @code{(prefix-numeric-value arg)}, which converts the raw argument to a
6087 number.  This number is multiplied by the buffer size in the following
6088 expression:
6090 @smallexample
6091 (* (buffer-size) (prefix-numeric-value arg)
6092 @end smallexample
6094 @noindent
6095 This multiplication creates a number that may be larger than the size of
6096 the buffer---seven times larger if the argument is 7, for example.  Ten
6097 is then added to this number and finally the large number is divided by
6098 ten to provide a value that is one character larger than the percentage
6099 position in the buffer.
6101 The number that results from all this is passed to @code{goto-char} and
6102 the cursor is moved to that point.
6104 @need 1500
6105 @node beginning-of-buffer complete,  , beginning-of-buffer opt arg, beginning-of-buffer
6106 @comment  node-name,  next,  previous,  up
6107 @subsection The Complete @code{beginning-of-buffer}
6109 @need 1000
6110 Here is the complete text of the @code{beginning-of-buffer} function:
6111 @sp 1
6113 @smallexample
6114 @group
6115 (defun beginning-of-buffer (&optional arg)
6116   "Move point to the beginning of the buffer;
6117 leave mark at previous position.
6118 With arg N, put point N/10 of the way
6119 from the true beginning.
6120 @end group
6121 @group
6122 Don't use this in Lisp programs!
6123 \(goto-char (point-min)) is faster
6124 and does not set the mark."
6125   (interactive "P")
6126   (push-mark)
6127 @end group
6128 @group
6129   (goto-char
6130    (if arg
6131        (if (> (buffer-size) 10000)
6132            ;; @r{Avoid overflow for large buffer sizes!}
6133            (* (prefix-numeric-value arg)
6134               (/ (buffer-size) 10))
6135 @end group
6136 @group
6137          (/ (+ 10 (* (buffer-size)
6138                      (prefix-numeric-value arg)))
6139             10))
6140      (point-min)))
6141   (if arg (forward-line 1)))
6142 @end group
6143 @end smallexample
6145 @noindent
6146 Except for two small points, the previous discussion shows how this
6147 function works.  The first point deals with a detail in the
6148 documentation string, and the second point concerns the last line of
6149 the function.
6151 @need 800
6152 In the documentation string, there is reference to an expression:
6154 @smallexample
6155 \(goto-char (point-min))
6156 @end smallexample
6158 @noindent
6159 A @samp{\} is used before the first parenthesis of this expression.
6160 This @samp{\} tells the Lisp interpreter that the expression should be
6161 printed as shown in the documentation rather than evaluated as a
6162 symbolic expression, which is what it looks like.
6164 @need 1200
6165 Finally, the last line of the @code{beginning-of-buffer} command says to
6166 move point to the beginning of the next line if the command is
6167 invoked with an argument:
6169 @smallexample
6170 (if arg (forward-line 1)))
6171 @end smallexample
6173 @noindent
6174 This puts the cursor at the beginning of the first line after the
6175 appropriate tenths position in the buffer.  This is a flourish that
6176 means that the cursor is always located @emph{at least} the requested
6177 tenths of the way through the buffer, which is a nicety that is,
6178 perhaps, not necessary, but which, if it did not occur, would be sure to
6179 draw complaints.
6181 @node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
6182 @comment  node-name,  next,  previous,  up
6183 @section Review
6185 Here is a brief summary of some of the topics covered in this chapter.
6187 @table @code
6188 @item or
6189 Evaluate each argument in sequence, and return the value of the first
6190 argument that is not @code{nil}; if none return a value that is not
6191 @code{nil}, return @code{nil}.  In brief, return the first true value
6192 of the arguments; return a true value if one @emph{or} any of the
6193 other are true.
6195 @item and
6196 Evaluate each argument in sequence, and if any are @code{nil}, return
6197 @code{nil}; if none are @code{nil}, return the value of the last
6198 argument.  In brief, return a true value only if all the arguments are
6199 true; return a true value if one @emph{and} each of the others is
6200 true.
6202 @item &optional
6203 A keyword used to indicate that an argument to a function definition
6204 is optional; this means that the function can be evaluated without the
6205 argument, if desired.
6207 @item prefix-numeric-value
6208 Convert the `raw prefix argument' produced by @code{(interactive
6209 "P")} to a numeric value.
6211 @item forward-line
6212 Move point forward to the beginning of the next line, or if the argument
6213 is greater than one, forward that many lines.  If it can't move as far
6214 forward as it is supposed to, @code{forward-line} goes forward as far as
6215 it can and then returns a count of the number of additional lines it was
6216 supposed to move but couldn't.
6218 @item erase-buffer
6219 Delete the entire contents of the current buffer.
6221 @item bufferp
6222 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
6223 @end table
6225 @node optional Exercise,  , Second Buffer Related Review, More Complex
6226 @section @code{optional} Argument Exercise
6228 Write an interactive function with an optional argument that tests
6229 whether its argument, a number, is greater than or equal to, or else,
6230 less than the value of @code{fill-column}, and tells you which, in a
6231 message.  However, if you do not pass an argument to the function, use
6232 56 as a default value.
6234 @node Narrowing & Widening, car cdr & cons, More Complex, Top
6235 @comment  node-name,  next,  previous,  up
6236 @chapter Narrowing and Widening
6237 @cindex Focusing attention (narrowing)
6238 @cindex Narrowing
6239 @cindex Widening
6241 Narrowing is a feature of Emacs that makes it possible for you to focus
6242 on a specific part of a buffer, and work without accidentally changing
6243 other parts.  Narrowing is normally disabled since it can confuse
6244 novices.
6246 @menu
6247 * Narrowing advantages::        The advantages of narrowing
6248 * save-restriction::            The @code{save-restriction} special form.
6249 * what-line::                   The number of the line that point is on.
6250 * narrow Exercise::
6251 @end menu
6253 @node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
6254 @ifnottex
6255 @unnumberedsec The Advantages of Narrowing
6256 @end ifnottex
6258 With narrowing, the rest of a buffer is made invisible, as if it weren't
6259 there.  This is an advantage if, for example, you want to replace a word
6260 in one part of a buffer but not in another: you narrow to the part you want
6261 and the replacement is carried out only in that section, not in the rest
6262 of the buffer.  Searches will only work within a narrowed region, not
6263 outside of one, so if you are fixing a part of a document, you can keep
6264 yourself from accidentally finding parts you do not need to fix by
6265 narrowing just to the region you want.
6266 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
6268 However, narrowing does make the rest of the buffer invisible, which
6269 can scare people who inadvertently invoke narrowing and think they
6270 have deleted a part of their file.  Moreover, the @code{undo} command
6271 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
6272 (nor should it), so people can become quite desperate if they do not
6273 know that they can return the rest of a buffer to visibility with the
6274 @code{widen} command.
6275 (The key binding for @code{widen} is @kbd{C-x n w}.)
6277 Narrowing is just as useful to the Lisp interpreter as to a human.
6278 Often, an Emacs Lisp function is designed to work on just part of a
6279 buffer; or conversely, an Emacs Lisp function needs to work on all of a
6280 buffer that has been narrowed.  The @code{what-line} function, for
6281 example, removes the narrowing from a buffer, if it has any narrowing
6282 and when it has finished its job, restores the narrowing to what it was.
6283 On the other hand, the @code{count-lines} function, which is called by
6284 @code{what-line}, uses narrowing to restrict itself to just that portion
6285 of the buffer in which it is interested and then restores the previous
6286 situation.
6288 @node save-restriction, what-line, Narrowing advantages, Narrowing & Widening
6289 @comment  node-name,  next,  previous,  up
6290 @section The @code{save-restriction} Special Form
6291 @findex save-restriction
6293 In Emacs Lisp, you can use the @code{save-restriction} special form to
6294 keep track of whatever narrowing is in effect, if any.  When the Lisp
6295 interpreter meets with @code{save-restriction}, it executes the code
6296 in the body of the @code{save-restriction} expression, and then undoes
6297 any changes to narrowing that the code caused.  If, for example, the
6298 buffer is narrowed and the code that follows @code{save-restriction}
6299 gets rid of the narrowing, @code{save-restriction} returns the buffer
6300 to its narrowed region afterwards.  In the @code{what-line} command,
6301 any narrowing the buffer may have is undone by the @code{widen}
6302 command that immediately follows the @code{save-restriction} command.
6303 Any original narrowing is restored just before the completion of the
6304 function.
6306 @need 1250
6307 The template for a @code{save-restriction} expression is simple:
6309 @smallexample
6310 @group
6311 (save-restriction
6312   @var{body}@dots{} )
6313 @end group
6314 @end smallexample
6316 @noindent
6317 The body of the @code{save-restriction} is one or more expressions that
6318 will be evaluated in sequence by the Lisp interpreter.
6320 Finally, a point to note: when you use both @code{save-excursion} and
6321 @code{save-restriction}, one right after the other, you should use
6322 @code{save-excursion} outermost.  If you write them in reverse order,
6323 you may fail to record narrowing in the buffer to which Emacs switches
6324 after calling @code{save-excursion}.  Thus, when written together,
6325 @code{save-excursion} and @code{save-restriction} should be written
6326 like this:
6328 @smallexample
6329 @group
6330 (save-excursion
6331   (save-restriction
6332     @var{body}@dots{}))
6333 @end group
6334 @end smallexample
6336 In other circumstances, when not written together, the
6337 @code{save-excursion} and @code{save-restriction} special forms must
6338 be written in the order appropriate to the function.
6340 @need 1250
6341 For example,
6343 @smallexample
6344 @group
6345   (save-restriction
6346     (widen)
6347     (save-excursion
6348     @var{body}@dots{}))
6349 @end group
6350 @end smallexample
6352 @node what-line, narrow Exercise, save-restriction, Narrowing & Widening
6353 @comment  node-name,  next,  previous,  up
6354 @section @code{what-line}
6355 @findex what-line
6356 @cindex Widening, example of
6358 The @code{what-line} command tells you the number of the line in which
6359 the cursor is located.  The function illustrates the use of the
6360 @code{save-restriction} and @code{save-excursion} commands.  Here is the
6361 original text of the function:
6363 @smallexample
6364 @group
6365 (defun what-line ()
6366   "Print the current line number (in the buffer) of point."
6367   (interactive)
6368   (save-restriction
6369     (widen)
6370     (save-excursion
6371       (beginning-of-line)
6372       (message "Line %d"
6373                (1+ (count-lines 1 (point)))))))
6374 @end group
6375 @end smallexample
6377 (In recent versions of GNU Emacs, the @code{what-line} function has
6378 been expanded to tell you your line number in a narrowed buffer as
6379 well as your line number in a widened buffer.  The recent version is
6380 more complex than the version shown here.  If you feel adventurous,
6381 you might want to look at it after figuring out how this version
6382 works.  The newer version uses a conditional to determine whether the
6383 buffer has been narrowed, and rather than use @code{beginning-of-line}
6384 to move point to the beginning of the current line, if need be, the
6385 function uses @code{(forward-line 0)}.)
6387 The function as shown here has a documentation line and is
6388 interactive, as you would expect.  The next two lines use the
6389 functions @code{save-restriction} and @code{widen}.
6391 The @code{save-restriction} special form notes whatever narrowing is in
6392 effect, if any, in the current buffer and restores that narrowing after
6393 the code in the body of the @code{save-restriction} has been evaluated.
6395 The @code{save-restriction} special form is followed by @code{widen}.
6396 This function undoes any narrowing the current buffer may have had
6397 when @code{what-line} was called.  (The narrowing that was there is
6398 the narrowing that @code{save-restriction} remembers.)  This widening
6399 makes it possible for the line counting commands to count from the
6400 beginning of the buffer.  Otherwise, they would have been limited to
6401 counting within the accessible region.  Any original narrowing is
6402 restored just before the completion of the function by the
6403 @code{save-restriction} special form.
6405 The call to @code{widen} is followed by @code{save-excursion}, which
6406 saves the location of the cursor (i.e., of point) and of the mark, and
6407 restores them after the code in the body of the @code{save-excursion}
6408 uses the @code{beginning-of-line} function to move point.
6410 (Note that the @code{(widen)} expression comes between the
6411 @code{save-restriction} and @code{save-excursion} special forms.  When
6412 you write the two @code{save- @dots{}} expressions in sequence, write
6413 @code{save-excursion} outermost.)
6415 @need 1200
6416 The last two lines of the @code{what-line} function are functions to
6417 count the number of lines in the buffer and then print the number in the
6418 echo area.
6420 @smallexample
6421 @group
6422 (message "Line %d"
6423          (1+ (count-lines 1 (point)))))))
6424 @end group
6425 @end smallexample
6427 The @code{message} function prints a one-line message at the bottom of the
6428 Emacs screen.  The first argument is inside of quotation marks and is
6429 printed as a string of characters.  However, it may contain @samp{%d},
6430 @samp{%s}, or @samp{%c} to print arguments that follow the string.
6431 @samp{%d} prints the argument as a decimal, so the message will say
6432 something such as @samp{Line 243}.
6434 @need 1200
6436 The number that is printed in place of the @samp{%d} is computed by the
6437 last line of the function:
6439 @smallexample
6440 (1+ (count-lines 1 (point)))
6441 @end smallexample
6443 @noindent
6444 What this does is count the lines from the first position of the
6445 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
6446 one to that number.  (The @code{1+} function adds one to its
6447 argument.)  We add one to it because line 2 has only one line before
6448 it, and @code{count-lines} counts only the lines @emph{before} the
6449 current line.
6451 After @code{count-lines} has done its job, and the message has been
6452 printed in the echo area, the @code{save-excursion} restores point and
6453 mark to their original positions; and @code{save-restriction} restores
6454 the original narrowing, if any.
6456 @node narrow Exercise,  , what-line, Narrowing & Widening
6457 @section Exercise with Narrowing
6459 Write a function that will display the first 60 characters of the
6460 current buffer, even if you have narrowed the buffer to its latter
6461 half so that the first line is inaccessible.  Restore point, mark, and
6462 narrowing.  For this exercise, you need to use a whole potpourri of
6463 functions, including @code{save-restriction}, @code{widen},
6464 @code{goto-char}, @code{point-min}, @code{message}, and
6465 @code{buffer-substring}.
6467 @cindex Properties, mention of @code{buffer-substring-no-properties}
6468 (@code{buffer-substring} is a previously unmentioned function you will
6469 have to investigate yourself; or perhaps you will have to use
6470 @code{buffer-substring-no-properties} @dots{}, yet another function
6471 and one that introduces text properties, a feature otherwise not
6472 discussed here.  @xref{Text Properties, , Text Properties, elisp, The
6473 GNU Emacs Lisp Reference Manual}.  Additionally, do you really need
6474 @code{goto-char} or @code{point-min}?  Or can you write the function
6475 without them?)
6477 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
6478 @comment  node-name,  next,  previous,  up
6479 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
6480 @findex car, @r{introduced}
6481 @findex cdr, @r{introduced}
6483 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
6484 functions.  The @code{cons} function is used to construct lists, and
6485 the @code{car} and @code{cdr} functions are used to take them apart.
6487 In the walk through of the @code{copy-region-as-kill} function, we
6488 will see @code{cons} as well as two variants on @code{cdr},
6489 namely, @code{setcdr} and @code{nthcdr}.  (@xref{copy-region-as-kill}.)
6491 @menu
6492 * Strange Names::               An historical aside: why the strange names?
6493 * car & cdr::                   Functions for extracting part of a list.
6494 * cons::                        Constructing a list.
6495 * nthcdr::                      Calling @code{cdr} repeatedly.
6496 * nth::
6497 * setcar::                      Changing the first element of a list.
6498 * setcdr::                      Changing the rest of a list.
6499 * cons Exercise::
6500 @end menu
6502 @node Strange Names, car & cdr, car cdr & cons, car cdr & cons
6503 @ifnottex
6504 @unnumberedsec Strange Names
6505 @end ifnottex
6507 The name of the @code{cons} function is not unreasonable: it is an
6508 abbreviation of the word `construct'.  The origins of the names for
6509 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
6510 is an acronym from the phrase `Contents of the Address part of the
6511 Register'; and @code{cdr} (pronounced `could-er') is an acronym from
6512 the phrase `Contents of the Decrement part of the Register'.  These
6513 phrases refer to specific pieces of hardware on the very early
6514 computer on which the original Lisp was developed.  Besides being
6515 obsolete, the phrases have been completely irrelevant for more than 25
6516 years to anyone thinking about Lisp.  Nonetheless, although a few
6517 brave scholars have begun to use more reasonable names for these
6518 functions, the old terms are still in use.  In particular, since the
6519 terms are used in the Emacs Lisp source code, we will use them in this
6520 introduction.
6522 @node car & cdr, cons, Strange Names, car cdr & cons
6523 @comment  node-name,  next,  previous,  up
6524 @section @code{car} and @code{cdr}
6526 The @sc{car} of a list is, quite simply, the first item in the list.
6527 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
6528 @code{rose}.
6530 @need 1200
6531 If you are reading this in Info in GNU Emacs, you can see this by
6532 evaluating the following:
6534 @smallexample
6535 (car '(rose violet daisy buttercup))
6536 @end smallexample
6538 @noindent
6539 After evaluating the expression, @code{rose} will appear in the echo
6540 area.
6542 Clearly, a more reasonable name for the @code{car} function would be
6543 @code{first} and this is often suggested.
6545 @code{car} does not remove the first item from the list; it only reports
6546 what it is.  After @code{car} has been applied to a list, the list is
6547 still the same as it was.  In the jargon, @code{car} is
6548 `non-destructive'.  This feature turns out to be important.
6550 The @sc{cdr} of a list is the rest of the list, that is, the
6551 @code{cdr} function returns the part of the list that follows the
6552 first item.  Thus, while the @sc{car} of the list @code{'(rose violet
6553 daisy buttercup)} is @code{rose}, the rest of the list, the value
6554 returned by the @code{cdr} function, is @code{(violet daisy
6555 buttercup)}.
6557 @need 800
6558 You can see this by evaluating the following in the usual way:
6560 @smallexample
6561 (cdr '(rose violet daisy buttercup))
6562 @end smallexample
6564 @noindent
6565 When you evaluate this, @code{(violet daisy buttercup)} will appear in
6566 the echo area.
6568 Like @code{car}, @code{cdr} does not remove any elements from the
6569 list---it just returns a report of what the second and subsequent
6570 elements are.
6572 Incidentally, in the example, the list of flowers is quoted.  If it were
6573 not, the Lisp interpreter would try to evaluate the list by calling
6574 @code{rose} as a function.  In this example, we do not want to do that.
6576 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
6578 (There is a lesson here: when you name new functions, consider very
6579 carefully what you are doing, since you may be stuck with the names
6580 for far longer than you expect.  The reason this document perpetuates
6581 these names is that the Emacs Lisp source code uses them, and if I did
6582 not use them, you would have a hard time reading the code; but do,
6583 please, try to avoid using these terms yourself.  The people who come
6584 after you will be grateful to you.)
6586 When @code{car} and @code{cdr} are applied to a list made up of symbols,
6587 such as the list @code{(pine fir oak maple)}, the element of the list
6588 returned by the function @code{car} is the symbol @code{pine} without
6589 any parentheses around it.  @code{pine} is the first element in the
6590 list.  However, the @sc{cdr} of the list is a list itself, @code{(fir
6591 oak maple)}, as you can see by evaluating the following expressions in
6592 the usual way:
6594 @smallexample
6595 @group
6596 (car '(pine fir oak maple))
6598 (cdr '(pine fir oak maple))
6599 @end group
6600 @end smallexample
6602 On the other hand, in a list of lists, the first element is itself a
6603 list.  @code{car} returns this first element as a list.  For example,
6604 the following list contains three sub-lists, a list of carnivores, a
6605 list of herbivores and a list of sea mammals:
6607 @smallexample
6608 @group
6609 (car '((lion tiger cheetah)
6610        (gazelle antelope zebra)
6611        (whale dolphin seal)))
6612 @end group
6613 @end smallexample
6615 @noindent
6616 In this example, the first element or @sc{car} of the list is the list of
6617 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
6618 @code{((gazelle antelope zebra) (whale dolphin seal))}.
6620 @smallexample
6621 @group
6622 (cdr '((lion tiger cheetah)
6623        (gazelle antelope zebra)
6624        (whale dolphin seal)))
6625 @end group
6626 @end smallexample
6628 It is worth saying again that @code{car} and @code{cdr} are
6629 non-destructive---that is, they do not modify or change lists to which
6630 they are applied.  This is very important for how they are used.
6632 Also, in the first chapter, in the discussion about atoms, I said that
6633 in Lisp, ``certain kinds of atom, such as an array, can be separated
6634 into parts; but the mechanism for doing this is different from the
6635 mechanism for splitting a list.  As far as Lisp is concerned, the
6636 atoms of a list are unsplittable.''  (@xref{Lisp Atoms}.)  The
6637 @code{car} and @code{cdr} functions are used for splitting lists and
6638 are considered fundamental to Lisp.  Since they cannot split or gain
6639 access to the parts of an array, an array is considered an atom.
6640 Conversely, the other fundamental function, @code{cons}, can put
6641 together or construct a list, but not an array.  (Arrays are handled
6642 by array-specific functions.  @xref{Arrays, , Arrays, elisp, The GNU
6643 Emacs Lisp Reference Manual}.)
6645 @node cons, nthcdr, car & cdr, car cdr & cons
6646 @comment  node-name,  next,  previous,  up
6647 @section @code{cons}
6648 @findex cons, @r{introduced}
6650 The @code{cons} function constructs lists; it is the inverse of
6651 @code{car} and @code{cdr}.  For example, @code{cons} can be used to make
6652 a four element list from the three element list, @code{(fir oak maple)}:
6654 @smallexample
6655 (cons 'pine '(fir oak maple))
6656 @end smallexample
6658 @need 800
6659 @noindent
6660 After evaluating this list, you will see
6662 @smallexample
6663 (pine fir oak maple)
6664 @end smallexample
6666 @noindent
6667 appear in the echo area.  @code{cons} causes the creation of a new
6668 list in which the element is followed by the elements of the original
6669 list.
6671 We often say that `@code{cons} puts a new element at the beginning of
6672 a list; it attaches or pushes elements onto the list', but this
6673 phrasing can be misleading, since @code{cons} does not change an
6674 existing list, but creates a new one.
6676 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
6678 @menu
6679 * Build a list::
6680 * length::                      How to find the length of a list.
6681 @end menu
6683 @node Build a list, length, cons, cons
6684 @ifnottex
6685 @unnumberedsubsec Build a list
6686 @end ifnottex
6688 @code{cons} must have a list to attach to.@footnote{Actually, you can
6689 @code{cons} an element to an atom to produce a dotted pair.  Dotted
6690 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
6691 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.}  You
6692 cannot start from absolutely nothing.  If you are building a list, you
6693 need to provide at least an empty list at the beginning.  Here is a
6694 series of @code{cons} expressions that build up a list of flowers.  If
6695 you are reading this in Info in GNU Emacs, you can evaluate each of
6696 the expressions in the usual way; the value is printed in this text
6697 after @samp{@result{}}, which you may read as `evaluates to'.
6699 @smallexample
6700 @group
6701 (cons 'buttercup ())
6702      @result{} (buttercup)
6703 @end group
6705 @group
6706 (cons 'daisy '(buttercup))
6707      @result{} (daisy buttercup)
6708 @end group
6710 @group
6711 (cons 'violet '(daisy buttercup))
6712      @result{} (violet daisy buttercup)
6713 @end group
6715 @group
6716 (cons 'rose '(violet daisy buttercup))
6717      @result{} (rose violet daisy buttercup)
6718 @end group
6719 @end smallexample
6721 @noindent
6722 In the first example, the empty list is shown as @code{()} and a list
6723 made up of @code{buttercup} followed by the empty list is constructed.
6724 As you can see, the empty list is not shown in the list that was
6725 constructed.  All that you see is @code{(buttercup)}.  The empty list is
6726 not counted as an element of a list because there is nothing in an empty
6727 list.  Generally speaking, an empty list is invisible.
6729 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
6730 two element list by putting @code{daisy} in front of @code{buttercup};
6731 and the third example constructs a three element list by putting
6732 @code{violet} in front of @code{daisy} and @code{buttercup}.
6734 @node length,  , Build a list, cons
6735 @comment  node-name,  next,  previous,  up
6736 @subsection Find the Length of a List: @code{length}
6737 @findex length
6739 You can find out how many elements there are in a list by using the Lisp
6740 function @code{length}, as in the following examples:
6742 @smallexample
6743 @group
6744 (length '(buttercup))
6745      @result{} 1
6746 @end group
6748 @group
6749 (length '(daisy buttercup))
6750      @result{} 2
6751 @end group
6753 @group
6754 (length (cons 'violet '(daisy buttercup)))
6755      @result{} 3
6756 @end group
6757 @end smallexample
6759 @noindent
6760 In the third example, the @code{cons} function is used to construct a
6761 three element list which is then passed to the @code{length} function as
6762 its argument.
6764 @need 1200
6765 We can also use @code{length} to count the number of elements in an
6766 empty list:
6768 @smallexample
6769 @group
6770 (length ())
6771      @result{} 0
6772 @end group
6773 @end smallexample
6775 @noindent
6776 As you would expect, the number of elements in an empty list is zero.
6778 An interesting experiment is to find out what happens if you try to find
6779 the length of no list at all; that is, if you try to call @code{length}
6780 without giving it an argument, not even an empty list:
6782 @smallexample
6783 (length )
6784 @end smallexample
6786 @need 800
6787 @noindent
6788 What you see, if you evaluate this, is the error message
6790 @smallexample
6791 Wrong number of arguments: #<subr length>, 0
6792 @end smallexample
6794 @noindent
6795 This means that the function receives the wrong number of
6796 arguments, zero, when it expects some other number of arguments.  In
6797 this case, one argument is expected, the argument being a list whose
6798 length the function is measuring.  (Note that @emph{one} list is
6799 @emph{one} argument, even if the list has many elements inside it.)
6801 The part of the error message that says @samp{#<subr length>} is the
6802 name of the function.  This is written with a special notation,
6803 @samp{#<subr}, that indicates that the function @code{length} is one
6804 of the primitive functions written in C rather than in Emacs Lisp.
6805 (@samp{subr} is an abbreviation for `subroutine'.)  @xref{What Is a
6806 Function, , What Is a Function?, elisp , The GNU Emacs Lisp Reference
6807 Manual}, for more about subroutines.
6809 @node nthcdr, nth, cons, car cdr & cons
6810 @comment  node-name,  next,  previous,  up
6811 @section @code{nthcdr}
6812 @findex nthcdr
6814 The @code{nthcdr} function is associated with the @code{cdr} function.
6815 What it does is take the @sc{cdr} of a list repeatedly.
6817 If you take the @sc{cdr} of the list @code{(pine fir
6818 oak maple)}, you will be returned the list @code{(fir oak maple)}.  If you
6819 repeat this on what was returned, you will be returned the list
6820 @code{(oak maple)}.  (Of course, repeated @sc{cdr}ing on the original
6821 list will just give you the original @sc{cdr} since the function does
6822 not change the list.  You need to evaluate the @sc{cdr} of the
6823 @sc{cdr} and so on.)  If you continue this, eventually you will be
6824 returned an empty list, which in this case, instead of being shown as
6825 @code{()} is shown as @code{nil}.
6827 @need 1200
6828 For review, here is a series of repeated @sc{cdr}s, the text following
6829 the @samp{@result{}} shows what is returned.
6831 @smallexample
6832 @group
6833 (cdr '(pine fir oak maple))
6834      @result{}(fir oak maple)
6835 @end group
6837 @group
6838 (cdr '(fir oak maple))
6839      @result{} (oak maple)
6840 @end group
6842 @group
6843 (cdr '(oak maple))
6844      @result{}(maple)
6845 @end group
6847 @group
6848 (cdr '(maple))
6849      @result{} nil
6850 @end group
6852 @group
6853 (cdr 'nil)
6854      @result{} nil
6855 @end group
6857 @group
6858 (cdr ())
6859      @result{} nil
6860 @end group
6861 @end smallexample
6863 @need 1200
6864 You can also do several @sc{cdr}s without printing the values in
6865 between, like this:
6867 @smallexample
6868 @group
6869 (cdr (cdr '(pine fir oak maple)))
6870      @result{} (oak maple)
6871 @end group
6872 @end smallexample
6874 @noindent
6875 In this example, the Lisp interpreter evaluates the innermost list first.
6876 The innermost list is quoted, so it just passes the list as it is to the
6877 innermost @code{cdr}.  This @code{cdr} passes a list made up of the
6878 second and subsequent elements of the list to the outermost @code{cdr},
6879 which produces a list composed of the third and subsequent elements of
6880 the original list.  In this example, the @code{cdr} function is repeated
6881 and returns a list that consists of the original list without its
6882 first two elements.
6884 The @code{nthcdr} function does the same as repeating the call to
6885 @code{cdr}.  In the following example, the argument 2 is passed to the
6886 function @code{nthcdr}, along with the list, and the value returned is
6887 the list without its first two items, which is exactly the same
6888 as repeating @code{cdr} twice on the list:
6890 @smallexample
6891 @group
6892 (nthcdr 2 '(pine fir oak maple))
6893      @result{} (oak maple)
6894 @end group
6895 @end smallexample
6897 @need 1200
6898 Using the original four element list, we can see what happens when
6899 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
6900 and 5:
6902 @smallexample
6903 @group
6904 ;; @r{Leave the list as it was.}
6905 (nthcdr 0 '(pine fir oak maple))
6906      @result{} (pine fir oak maple)
6907 @end group
6909 @group
6910 ;; @r{Return a copy without the first element.}
6911 (nthcdr 1 '(pine fir oak maple))
6912      @result{} (fir oak maple)
6913 @end group
6915 @group
6916 ;; @r{Return a copy of the list without three elements.}
6917 (nthcdr 3 '(pine fir oak maple))
6918      @result{} (maple)
6919 @end group
6921 @group
6922 ;; @r{Return a copy lacking all four elements.}
6923 (nthcdr 4 '(pine fir oak maple))
6924      @result{} nil
6925 @end group
6927 @group
6928 ;; @r{Return a copy lacking all elements.}
6929 (nthcdr 5 '(pine fir oak maple))
6930      @result{} nil
6931 @end group
6932 @end smallexample
6934 @node nth, setcar, nthcdr, car cdr & cons
6935 @comment  node-name,  next,  previous,  up
6936 @section @code{nth}
6937 @findex nth
6939 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
6940 The @code{nth} function takes the @sc{car} of the result returned by
6941 @code{nthcdr}.  It returns the Nth element of the list.
6943 @need 1500
6944 Thus, if it were not defined in C for speed, the definition of
6945 @code{nth} would be:
6947 @smallexample
6948 @group
6949 (defun nth (n list)
6950   "Returns the Nth element of LIST.
6951 N counts from zero.  If LIST is not that long, nil is returned."
6952   (car (nthcdr n list)))
6953 @end group
6954 @end smallexample
6956 @noindent
6957 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
6958 but its definition was redone in C in the 1980s.)
6960 The @code{nth} function returns a single element of a list.
6961 This can be very convenient.
6963 Note that the elements are numbered from zero, not one.  That is to
6964 say, the first element of a list, its @sc{car} is the zeroth element.
6965 This is called `zero-based' counting and often bothers people who
6966 are accustomed to the first element in a list being number one, which
6967 is `one-based'.
6969 @need 1250
6970 For example:
6972 @smallexample
6973 @group
6974 (nth 0 '("one" "two" "three"))
6975     @result{} "one"
6977 (nth 1 '("one" "two" "three"))
6978     @result{} "two"
6979 @end group
6980 @end smallexample
6982 It is worth mentioning that @code{nth}, like @code{nthcdr} and
6983 @code{cdr}, does not change the original list---the function is
6984 non-destructive.  This is in sharp contrast to the @code{setcar} and
6985 @code{setcdr} functions.
6987 @node setcar, setcdr, nth, car cdr & cons
6988 @comment  node-name,  next,  previous,  up
6989 @section @code{setcar}
6990 @findex setcar
6992 As you might guess from their names, the @code{setcar} and @code{setcdr}
6993 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
6994 They actually change the original list, unlike @code{car} and @code{cdr}
6995 which leave the original list as it was.  One way to find out how this
6996 works is to experiment.  We will start with the @code{setcar} function.
6998 @need 1200
6999 First, we can make a list and then set the value of a variable to the
7000 list, using the @code{setq} function.  Here is a list of animals:
7002 @smallexample
7003 (setq animals '(antelope giraffe lion tiger))
7004 @end smallexample
7006 @noindent
7007 If you are reading this in Info inside of GNU Emacs, you can evaluate
7008 this expression in the usual fashion, by positioning the cursor after
7009 the expression and typing @kbd{C-x C-e}.  (I'm doing this right here as
7010 I write this.  This is one of the advantages of having the interpreter
7011 built into the computing environment.)
7013 @need 1200
7014 When we evaluate the variable @code{animals}, we see that it is bound to
7015 the list @code{(antelope giraffe lion tiger)}:
7017 @smallexample
7018 @group
7019 animals
7020      @result{} (antelope giraffe lion tiger)
7021 @end group
7022 @end smallexample
7024 @noindent
7025 Put another way, the variable @code{animals} points to the list
7026 @code{(antelope giraffe lion tiger)}.
7028 Next, evaluate the function @code{setcar} while passing it two
7029 arguments, the variable @code{animals} and the quoted symbol
7030 @code{hippopotamus}; this is done by writing the three element list
7031 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
7032 usual fashion:
7034 @smallexample
7035 (setcar animals 'hippopotamus)
7036 @end smallexample
7038 @need 1200
7039 @noindent
7040 After evaluating this expression, evaluate the variable @code{animals}
7041 again.  You will see that the list of animals has changed:
7043 @smallexample
7044 @group
7045 animals
7046      @result{} (hippopotamus giraffe lion tiger)
7047 @end group
7048 @end smallexample
7050 @noindent
7051 The first element on the list, @code{antelope} is replaced by
7052 @code{hippopotamus}.
7054 So we can see that @code{setcar} did not add a new element to the list
7055 as @code{cons} would have; it replaced @code{giraffe} with
7056 @code{hippopotamus}; it @emph{changed} the list.
7058 @node setcdr, cons Exercise, setcar, car cdr & cons
7059 @comment  node-name,  next,  previous,  up
7060 @section @code{setcdr}
7061 @findex setcdr
7063 The @code{setcdr} function is similar to the @code{setcar} function,
7064 except that the function replaces the second and subsequent elements of
7065 a list rather than the first element.
7067 (To see how to change the last element of a list, look ahead to
7068 @ref{kill-new function, , The @code{kill-new} function}, which uses
7069 the @code{nthcdr} and @code{setcdr} functions.)
7071 @need 1200
7072 To see how this works, set the value of the variable to a list of
7073 domesticated animals by evaluating the following expression:
7075 @smallexample
7076 (setq domesticated-animals '(horse cow sheep goat))
7077 @end smallexample
7079 @need 1200
7080 @noindent
7081 If you now evaluate the list, you will be returned the list
7082 @code{(horse cow sheep goat)}:
7084 @smallexample
7085 @group
7086 domesticated-animals
7087      @result{} (horse cow sheep goat)
7088 @end group
7089 @end smallexample
7091 @need 1200
7092 Next, evaluate @code{setcdr} with two arguments, the name of the
7093 variable which has a list as its value, and the list to which the
7094 @sc{cdr} of the first list will be set;
7096 @smallexample
7097 (setcdr domesticated-animals '(cat dog))
7098 @end smallexample
7100 @noindent
7101 If you evaluate this expression, the list @code{(cat dog)} will appear
7102 in the echo area.  This is the value returned by the function.  The
7103 result we are interested in is the ``side effect'', which we can see by
7104 evaluating the variable @code{domesticated-animals}:
7106 @smallexample
7107 @group
7108 domesticated-animals
7109      @result{} (horse cat dog)
7110 @end group
7111 @end smallexample
7113 @noindent
7114 Indeed, the list is changed from @code{(horse cow sheep goat)} to
7115 @code{(horse cat dog)}.  The @sc{cdr} of the list is changed from
7116 @code{(cow sheep goat)} to @code{(cat dog)}.
7118 @node cons Exercise,  , setcdr, car cdr & cons
7119 @section Exercise
7121 Construct a list of four birds by evaluating several expressions with
7122 @code{cons}.  Find out what happens when you @code{cons} a list onto
7123 itself.  Replace the first element of the list of four birds with a
7124 fish.  Replace the rest of that list with a list of other fish.
7126 @node Cutting & Storing Text, List Implementation, car cdr & cons, Top
7127 @comment  node-name,  next,  previous,  up
7128 @chapter Cutting and Storing Text
7129 @cindex Cutting and storing text
7130 @cindex Storing and cutting text
7131 @cindex Killing text
7132 @cindex Clipping text
7133 @cindex Erasing text
7134 @cindex Deleting text
7136 Whenever you cut or clip text out of a buffer with a `kill' command in
7137 GNU Emacs, it is stored in a list and you can bring it back with a
7138 `yank' command.
7140 (The use of the word `kill' in Emacs for processes which specifically
7141 @emph{do not} destroy the values of the entities is an unfortunate
7142 historical accident.  A much more appropriate word would be `clip' since
7143 that is what the kill commands do; they clip text out of a buffer and
7144 put it into storage from which it can be brought back.  I have often
7145 been tempted to replace globally all occurrences of `kill' in the Emacs
7146 sources with `clip' and all occurrences of `killed' with `clipped'.)
7148 @menu
7149 * Storing Text::                Text is stored in a list.
7150 * zap-to-char::                 Cutting out text up to a character.
7151 * kill-region::                 Cutting text out of a region.
7152 * Digression into C::           Minor note on C programming language macros.
7153 * defvar::                      How to give a variable an initial value.
7154 * copy-region-as-kill::         A definition for copying text.
7155 * cons & search-fwd Review::
7156 * search Exercises::
7157 @end menu
7159 @node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text
7160 @ifnottex
7161 @unnumberedsec Storing Text in a List
7162 @end ifnottex
7164 When text is cut out of a buffer, it is stored on a list.  Successive
7165 pieces of text are stored on the list successively, so the list might
7166 look like this:
7168 @smallexample
7169 ("a piece of text" "previous piece")
7170 @end smallexample
7172 @need 1200
7173 @noindent
7174 The function @code{cons} can be used to to create a new list from a
7175 piece of text (an `atom', to use the jargon) and an existing list,
7176 like this:
7178 @smallexample
7179 @group
7180 (cons "another piece"
7181       '("a piece of text" "previous piece"))
7182 @end group
7183 @end smallexample
7185 @need 1200
7186 @noindent
7187 If you evaluate this expression, a list of three elements will appear in
7188 the echo area:
7190 @smallexample
7191 ("another piece" "a piece of text" "previous piece")
7192 @end smallexample
7194 With the @code{car} and @code{nthcdr} functions, you can retrieve
7195 whichever piece of text you want.  For example, in the following code,
7196 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
7197 and the @code{car} returns the first element of that remainder---the
7198 second element of the original list:
7200 @smallexample
7201 @group
7202 (car (nthcdr 1 '("another piece"
7203                  "a piece of text"
7204                  "previous piece")))
7205      @result{} "a piece of text"
7206 @end group
7207 @end smallexample
7209 The actual functions in Emacs are more complex than this, of course.
7210 The code for cutting and retrieving text has to be written so that
7211 Emacs can figure out which element in the list you want---the first,
7212 second, third, or whatever.  In addition, when you get to the end of
7213 the list, Emacs should give you the first element of the list, rather
7214 than nothing at all.
7216 The list that holds the pieces of text is called the @dfn{kill ring}.
7217 This chapter leads up to a description of the kill ring and how it is
7218 used by first tracing how the @code{zap-to-char} function works.  This
7219 function uses (or `calls') a function that invokes a function that
7220 manipulates the kill ring.  Thus, before reaching the mountains, we
7221 climb the foothills.
7223 A subsequent chapter describes how text that is cut from the buffer is
7224 retrieved.  @xref{Yanking, , Yanking Text Back}.
7226 @node zap-to-char, kill-region, Storing Text, Cutting & Storing Text
7227 @comment  node-name,  next,  previous,  up
7228 @section @code{zap-to-char}
7229 @findex zap-to-char
7231 The @code{zap-to-char} function barely changed between GNU Emacs
7232 version 19 and GNU Emacs version 21.  However, @code{zap-to-char}
7233 calls another function, @code{kill-region}, which enjoyed a major rewrite
7234 on the way to version 21.
7236 The @code{kill-region} function in Emacs 19 is complex, but does not
7237 use code that is important at this time.  We will skip it.
7239 The @code{kill-region} function in Emacs 21 is easier to read than the
7240 same function in Emacs 19 and introduces a very important concept,
7241 that of error handling.  We will walk through the function.
7243 But first, let us look at the interactive @code{zap-to-char} function.
7245 @menu
7246 * Complete zap-to-char::        The complete implementation.
7247 * zap-to-char interactive::     A three part interactive expression.
7248 * zap-to-char body::            A short overview.
7249 * search-forward::              How to search for a string.
7250 * progn::                       The @code{progn} special form.
7251 * Summing up zap-to-char::      Using @code{point} and @code{search-forward}.
7252 @end menu
7254 @node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
7255 @ifnottex
7256 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
7257 @end ifnottex
7259 The GNU Emacs version 19 and version 21 implementations of the
7260 @code{zap-to-char} function are nearly identical in form, and they
7261 work alike.  The function removes the text in the region between the
7262 location of the cursor (i.e., of point) up to and including the next
7263 occurrence of a specified character.  The text that @code{zap-to-char}
7264 removes is put in the kill ring; and it can be retrieved from the kill
7265 ring by typing @kbd{C-y} (@code{yank}).  If the command is given an
7266 argument, it removes text through that number of occurrences.  Thus,
7267 if the cursor were at the beginning of this sentence and the character
7268 were @samp{s}, @samp{Thus} would be removed.  If the argument were
7269 two, @samp{Thus, if the curs} would be removed, up to and including
7270 the @samp{s} in @samp{cursor}.
7272 If the specified character is not found, @code{zap-to-char} will say
7273 ``Search failed'', tell you the character you typed, and not remove
7274 any text.
7276 In order to determine how much text to remove, @code{zap-to-char} uses
7277 a search function.  Searches are used extensively in code that
7278 manipulates text, and we will focus attention on them as well as on the
7279 deletion command.
7281 @need 800
7282 Here is the complete text of the version 19 implementation of the function:
7284 @c v 19
7285 @smallexample
7286 @group
7287 (defun zap-to-char (arg char)  ; version 19 implementation
7288   "Kill up to and including ARG'th occurrence of CHAR.
7289 Goes backward if ARG is negative; error if CHAR not found."
7290   (interactive "*p\ncZap to char: ")
7291   (kill-region (point)
7292                (progn
7293                  (search-forward
7294                   (char-to-string char) nil nil arg)
7295                  (point))))
7296 @end group
7297 @end smallexample
7299 @node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char
7300 @comment  node-name,  next,  previous,  up
7301 @subsection The @code{interactive} Expression
7303 @need 800
7304 The interactive expression in the @code{zap-to-char} command looks like
7305 this:
7307 @smallexample
7308 (interactive "*p\ncZap to char: ")
7309 @end smallexample
7311 The part within quotation marks, @code{"*p\ncZap to char:@: "}, specifies
7312 three different things.  First, and most simply, the asterisk, @samp{*},
7313 causes an error to be signalled if the buffer is read-only.  This means that
7314 if you try @code{zap-to-char} in a read-only buffer you will not be able to
7315 remove text, and you will receive a message that says ``Buffer is
7316 read-only''; your terminal may beep at you as well.
7318 The version 21 implementation does not have the asterisk, @samp{*}.  The
7319 function works the same as in version 19: in both cases, it cannot
7320 remove text from a read-only buffer but the function does copy the
7321 text that would have been removed to the kill ring.  Also, in both
7322 cases, you see an error message.
7324 However, the version 19 implementation copies text from a read-only
7325 buffer only because of a mistake in the implementation of
7326 @code{interactive}.  According to the documentation for
7327 @code{interactive}, the asterisk, @samp{*}, should prevent the
7328 @code{zap-to-char} function from doing anything at all when the buffer
7329 is read only.  In version 19, the function should not copy the text to
7330 the kill ring.  It is a bug that it does.
7332 In version 21, the function is designed to copy the text to the kill
7333 ring; moreover, @code{interactive} is implemented correctly.  So the
7334 asterisk, @samp{*}, had to be removed from the interactive
7335 specification.  However, if you insert an @samp{*} yourself and
7336 evaluate the function definition, then the next time you run the
7337 @code{zap-to-char} function on a read-only buffer, you will not copy
7338 any text.
7340 That change aside, and a change to the documentation, the two versions
7341 of the  @code{zap-to-char} function are identical.
7343 Let us continue with the interactive specification.
7345 The second part of @code{"*p\ncZap to char:@: "} is the @samp{p}.
7346 This part is separated from the next part by a newline, @samp{\n}.
7347 The @samp{p} means that the first argument to the function will be
7348 passed the value of a `processed prefix'.  The prefix argument is
7349 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number.  If
7350 the function is called interactively without a prefix, 1 is passed to
7351 this argument.
7353 The third part of @code{"*p\ncZap to char:@: "} is @samp{cZap to char:@:
7354 }.  In this part, the lower case @samp{c} indicates that
7355 @code{interactive} expects a prompt and that the argument will be a
7356 character.  The prompt follows the @samp{c} and is the string @samp{Zap
7357 to char:@: } (with a space after the colon to make it look good).
7359 What all this does is prepare the arguments to @code{zap-to-char} so they
7360 are of the right type, and give the user a prompt.
7362 @node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
7363 @comment  node-name,  next,  previous,  up
7364 @subsection The Body of @code{zap-to-char}
7366 The body of the @code{zap-to-char} function contains the code that
7367 kills (that is, removes) the text in the region from the current
7368 position of the cursor up to and including the specified character.
7369 The first part of the code looks like this:
7371 @smallexample
7372 (kill-region (point) @dots{}
7373 @end smallexample
7375 @noindent
7376 @code{(point)} is the current position of the cursor.
7378 The next part of the code is an expression using @code{progn}.  The body
7379 of the @code{progn} consists of calls to @code{search-forward} and
7380 @code{point}.
7382 It is easier to understand how @code{progn} works after learning about
7383 @code{search-forward}, so we will look at @code{search-forward} and
7384 then at @code{progn}.
7386 @node search-forward, progn, zap-to-char body, zap-to-char
7387 @comment  node-name,  next,  previous,  up
7388 @subsection The @code{search-forward} Function
7389 @findex search-forward
7391 The @code{search-forward} function is used to locate the
7392 zapped-for-character in @code{zap-to-char}.  If the search is
7393 successful, @code{search-forward} leaves point immediately after the
7394 last character in the target string.  (In @code{zap-to-char}, the
7395 target string is just one character long.)  If the search is
7396 backwards, @code{search-forward} leaves point just before the first
7397 character in the target.  Also, @code{search-forward} returns @code{t}
7398 for true.  (Moving point is therefore a `side effect'.)
7400 @need 1250
7401 In @code{zap-to-char}, the @code{search-forward} function looks like this:
7403 @smallexample
7404 (search-forward (char-to-string char) nil nil arg)
7405 @end smallexample
7407 The @code{search-forward} function takes four arguments:
7409 @enumerate
7410 @item
7411 The first argument is the target, what is searched for.  This must be a
7412 string, such as @samp{"z"}.
7414 As it happens, the argument passed to @code{zap-to-char} is a single
7415 character.  Because of the way computers are built, the Lisp
7416 interpreter may treat a single character as being different from a
7417 string of characters.  Inside the computer, a single character has a
7418 different electronic format than a string of one character.  (A single
7419 character can often be recorded in the computer using exactly one
7420 byte; but a string may be longer, and the computer needs to be ready
7421 for this.)  Since the @code{search-forward} function searches for a
7422 string, the character that the @code{zap-to-char} function receives as
7423 its argument must be converted inside the computer from one format to
7424 the other; otherwise the @code{search-forward} function will fail.
7425 The @code{char-to-string} function is used to make this conversion.
7427 @item
7428 The second argument bounds the search; it is specified as a position in
7429 the buffer.  In this case, the search can go to the end of the buffer,
7430 so no bound is set and the second argument is @code{nil}.
7432 @item
7433 The third argument tells the function what it should do if the search
7434 fails---it can signal an error (and print a message) or it can return
7435 @code{nil}.  A @code{nil} as the third argument causes the function to
7436 signal an error when the search fails.
7438 @item
7439 The fourth argument to @code{search-forward} is the repeat count---how
7440 many occurrences of the string to look for.  This argument is optional
7441 and if the function is called without a repeat count, this argument is
7442 passed the value 1.  If this argument is negative, the search goes
7443 backwards.
7444 @end enumerate
7446 @need 800
7447 In template form, a @code{search-forward} expression looks like this:
7449 @smallexample
7450 @group
7451 (search-forward "@var{target-string}"
7452                 @var{limit-of-search}
7453                 @var{what-to-do-if-search-fails}
7454                 @var{repeat-count})
7455 @end group
7456 @end smallexample
7458 We will look at @code{progn} next.
7460 @node progn, Summing up zap-to-char, search-forward, zap-to-char
7461 @comment  node-name,  next,  previous,  up
7462 @subsection The @code{progn} Special Form
7463 @findex progn
7465 @code{progn} is a special form that causes each of its arguments to be
7466 evaluated in sequence and then returns the value of the last one.  The
7467 preceding expressions are evaluated only for the side effects they
7468 perform.  The values produced by them are discarded.
7470 @need 800
7471 The template for a @code{progn} expression is very simple:
7473 @smallexample
7474 @group
7475 (progn
7476   @var{body}@dots{})
7477 @end group
7478 @end smallexample
7480 In @code{zap-to-char}, the @code{progn} expression has to do two things:
7481 put point in exactly the right position; and return the location of
7482 point so that @code{kill-region} will know how far to kill to.
7484 The first argument to the @code{progn} is @code{search-forward}.  When
7485 @code{search-forward} finds the string, the function leaves point
7486 immediately after the last character in the target string.  (In this
7487 case the target string is just one character long.)  If the search is
7488 backwards, @code{search-forward} leaves point just before the first
7489 character in the target.  The movement of point is a side effect.
7491 The second and last argument to @code{progn} is the expression
7492 @code{(point)}.  This expression returns the value of point, which in
7493 this case will be the location to which it has been moved by
7494 @code{search-forward}.  This value is returned by the @code{progn}
7495 expression and is passed to @code{kill-region} as @code{kill-region}'s
7496 second argument.
7498 @node Summing up zap-to-char,  , progn, zap-to-char
7499 @comment  node-name,  next,  previous,  up
7500 @subsection Summing up @code{zap-to-char}
7502 Now that we have seen how @code{search-forward} and @code{progn} work,
7503 we can see how the @code{zap-to-char} function works as a whole.
7505 The first argument to @code{kill-region} is the position of the cursor
7506 when the @code{zap-to-char} command is given---the value of point at
7507 that time.  Within the @code{progn}, the search function then moves
7508 point to just after the zapped-to-character and @code{point} returns the
7509 value of this location.  The @code{kill-region} function puts together
7510 these two values of point, the first one as the beginning of the region
7511 and the second one as the end of the region, and removes the region.
7513 The @code{progn} special form is necessary because the @code{kill-region}
7514 command takes two arguments; and it would fail if @code{search-forward}
7515 and @code{point} expressions were  written in sequence as two
7516 additional arguments.  The @code{progn} expression is a single argument
7517 to @code{kill-region} and returns the one value that @code{kill-region}
7518 needs for its second argument.
7520 @node kill-region, Digression into C, zap-to-char, Cutting & Storing Text
7521 @comment  node-name,  next,  previous,  up
7522 @section @code{kill-region}
7523 @findex kill-region
7525 The @code{zap-to-char} function uses the @code{kill-region} function.
7526 This function clips text from a region and copies that text to
7527 the kill ring, from which it may be retrieved.
7529 The Emacs 21 version of that function uses @code{condition-case} and
7530 @code{copy-region-as-kill}, both of which we will explain.
7531 @code{condition-case} is an important special form.
7533 In essence, the @code{kill-region} function calls
7534 @code{condition-case}, which takes three arguments.  In this function,
7535 the first argument does nothing.  The second argument contains the
7536 code that does the work when all goes well.  The third argument
7537 contains the code that is called in the event of an error.
7539 @menu
7540 * Complete kill-region::        The function definition.
7541 * condition-case::              Dealing with a problem.
7542 * delete-and-extract-region::   Doing the work.
7543 @end menu
7545 @node Complete kill-region, condition-case, kill-region, kill-region
7546 @ifnottex
7547 @unnumberedsubsec The Complete @code{kill-region} Definition
7548 @end ifnottex
7550 @need 1200
7551 We will go through the @code{condition-case} code in a moment.  First,
7552 let us look at the original definition of @code{kill-region}, with
7553 comments added (the newer definition has an optional third argument
7554 and is more complex):
7556 @c v 21
7557 @smallexample
7558 @group
7559 (defun kill-region (beg end)
7560   "Kill between point and mark.
7561 The text is deleted but saved in the kill ring."
7562   (interactive "r")
7563 @end group
7565 @group
7566   ;; 1. `condition-case' takes three arguments.
7567   ;;    If the first argument is nil, as it is here,
7568   ;;    information about the error signal is not
7569   ;;    stored for use by another function.
7570   (condition-case nil
7571 @end group
7573 @group
7574       ;; 2. The second argument to `condition-case'
7575       ;;    tells the Lisp interpreter what to do when all goes well.
7576 @end group
7578 @group
7579       ;;    The `delete-and-extract-region' function usually does the
7580       ;;    work.  If the beginning and ending of the region are both
7581       ;;    the same, then the variable `string' will be empty, or nil
7582       (let ((string (delete-and-extract-region beg end)))
7583 @end group
7585 @group
7586         ;; `when' is an `if' clause that cannot take an `else-part'.
7587         ;; Emacs normally sets the value of `last-command' to the
7588         ;; previous command.
7589 @end group
7590 @group
7591         ;; `kill-append' concatenates the new string and the old.
7592         ;; `kill-new' inserts text into a new item in the kill ring.
7593         (when string
7594           (if (eq last-command 'kill-region)
7595               ;; if true, prepend string
7596               (kill-append string (< end beg))
7597             (kill-new string)))
7598         (setq this-command 'kill-region))
7599 @end group
7601 @group
7602     ;; 3. The third argument to `condition-case' tells the interpreter
7603     ;;    what to do with an error.
7604 @end group
7605 @group
7606     ;;    The third argument has a conditions part and a body part.
7607     ;;    If the conditions are met (in this case,
7608     ;;             if text or buffer is read-only)
7609     ;;    then the body is executed.
7610 @end group
7611 @group
7612     ((buffer-read-only text-read-only) ;; this is the if-part
7613      ;; then...
7614      (copy-region-as-kill beg end)
7615 @end group
7616 @group
7617      (if kill-read-only-ok            ;; usually this variable is nil
7618          (message "Read only text copied to kill ring")
7619        ;; or else, signal an error if the buffer is read-only;
7620        (barf-if-buffer-read-only)
7621        ;; and, in any case, signal that the text is read-only.
7622        (signal 'text-read-only (list (current-buffer)))))))
7623 @end group
7624 @end smallexample
7626 @node condition-case, delete-and-extract-region, Complete kill-region, kill-region
7627 @comment  node-name,  next,  previous,  up
7628 @subsection @code{condition-case}
7629 @findex condition-case
7631 As we have seen earlier (@pxref{Making Errors, , Generate an Error
7632 Message}), when the Emacs Lisp interpreter has trouble evaluating an
7633 expression, it provides you with help; in the jargon, this is called
7634 ``signaling an error''.  Usually, the computer stops the program and
7635 shows you a message.
7637 However, some programs undertake complicated actions.  They should not
7638 simply stop on an error.  In the @code{kill-region} function, the most
7639 likely error is that you will try to kill text that is read-only and
7640 cannot be removed.  So the @code{kill-region} function contains code
7641 to handle this circumstance.  This code, which makes up the body of
7642 the @code{kill-region} function, is inside of a @code{condition-case}
7643 special form.
7645 @need 800
7646 The template for @code{condition-case} looks like this:
7648 @smallexample
7649 @group
7650 (condition-case
7651   @var{var}
7652   @var{bodyform}
7653   @var{error-handler}@dots{})
7654 @end group
7655 @end smallexample
7657 The second argument, @var{bodyform}, is straightforward.  The
7658 @code{condition-case} special form causes the Lisp interpreter to
7659 evaluate the code in @var{bodyform}.  If no error occurs, the special
7660 form returns the code's value and produces the side-effects, if any.
7662 In short, the @var{bodyform} part of a @code{condition-case}
7663 expression determines what should happen when everything works
7664 correctly.
7666 However, if an error occurs, among its other actions, the function
7667 generating the error signal will define one or more error condition
7668 names.
7670 An error handler is the third argument to @code{condition case}.
7671 An error handler has two parts, a @var{condition-name} and a
7672 @var{body}.  If the @var{condition-name} part of an error handler
7673 matches a condition name generated by an error, then the @var{body}
7674 part of the error handler is run.
7676 As you will expect, the @var{condition-name} part of an error handler
7677 may be either a single condition name or a list of condition names.
7679 Also, a complete @code{condition-case} expression may contain more
7680 than one error handler.  When an error occurs, the first applicable
7681 handler is run.
7683 Lastly, the first argument to the @code{condition-case} expression,
7684 the @var{var} argument, is sometimes bound to a variable that
7685 contains information about the error.  However, if that argument is
7686 nil, as is the case in @code{kill-region}, that information is
7687 discarded.
7689 @need 1200
7690 In brief, in the @code{kill-region} function, the code
7691 @code{condition-case} works like this:
7693 @smallexample
7694 @group
7695 @var{If no errors}, @var{run only this code}
7696     @var{but}, @var{if errors}, @var{run this other code}.
7697 @end group
7698 @end smallexample
7700 @node delete-and-extract-region,  , condition-case, kill-region
7701 @comment  node-name,  next,  previous,  up
7702 @subsection @code{delete-and-extract-region}
7703 @findex delete-and-extract-region
7705 A @code{condition-case} expression has two parts, a part that is
7706 evaluated in the expectation that all will go well, but which may
7707 generate an error; and a part that is evaluated when there is an
7708 error.
7710 First, let us look at the code in @code{kill-region} that is run in
7711 the expectation that all goes well.  This is the core of the function.
7712 The code looks like this:
7714 @smallexample
7715 @group
7716 (let ((string (delete-and-extract-region beg end)))
7717   (when string
7718     (if (eq last-command 'kill-region)
7719         (kill-append string (< end beg))
7720       (kill-new string)))
7721   (setq this-command 'kill-region))
7722 @end group
7723 @end smallexample
7725 It looks complicated because we have the new functions
7726 @code{delete-and-extract-region}, @code{kill-append}, and
7727 @code{kill-new} as well as the new variables,
7728 @code{last-command} and @code{this-command}.
7730 The @code{delete-and-extract-region} function is straightforward.  It
7731 is a built-in function that deletes the text in a region (a side
7732 effect) and also returns that text.  This is the function that
7733 actually removes the text.  (And if it cannot do that, it signals the
7734 error.)
7736 In this @code{let} expression, the text that
7737 @code{delete-and-extract-region} returns is placed in the local
7738 variable called @samp{string}.  This is the text that is removed from
7739 the buffer.  (To be more precise, the variable is set to point to the
7740 address of the extracted text; to say it is `placed in' the variable
7741 is simply a shorthand.)
7743 If the variable @samp{string} does point to text, that text is added
7744 to the kill ring.  The variable will have a @code{nil} value if no
7745 text was removed.
7747 The code uses @code{when} to determine whether the variable
7748 @samp{string} points to text.  A @code{when} statement is simply a
7749 programmers' convenience.  A @code{when} statement is an @code{if}
7750 statement without the possibility of an else clause.  In your mind, you
7751 can replace @code{when} with @code{if} and understand what goes on.
7752 That is what the Lisp interpreter does.
7754 @cindex Macro, lisp
7755 @cindex Lisp macro
7756 Technically speaking, @code{when} is a Lisp macro.  A Lisp @dfn{macro}
7757 enables you to define new control constructs and other language
7758 features.  It tells the interpreter how to compute another Lisp
7759 expression which will in turn compute the value.  In this case, the
7760 `other expression' is an @code{if} expression.  For more about Lisp
7761 macros, see @ref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference
7762 Manual}.  The C programming language also provides macros.  These are
7763 different, but also useful.  We will briefly look at C macros in
7764 @ref{Digression into C}.
7766 @need 1200
7767 If the string has content, then another conditional expression is
7768 executed.  This is an @code{if} with both a then-part and an else-part.
7770 @smallexample
7771 @group
7772 (if (eq last-command 'kill-region)
7773     (kill-append string (< end beg))
7774   (kill-new string)))
7775 @end group
7776 @end smallexample
7778 The then-part is evaluated if the previous command was another call to
7779 @code{kill-region}; if not, the else-part is evaluated.
7781 @code{last-command} is a variable that comes with Emacs that we have
7782 not seen before.  Normally, whenever a function is executed, Emacs
7783 sets the value of @code{last-command} to the previous command.
7785 @need 1200
7786 In this segment of the definition, the @code{if} expression checks
7787 whether the previous command was @code{kill-region}.  If it was,
7789 @smallexample
7790 (kill-append string (< end beg))
7791 @end smallexample
7793 @noindent
7794 concatenates a copy of the newly clipped text to the just previously
7795 clipped text in the kill ring.  (If the @w{@code{(< end beg))}}
7796 expression is true, @code{kill-append} prepends the string to the just
7797 previously clipped text.  For a detailed discussion, see
7798 @ref{kill-append function, , The @code{kill-append} function}.)
7800 If you then yank back the text, i.e., `paste' it, you get both
7801 pieces of text at once.  That way, if you delete two words in a row,
7802 and then yank them back, you get both words, in their proper order,
7803 with one yank.  (The @w{@code{(< end beg))}} expression makes sure the
7804 order is correct.)
7806 On the other hand, if the previous command is not @code{kill-region},
7807 then the @code{kill-new} function is called, which adds the text to
7808 the kill ring as the latest item, and sets the
7809 @code{kill-ring-yank-pointer} variable to point to it.
7811 @node Digression into C, defvar, kill-region, Cutting & Storing Text
7812 @comment  node-name,  next,  previous,  up
7813 @section Digression into C
7814 @findex delete-and-extract-region
7815 @cindex C, a digression into
7816 @cindex Digression into C
7818 The @code{zap-to-char} command uses the
7819 @code{delete-and-extract-region} function, which in turn uses two
7820 other functions, @code{copy-region-as-kill} and
7821 @code{del_range_1}.  The @code{copy-region-as-kill} function will be
7822 described in a following section; it puts a copy of the region in the
7823 kill ring so it can be yanked back.  (@xref{copy-region-as-kill, ,
7824 @code{copy-region-as-kill}}.)
7826 The @code{delete-and-extract-region} function removes the contents of
7827 a region and you cannot get them back.
7829 Unlike the other code discussed here, @code{delete-and-extract-region}
7830 is not written in Emacs Lisp; it is written in C and is one of the
7831 primitives of the GNU Emacs system.  Since it is very simple, I will
7832 digress briefly from Lisp and describe it here.
7834 @need 1500
7835 Like many of the other Emacs primitives,
7836 @code{delete-and-extract-region} is written as an instance of a C
7837 macro, a macro being a template for code.  The complete macro looks
7838 like this:
7840 @c /usr/local/src/emacs/src/editfns.c
7841 @smallexample
7842 @group
7843 DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
7844        Sdelete_and_extract_region, 2, 2, 0,
7845   "Delete the text between START and END and return it.")
7846   (start, end)
7847      Lisp_Object start, end;
7849   validate_region (&start, &end);
7850   return del_range_1 (XINT (start), XINT (end), 1, 1);
7852 @end group
7853 @end smallexample
7855 Without going into the details of the macro writing process, let me
7856 point out that this macro starts with the word @code{DEFUN}.  The word
7857 @code{DEFUN} was chosen since the code serves the same purpose as
7858 @code{defun} does in Lisp.  The word @code{DEFUN} is followed by seven
7859 parts inside of parentheses:
7861 @itemize @bullet
7862 @item
7863 The first part is the name given to the function in Lisp,
7864 @code{delete-and-extract-region}.
7866 @item
7867 The second part is the name of the function in C,
7868 @code{Fdelete_and_extract_region}.  By convention, it starts with
7869 @samp{F}.  Since C does not use hyphens in names, underscores are used
7870 instead.
7872 @item
7873 The third part is the name for the C constant structure that records
7874 information on this function for internal use.  It is the name of the
7875 function in C but begins with an @samp{S} instead of an @samp{F}.
7877 @item
7878 The fourth and fifth parts specify the minimum and maximum number of
7879 arguments the function can have.  This function demands exactly 2
7880 arguments.
7882 @item
7883 The sixth part is nearly like the argument that follows the
7884 @code{interactive} declaration in a function written in Lisp: a letter
7885 followed, perhaps, by a prompt.  The only difference from the Lisp is
7886 when the macro is called with no arguments.  Then you write a @code{0}
7887 (which is a `null string'), as in this macro.
7889 If you were to specify arguments, you would place them between
7890 quotation marks.  The C macro for @code{goto-char} includes
7891 @code{"NGoto char: "} in this position to indicate that the function
7892 expects a raw prefix, in this case, a numerical location in a buffer,
7893 and provides a prompt.
7895 @item
7896 The seventh part is a documentation string, just like the one for a
7897 function written in Emacs Lisp, except that every newline must be
7898 written explicitly as @samp{\n} followed by a backslash and carriage
7899 return.
7901 @need 1000
7902 Thus, the first two lines of documentation for  @code{goto-char} are
7903 written like this:
7905 @smallexample
7906 @group
7907   "Set point to POSITION, a number or marker.\n\
7908 Beginning of buffer is position (point-min), end is (point-max).
7909 @end group
7910 @end smallexample
7911 @end itemize
7913 @need 1200
7914 In a C macro, the formal parameters come next, with a statement of
7915 what kind of object they are, followed by what might be called the `body'
7916 of the macro.  For @code{delete-and-extract-region} the `body'
7917 consists of the following two lines:
7919 @smallexample
7920 @group
7921 validate_region (&start, &end);
7922 return del_range_1 (XINT (start), XINT (end), 1, 1);
7923 @end group
7924 @end smallexample
7926 The first function, @code{validate_region} checks whether the values
7927 passed as the beginning and end of the region are the proper type and
7928 are within range.  The second function, @code{del_range_1}, actually
7929 deletes the text.
7931 @code{del_range_1} is a complex function we will not look into.  It
7932 updates the buffer and does other things.
7934 However, it is worth looking at the two arguments passed to
7935 @code{del_range}.  These are @w{@code{XINT (start)}} and @w{@code{XINT
7936 (end)}}.
7938 As far as the C language is concerned, @code{start} and @code{end} are
7939 two integers that mark the beginning and end of the region to be
7940 deleted@footnote{More precisely, and requiring more expert knowledge
7941 to understand, the two integers are of type `Lisp_Object', which can
7942 also be a C union instead of an integer type.}.
7944 In early versions of Emacs, these two numbers were thirty-two bits
7945 long, but the code is slowly being generalized to handle other
7946 lengths.  Three of the available bits are used to specify the type of
7947 information and a fourth bit is used for handling the computer's
7948 memory; the remaining bits are used as `content'.
7950 @samp{XINT} is a C macro that extracts the relevant number from the
7951 longer collection of bits; the four other bits are discarded.
7953 @need 800
7954 The command in @code{delete-and-extract-region} looks like this:
7956 @smallexample
7957 del_range_1 (XINT (start), XINT (end), 1, 1);
7958 @end smallexample
7960 @noindent
7961 It deletes the region between the beginning position, @code{start},
7962 and the ending position, @code{end}.
7964 From the point of view of the person writing Lisp, Emacs is all very
7965 simple; but hidden underneath is a great deal of complexity to make it
7966 all work.
7968 @node defvar, copy-region-as-kill, Digression into C, Cutting & Storing Text
7969 @comment  node-name,  next,  previous,  up
7970 @section Initializing a Variable with @code{defvar}
7971 @findex defvar
7972 @cindex Initializing a variable
7973 @cindex Variable initialization
7975 Unlike the @code{delete-and-extract-region} function, the
7976 @code{copy-region-as-kill} function is written in Emacs Lisp.  Two
7977 functions within it, @code{kill-append} and @code{kill-new}, copy a
7978 region in a buffer and save it in a variable called the
7979 @code{kill-ring}.  This section describes how the @code{kill-ring}
7980 variable is created and initialized using the @code{defvar} special
7981 form.
7983 (Again we note that the term @code{kill-ring} is a misnomer.  The text
7984 that is clipped out of the buffer can be brought back; it is not a ring
7985 of corpses, but a ring of resurrectable text.)
7987 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
7988 given an initial value by using the @code{defvar} special form.  The
7989 name comes from ``define variable''.
7991 The @code{defvar} special form is similar to @code{setq} in that it sets
7992 the value of a variable.  It is unlike @code{setq} in two ways: first,
7993 it only sets the value of the variable if the variable does not already
7994 have a value.  If the variable already has a value, @code{defvar} does
7995 not override the existing value.  Second, @code{defvar} has a
7996 documentation string.
7998 (Another special form, @code{defcustom}, is designed for variables
7999 that people customize.  It has more features than @code{defvar}.
8000 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
8002 @menu
8003 * See variable current value::
8004 * defvar and asterisk::         An old-time convention.
8005 @end menu
8007 @node See variable current value, defvar and asterisk, defvar, defvar
8008 @ifnottex
8009 @unnumberedsubsec Seeing the Current Value of a Variable
8010 @end ifnottex
8012 You can see the current value of a variable, any variable, by using
8013 the @code{describe-variable} function, which is usually invoked by
8014 typing @kbd{C-h v}.  If you type @kbd{C-h v} and then @code{kill-ring}
8015 (followed by @key{RET}) when prompted, you will see what is in your
8016 current kill ring---this may be quite a lot!  Conversely, if you have
8017 been doing nothing this Emacs session except read this document, you
8018 may have nothing in it.  Also, you will see the documentation for
8019 @code{kill-ring}:
8021 @smallexample
8022 @group
8023 Documentation:
8024 List of killed text sequences.
8025 Since the kill ring is supposed to interact nicely with cut-and-paste
8026 facilities offered by window systems, use of this variable should
8027 @end group
8028 @group
8029 interact nicely with `interprogram-cut-function' and
8030 `interprogram-paste-function'.  The functions `kill-new',
8031 `kill-append', and `current-kill' are supposed to implement this
8032 interaction; you may want to use them instead of manipulating the kill
8033 ring directly.
8034 @end group
8035 @end smallexample
8037 @need 800
8038 The kill ring is defined by a @code{defvar} in the following way:
8040 @smallexample
8041 @group
8042 (defvar kill-ring nil
8043   "List of killed text sequences.
8044 @dots{}")
8045 @end group
8046 @end smallexample
8048 @noindent
8049 In this variable definition, the variable is given an initial value of
8050 @code{nil}, which makes sense, since if you have saved nothing, you want
8051 nothing back if you give a @code{yank} command.  The documentation
8052 string is written just like the documentation string of a @code{defun}.
8053 As with the documentation string of the @code{defun}, the first line of
8054 the documentation should be a complete sentence, since some commands,
8055 like @code{apropos}, print only the first line of documentation.
8056 Succeeding lines should not be indented; otherwise they look odd when
8057 you use @kbd{C-h v} (@code{describe-variable}).
8059 @node defvar and asterisk,  , See variable current value, defvar
8060 @subsection @code{defvar} and an asterisk
8061 @findex defvar @r{for a user customizable variable}
8062 @findex defvar @r{with an asterisk}
8064 In the past, Emacs used the @code{defvar} special form both for
8065 internal variables that you would not expect a user to change and for
8066 variables that you do expect a user to change.  Although you can still
8067 use @code{defvar} for user customizable variables, please use
8068 @code{defcustom} instead, since that special form provides a path into
8069 the Customization commands.  (@xref{defcustom, , Specifying Variables
8070 using @code{defcustom}}.)
8072 When you specified a variable using the @code{defvar} special form,
8073 you could distinguish a readily settable variable from others by
8074 typing an asterisk, @samp{*}, in the first column of its documentation
8075 string.  For example:
8077 @smallexample
8078 @group
8079 (defvar shell-command-default-error-buffer nil
8080   "*Buffer name for `shell-command' @dots{} error output.
8081 @dots{} ")
8082 @end group
8083 @end smallexample
8085 @findex set-variable
8086 @noindent
8087 You could (and still can) use the @code{set-variable} command to
8088 change the value of @code{shell-command-default-error-buffer}
8089 temporarily.  However, options set using @code{set-variable} are set
8090 only for the duration of your editing session.  The new values are not
8091 saved between sessions.  Each time Emacs starts, it reads the original
8092 value, unless you change the value within your @file{.emacs} file,
8093 either by setting it manually or by using @code{customize}.
8094 @xref{Emacs Initialization, , Your @file{.emacs} File}.
8096 For me, the major use of the @code{set-variable} command is to suggest
8097 variables that I might want to set in my @file{.emacs} file.  There
8098 are now more than 700 such variables --- far too many to remember
8099 readily.  Fortunately, you can press @key{TAB} after calling the
8100 @code{M-x set-variable} command to see the list of variables.
8101 (@xref{Examining, , Examining and Setting Variables, emacs,
8102 The GNU Emacs Manual}.)
8104 @node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text
8105 @comment  node-name,  next,  previous,  up
8106 @section @code{copy-region-as-kill}
8107 @findex copy-region-as-kill
8108 @findex nthcdr
8110 The @code{copy-region-as-kill} function copies a region of text from a
8111 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
8112 in the @code{kill-ring}.
8114 If you call @code{copy-region-as-kill} immediately after a
8115 @code{kill-region} command, Emacs appends the newly copied text to the
8116 previously copied text.  This means that if you yank back the text, you
8117 get it all, from both this and the previous operation.  On the other
8118 hand, if some other command precedes the @code{copy-region-as-kill},
8119 the function copies the text into a separate entry in the kill ring.
8121 @menu
8122 * Complete copy-region-as-kill::  The complete function definition.
8123 * copy-region-as-kill body::    The body of @code{copy-region-as-kill}.
8124 @end menu
8126 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
8127 @ifnottex
8128 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
8129 @end ifnottex
8131 @need 1200
8132 Here is the complete text of the version 21 @code{copy-region-as-kill}
8133 function:
8135 @c !!! for no text properties, use buffer-substring-no-properties
8137 @smallexample
8138 @group
8139 (defun copy-region-as-kill (beg end)
8140   "Save the region as if killed, but don't kill it.
8141 In Transient Mark mode, deactivate the mark.
8142 If `interprogram-cut-function' is non-nil, also save
8143 the text for a window system cut and paste."
8144   (interactive "r")
8145 @end group
8146 @group
8147   (if (eq last-command 'kill-region)
8148       (kill-append (buffer-substring beg end) (< end beg))
8149     (kill-new (buffer-substring beg end)))
8150 @end group
8151 @group
8152   (if transient-mark-mode
8153       (setq deactivate-mark t))
8154   nil)
8155 @end group
8156 @end smallexample
8158 @need 800
8159 As usual, this function can be divided into its component parts:
8161 @smallexample
8162 @group
8163 (defun copy-region-as-kill (@var{argument-list})
8164   "@var{documentation}@dots{}"
8165   (interactive "r")
8166   @var{body}@dots{})
8167 @end group
8168 @end smallexample
8170 The arguments are @code{beg} and @code{end} and the function is
8171 interactive with @code{"r"}, so the two arguments must refer to the
8172 beginning and end of the region.  If you have been reading though this
8173 document from the beginning, understanding these parts of a function is
8174 almost becoming routine.
8176 The documentation is somewhat confusing unless you remember that the
8177 word `kill' has a meaning different from its usual meaning.  The
8178 `Transient Mark' and @code{interprogram-cut-function} comments explain
8179 certain side-effects.
8181 After you once set a mark, a buffer always contains a region.  If you
8182 wish, you can use Transient Mark mode to highlight the region
8183 temporarily.  (No one wants to highlight the region all the time, so
8184 Transient Mark mode highlights it only at appropriate times.  Many
8185 people turn off Transient Mark mode, so the region is never
8186 highlighted.)
8188 Also, a windowing system allows you to copy, cut, and paste among
8189 different programs.  In the X windowing system, for example, the
8190 @code{interprogram-cut-function} function is @code{x-select-text},
8191 which works with the windowing system's equivalent of the Emacs kill
8192 ring.
8194 The body of the @code{copy-region-as-kill} function starts with an
8195 @code{if} clause.  What this clause does is distinguish between two
8196 different situations: whether or not this command is executed
8197 immediately after a previous @code{kill-region} command.  In the first
8198 case, the new region is appended to the previously copied text.
8199 Otherwise, it is inserted into the beginning of the kill ring as a
8200 separate piece of text from the previous piece.
8202 The last two lines of the function prevent the region from lighting up
8203 if Transient Mark mode is turned on.
8205 The body of @code{copy-region-as-kill} merits discussion in detail.
8207 @node copy-region-as-kill body,  , Complete copy-region-as-kill, copy-region-as-kill
8208 @comment  node-name,  next,  previous,  up
8209 @subsection The Body of @code{copy-region-as-kill}
8211 The @code{copy-region-as-kill} function works in much the same way as
8212 the @code{kill-region} function (@pxref{kill-region,
8213 ,@code{kill-region}}).  Both are written so that two or more kills in
8214 a row combine their text into a single entry.  If you yank back the
8215 text from the kill ring, you get it all in one piece.  Moreover, kills
8216 that kill forward from the current position of the cursor are added to
8217 the end of the previously copied text and commands that copy text
8218 backwards add it to the beginning of the previously copied text.  This
8219 way, the words in the text stay in the proper order.
8221 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
8222 use of the @code{last-command} variable that keeps track of the
8223 previous Emacs command.
8225 @menu
8226 * last-command & this-command::
8227 * kill-append function::
8228 * kill-new function::
8229 @end menu
8231 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
8232 @ifnottex
8233 @unnumberedsubsubsec @code{last-command} and @code{this-command}
8234 @end ifnottex
8236 Normally, whenever a function is executed, Emacs sets the value of
8237 @code{this-command} to the function being executed (which in this case
8238 would be @code{copy-region-as-kill}).  At the same time, Emacs sets
8239 the value of @code{last-command} to the previous value of
8240 @code{this-command}.
8242 In the first part of the body of the @code{copy-region-as-kill}
8243 function, an @code{if} expression determines whether the value of
8244 @code{last-command} is @code{kill-region}.  If so, the then-part of
8245 the @code{if} expression is evaluated; it uses the @code{kill-append}
8246 function to concatenate the text copied at this call to the function
8247 with the text already in the first element (the @sc{car}) of the kill
8248 ring.  On the other hand, if the value of @code{last-command} is not
8249 @code{kill-region}, then the @code{copy-region-as-kill} function
8250 attaches a new element to the kill ring using the @code{kill-new}
8251 function.
8253 @need 1250
8254 The @code{if} expression reads as follows; it uses @code{eq}, which is
8255 a function we have not yet seen:
8257 @smallexample
8258 @group
8259   (if (eq last-command 'kill-region)
8260       ;; @r{then-part}
8261       (kill-append (buffer-substring beg end) (< end beg))
8262     ;; @r{else-part}
8263     (kill-new (buffer-substring beg end)))
8264 @end group
8265 @end smallexample
8267 @findex eq @r{(example of use)}
8268 @noindent
8269 The @code{eq} function tests whether its first argument is the same Lisp
8270 object as its second argument.  The @code{eq} function is similar to the
8271 @code{equal} function in that it is used to test for equality, but
8272 differs in that it determines whether two representations are actually
8273 the same object inside the computer, but with different names.
8274 @code{equal} determines whether the structure and contents of two
8275 expressions are the same.
8277 If the previous command was @code{kill-region}, then the Emacs Lisp
8278 interpreter calls the @code{kill-append} function
8280 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
8281 @unnumberedsubsubsec The @code{kill-append} function
8282 @findex kill-append
8284 @need 800
8285 The @code{kill-append} function looks like this:
8287 @smallexample
8288 @group
8289 (defun kill-append (string before-p)
8290   "Append STRING to the end of the latest kill in the kill ring.
8291 If BEFORE-P is non-nil, prepend STRING to the kill.
8292 If `interprogram-cut-function' is set, pass the resulting kill to
8293 it."
8294   (kill-new (if before-p
8295                 (concat string (car kill-ring))
8296               (concat (car kill-ring) string))
8297             t))
8298 @end group
8299 @end smallexample
8301 @noindent
8302 The @code{kill-append} function is fairly straightforward.  It uses
8303 the @code{kill-new} function, which we will discuss in more detail in
8304 a moment.
8306 First, let us look at the conditional that is one of the two arguments
8307 to @code{kill-new}.  It uses @code{concat} to concatenate the new text
8308 to the @sc{car} of the kill ring.  Whether it prepends or appends the
8309 text depends on the results of an @code{if} expression:
8311 @smallexample
8312 @group
8313 (if before-p                            ; @r{if-part}
8314     (concat string (car kill-ring))     ; @r{then-part}
8315   (concat (car kill-ring) string))      ; @r{else-part}
8316 @end group
8317 @end smallexample
8319 @noindent
8320 If the region being killed is before the region that was killed in the
8321 last command, then it should be prepended before the material that was
8322 saved in the previous kill; and conversely, if the killed text follows
8323 what was just killed, it should be appended after the previous text.
8324 The @code{if} expression depends on the predicate @code{before-p} to
8325 decide whether the newly saved text should be put before or after the
8326 previously saved text.
8328 The symbol @code{before-p} is the name of one of the arguments to
8329 @code{kill-append}.  When the @code{kill-append} function is
8330 evaluated, it is bound to the value returned by evaluating the actual
8331 argument.  In this case, this is the expression @code{(< end beg)}.
8332 This expression does not directly determine whether the killed text in
8333 this command is located before or after the kill text of the last
8334 command; what it does is determine whether the value of the variable
8335 @code{end} is less than the value of the variable @code{beg}.  If it
8336 is, it means that the user is most likely heading towards the
8337 beginning of the buffer.  Also, the result of evaluating the predicate
8338 expression, @code{(< end beg)}, will be true and the text will be
8339 prepended before the previous text.  On the other hand, if the value of
8340 the variable @code{end} is greater than the value of the variable
8341 @code{beg}, the text will be appended after the previous text.
8343 @need 800
8344 When the newly saved text will be prepended, then the string with the new
8345 text will be concatenated before the old text:
8347 @smallexample
8348 (concat string (car kill-ring))
8349 @end smallexample
8351 @need 1200
8352 @noindent
8353 But if the text will be appended, it will be concatenated
8354 after the old text:
8356 @smallexample
8357 (concat (car kill-ring) string))
8358 @end smallexample
8360 To understand how this works, we first need to review the
8361 @code{concat} function.  The @code{concat} function links together or
8362 unites two strings of text.  The result is a string.  For example:
8364 @smallexample
8365 @group
8366 (concat "abc" "def")
8367      @result{} "abcdef"
8368 @end group
8370 @group
8371 (concat "new "
8372         (car '("first element" "second element")))
8373      @result{} "new first element"
8375 (concat (car
8376         '("first element" "second element")) " modified")
8377      @result{} "first element modified"
8378 @end group
8379 @end smallexample
8381 We can now make sense of @code{kill-append}: it modifies the contents
8382 of the kill ring.  The kill ring is a list, each element of which is
8383 saved text.  The @code{kill-append} function uses the @code{kill-new}
8384 function which in turn uses the @code{setcar} function.
8386 @node kill-new function,  , kill-append function, copy-region-as-kill body
8387 @unnumberedsubsubsec The @code{kill-new} function
8388 @findex kill-new
8390 @need 1200
8391 The @code{kill-new} function looks like this:
8393 @smallexample
8394 @group
8395 (defun kill-new (string &optional replace)
8396   "Make STRING the latest kill in the kill ring.
8397 Set the kill-ring-yank pointer to point to it.
8398 If `interprogram-cut-function' is non-nil, apply it to STRING.
8399 Optional second argument REPLACE non-nil means that STRING will replace
8400 the front of the kill ring, rather than being added to the list."
8401 @end group
8402 @group
8403   (and (fboundp 'menu-bar-update-yank-menu)
8404        (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8405 @end group
8406 @group
8407   (if (and replace kill-ring)
8408       (setcar kill-ring string)
8409     (setq kill-ring (cons string kill-ring))
8410     (if (> (length kill-ring) kill-ring-max)
8411         (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8412 @end group
8413 @group
8414   (setq kill-ring-yank-pointer kill-ring)
8415   (if interprogram-cut-function
8416       (funcall interprogram-cut-function string (not replace))))
8417 @end group
8418 @end smallexample
8420 As usual, we can look at this function in parts.
8422 @need 1200
8423 The first line of the documentation makes sense:
8425 @smallexample
8426 Make STRING the latest kill in the kill ring.
8427 @end smallexample
8429 @noindent
8430 Let's skip over the rest of the documentation for the moment.
8432 Also, let's skip over the first two lines of code, those involving
8433 @code{menu-bar-update-yank-menu}.  We will explain them below.
8435 @need 1200
8436 The critical lines are these:
8438 @smallexample
8439 @group
8440   (if (and replace kill-ring)
8441       ;; @r{then}
8442       (setcar kill-ring string)
8443 @end group
8444 @group
8445     ;; @r{else}
8446     (setq kill-ring (cons string kill-ring))
8447     (if (> (length kill-ring) kill-ring-max)
8448         ;; @r{avoid overly long kill ring}
8449         (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8450 @end group
8451 @group
8452   (setq kill-ring-yank-pointer kill-ring)
8453   (if interprogram-cut-function
8454       (funcall interprogram-cut-function string (not replace))))
8455 @end group
8456 @end smallexample
8458 The conditional test is @w{@code{(and replace kill-ring)}}.
8459 This will be true when two conditions are met:  the kill ring has
8460 something in it, and the @code{replace} variable is true.
8462 @need 1250
8463 The @code{kill-append} function sets @code{replace} to be true; then,
8464 when the kill ring has at least one item in it, the @code{setcar}
8465 expression is executed:
8467 @smallexample
8468 (setcar kill-ring string)
8469 @end smallexample
8471 The @code{setcar} function actually changes the first element of the
8472 @code{kill-ring} list to the value of @code{string}.  It replaces the
8473 first element.
8475 On the other hand, if the kill ring is empty, or replace is false, the
8476 else-part of the condition is executed:
8478 @smallexample
8479 @group
8480 (setq kill-ring (cons string kill-ring))
8481 (if (> (length kill-ring) kill-ring-max)
8482     (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8483 @end group
8484 @end smallexample
8486 @noindent
8487 This expression first constructs a new version of the kill ring by
8488 prepending @code{string} to the existing kill ring as a new element.
8489 Then it executes a second @code{if} clause.  This second @code{if}
8490 clause keeps the kill ring from growing too long.
8492 Let's look at these two expressions in order.
8494 The @code{setq} line of the else-part sets the new value of the kill
8495 ring to what results from adding the string being killed to the old kill
8496 ring.
8498 @need 800
8499 We can see how this works with an example:
8501 @smallexample
8502 (setq example-list '("here is a clause" "another clause"))
8503 @end smallexample
8505 @need 1200
8506 @noindent
8507 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
8508 @code{example-list} and see what it returns:
8510 @smallexample
8511 @group
8512 example-list
8513      @result{} ("here is a clause" "another clause")
8514 @end group
8515 @end smallexample
8517 @need 1200
8518 @noindent
8519 Now, we can add a new element on to this list by evaluating the
8520 following expression:
8521 @findex cons, @r{example}
8523 @smallexample
8524 (setq example-list (cons "a third clause" example-list))
8525 @end smallexample
8527 @need 800
8528 @noindent
8529 When we evaluate @code{example-list}, we find its value is:
8531 @smallexample
8532 @group
8533 example-list
8534      @result{} ("a third clause" "here is a clause" "another clause")
8535 @end group
8536 @end smallexample
8538 @noindent
8539 Thus, the third clause was added to the list by @code{cons}.
8541 @need 1200
8542 This is exactly similar to what the @code{setq} and @code{cons} do in
8543 the function.  Here is the line again:
8545 @smallexample
8546 (setq kill-ring (cons string kill-ring))
8547 @end smallexample
8549 @need 1200
8550 Now for the second part of the @code{if} clause.  This expression
8551 keeps the kill ring from growing too long.  It looks like this:
8553 @smallexample
8554 @group
8555 (if (> (length kill-ring) kill-ring-max)
8556     (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8557 @end group
8558 @end smallexample
8560 The code checks whether the length of the kill ring is greater than
8561 the maximum permitted length.  This is the value of
8562 @code{kill-ring-max} (which is 60, by default).  If the length of the
8563 kill ring is too long, then this code sets the last element of the
8564 kill ring to @code{nil}.  It does this by using two functions,
8565 @code{nthcdr} and @code{setcdr}.
8567 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
8568 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
8569 @sc{car} of a list.  In this case, however, @code{setcdr} will not be
8570 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
8571 function is used to cause it to set the @sc{cdr} of the next to last
8572 element of the kill ring---this means that since the @sc{cdr} of the
8573 next to last element is the last element of the kill ring, it will set
8574 the last element of the kill ring.
8576 @findex nthcdr, @r{example}
8577 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
8578 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
8579 @dots{}  It does this @var{N} times and returns the results.
8581 @findex setcdr, @r{example}
8582 Thus, if we had a four element list that was supposed to be three
8583 elements long, we could set the @sc{cdr} of the next to last element
8584 to @code{nil}, and thereby shorten the list.  (If you sent the last
8585 element to some other value than @code{nil}, which you could do, then
8586 you would not have shortened the list.)
8588 You can see shortening by evaluating the following three expressions
8589 in turn.  First set the value of @code{trees} to @code{(maple oak pine
8590 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
8591 and then find the value of @code{trees}:
8593 @smallexample
8594 @group
8595 (setq trees '(maple oak pine birch))
8596      @result{} (maple oak pine birch)
8597 @end group
8599 @group
8600 (setcdr (nthcdr 2 trees) nil)
8601      @result{} nil
8603 trees
8604      @result{} (maple oak pine)
8605 @end group
8606 @end smallexample
8608 @noindent
8609 (The value returned by the @code{setcdr} expression is @code{nil} since
8610 that is what the @sc{cdr} is set to.)
8612 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
8613 @sc{cdr} a number of times that is one less than the maximum permitted
8614 size of the kill ring and sets the @sc{cdr} of that element (which
8615 will be the rest of the elements in the kill ring) to @code{nil}.
8616 This prevents the kill ring from growing too long.
8618 @need 800
8619 The next to last expression in the @code{kill-new} function is
8621 @smallexample
8622 (setq kill-ring-yank-pointer kill-ring)
8623 @end smallexample
8625 The @code{kill-ring-yank-pointer} is a global variable that is set to be
8626 the @code{kill-ring}.
8628 Even though the @code{kill-ring-yank-pointer} is called a
8629 @samp{pointer}, it is a variable just like the kill ring.  However, the
8630 name has been chosen to help humans understand how the variable is used.
8631 The variable is used in functions such as @code{yank} and
8632 @code{yank-pop} (@pxref{Yanking, , Yanking Text Back}).
8634 @need 1200
8635 Now, to return to the first two lines in the body of the function:
8637 @smallexample
8638 @group
8639   (and (fboundp 'menu-bar-update-yank-menu)
8640        (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8641 @end group
8642 @end smallexample
8644 @noindent
8645 This is an expression whose first element is the function @code{and}.
8647 @findex and, @r{introduced}
8648 The @code{and} special form evaluates each of its arguments until one of
8649 the arguments returns a value of @code{nil}, in which case the
8650 @code{and} expression returns @code{nil}; however, if none of the
8651 arguments returns a value of @code{nil}, the value resulting from
8652 evaluating the last argument is returned.  (Since such a value is not
8653 @code{nil}, it is considered true in Emacs Lisp.)  In other words, an
8654 @code{and} expression returns a true value only if all its arguments
8655 are true.
8656 @findex and
8658 In this case, the expression tests first to see whether
8659 @code{menu-bar-update-yank-menu} exists as a function, and if so,
8660 calls it.  The @code{fboundp} function returns true if the symbol it
8661 is testing has a function definition that `is not void'.  If the
8662 symbol's function definition were void, we would receive an error
8663 message, as we did when we created errors intentionally (@pxref{Making
8664 Errors, , Generate an Error Message}).
8666 @need 1200
8667 Essentially, the @code{and} is an @code{if} expression that reads like
8668 this:
8670 @smallexample
8671 @group
8672 if @var{the-menu-bar-function-exists}
8673   then @var{execute-it}
8674 @end group
8675 @end smallexample
8677 @code{menu-bar-update-yank-menu} is one of the functions that make it
8678 possible to use the `Select and Paste' menu in the Edit item of a menu
8679 bar; using a mouse, you can look at the various pieces of text you
8680 have saved and select one piece to paste.
8682 Finally, the last expression in the @code{kill-new} function adds the
8683 newly copied string to whatever facility exists for copying and
8684 pasting among different programs running in a windowing system.  In
8685 the X Windowing system, for example, the @code{x-select-text} function
8686 takes the string and stores it in memory operated by X.  You can paste
8687 the string in another program, such as an Xterm.
8689 @need 1200
8690 The expression looks like this:
8692 @smallexample
8693 @group
8694   (if interprogram-cut-function
8695       (funcall interprogram-cut-function string (not replace))))
8696 @end group
8697 @end smallexample
8699 If an @code{interprogram-cut-function} exists, then Emacs executes
8700 @code{funcall}, which in turn calls its first argument as a function
8701 and passes the remaining arguments to it.  (Incidentally, as far as I
8702 can see, this @code{if} expression could be replaced by an @code{and}
8703 expression similar to the one in the first part of the function.)
8705 We are not going to discuss windowing systems and other programs
8706 further, but merely note that this is a mechanism that enables GNU
8707 Emacs to work easily and well with other programs.
8709 This code for placing text in the kill ring, either concatenated with
8710 an existing element or as a new element, leads us to the code for
8711 bringing back text that has been cut out of the buffer---the yank
8712 commands.  However, before discussing the yank commands, it is better
8713 to learn how lists are implemented in a computer.  This will make
8714 clear such mysteries as the use of the term `pointer'.
8716 @need 1250
8717 @node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text
8718 @comment  node-name,  next,  previous,  up
8719 @section Review
8721 Here is a brief summary of some recently introduced functions.
8723 @table @code
8724 @item car
8725 @itemx cdr
8726 @code{car} returns the first element of a list; @code{cdr} returns the
8727 second and subsequent elements of a list.
8729 @need 1250
8730 For example:
8732 @smallexample
8733 @group
8734 (car '(1 2 3 4 5 6 7))
8735      @result{} 1
8736 (cdr '(1 2 3 4 5 6 7))
8737      @result{} (2 3 4 5 6 7)
8738 @end group
8739 @end smallexample
8741 @item cons
8742 @code{cons} constructs a list by prepending its first argument to its
8743 second argument.
8745 @need 1250
8746 For example:
8748 @smallexample
8749 @group
8750 (cons 1 '(2 3 4))
8751      @result{} (1 2 3 4)
8752 @end group
8753 @end smallexample
8755 @item nthcdr
8756 Return the result of taking @sc{cdr} `n' times on a list.
8757 @iftex
8759 @tex
8760 $n^{th}$
8761 @end tex
8762 @code{cdr}.
8763 @end iftex
8764 The `rest of the rest', as it were.
8766 @need 1250
8767 For example:
8769 @smallexample
8770 @group
8771 (nthcdr 3 '(1 2 3 4 5 6 7))
8772      @result{} (4 5 6 7)
8773 @end group
8774 @end smallexample
8776 @item setcar
8777 @itemx setcdr
8778 @code{setcar} changes the first element of a list; @code{setcdr}
8779 changes the second and subsequent elements of a list.
8781 @need 1250
8782 For example:
8784 @smallexample
8785 @group
8786 (setq triple '(1 2 3))
8788 (setcar triple '37)
8790 triple
8791      @result{} (37 2 3)
8793 (setcdr triple '("foo" "bar"))
8795 triple
8796      @result{} (37 "foo" "bar")
8797 @end group
8798 @end smallexample
8800 @item progn
8801 Evaluate each argument in sequence and then return the value of the
8802 last.
8804 @need 1250
8805 For example:
8807 @smallexample
8808 @group
8809 (progn 1 2 3 4)
8810      @result{} 4
8811 @end group
8812 @end smallexample
8814 @item save-restriction
8815 Record whatever narrowing is in effect in the current buffer, if any,
8816 and restore that narrowing after evaluating the arguments.
8818 @item search-forward
8819 Search for a string, and if the string is found, move point.
8821 @need 1250
8822 @noindent
8823 Takes four arguments:
8825 @enumerate
8826 @item
8827 The string to search for.
8829 @item
8830 Optionally, the limit of the search.
8832 @item
8833 Optionally, what to do if the search fails, return @code{nil} or an
8834 error message.
8836 @item
8837 Optionally, how many times to repeat the search; if negative, the
8838 search goes backwards.
8839 @end enumerate
8841 @item kill-region
8842 @itemx delete-and-extract-region
8843 @itemx copy-region-as-kill
8845 @code{kill-region} cuts the text between point and mark from the
8846 buffer and stores that text in the kill ring, so you can get it back
8847 by yanking.
8849 @code{delete-and-extract-region} removes the text between point and
8850 mark from the buffer and throws it away.  You cannot get it back.
8852 @code{copy-region-as-kill} copies the text between point and mark into
8853 the kill ring, from which you can get it by yanking.  The function
8854 does not cut or remove the text from the buffer.
8855 @end table
8857 @need 1500
8858 @node search Exercises,  , cons & search-fwd Review, Cutting & Storing Text
8859 @section Searching Exercises
8861 @itemize @bullet
8862 @item
8863 Write an interactive function that searches for a string.  If the
8864 search finds the string, leave point after it and display a message
8865 that says ``Found!''.  (Do not use @code{search-forward} for the name
8866 of this function; if you do, you will overwrite the existing version of
8867 @code{search-forward} that comes with Emacs.  Use a name such as
8868 @code{test-search} instead.)
8870 @item
8871 Write a function that prints the third element of the kill ring in the
8872 echo area, if any; if the kill ring does not contain a third element,
8873 print an appropriate message.
8874 @end itemize
8876 @node List Implementation, Yanking, Cutting & Storing Text, Top
8877 @comment  node-name,  next,  previous,  up
8878 @chapter How Lists are Implemented
8879 @cindex Lists in a computer
8881 In Lisp, atoms are recorded in a straightforward fashion; if the
8882 implementation is not straightforward in practice, it is, nonetheless,
8883 straightforward in theory.  The atom @samp{rose}, for example, is
8884 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
8885 @samp{e}.  A list, on the other hand, is kept differently.  The mechanism
8886 is equally simple, but it takes a moment to get used to the idea.  A
8887 list is kept using a series of pairs of pointers.  In the series, the
8888 first pointer in each pair points to an atom or to another list, and the
8889 second pointer in each pair points to the next pair, or to the symbol
8890 @code{nil}, which marks the end of the list.
8892 A pointer itself is quite simply the electronic address of what is
8893 pointed to.  Hence, a list is kept as a series of electronic addresses.
8895 @menu
8896 * Lists diagrammed::
8897 * Symbols as Chest::            Exploring a powerful metaphor.
8898 * List Exercise::
8899 @end menu
8901 @node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
8902 @ifnottex
8903 @unnumberedsec Lists diagrammed
8904 @end ifnottex
8906 For example, the list @code{(rose violet buttercup)} has three elements,
8907 @samp{rose}, @samp{violet}, and @samp{buttercup}.  In the computer, the
8908 electronic address of @samp{rose} is recorded in a segment of computer
8909 memory along with the address that gives the electronic address of where
8910 the atom @samp{violet} is located; and that address (the one that tells
8911 where @samp{violet} is located) is kept along with an address that tells
8912 where the address for the atom @samp{buttercup} is located.
8914 @need 1200
8915 This sounds more complicated than it is and is easier seen in a diagram:
8917 @c clear print-postscript-figures
8918 @c !!! cons-cell-diagram #1
8919 @ifnottex
8920 @smallexample
8921 @group
8922     ___ ___      ___ ___      ___ ___
8923    |___|___|--> |___|___|--> |___|___|--> nil
8924      |            |            |
8925      |            |            |
8926       --> rose     --> violet   --> buttercup
8927 @end group
8928 @end smallexample
8929 @end ifnottex
8930 @ifset print-postscript-figures
8931 @sp 1
8932 @tex
8933 @image{cons-1}
8934 %%%% old method of including an image
8935 % \input /usr/local/lib/tex/inputs/psfig.tex
8936 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
8937 % \catcode`\@=0 %
8938 @end tex
8939 @sp 1
8940 @end ifset
8941 @ifclear print-postscript-figures
8942 @iftex
8943 @smallexample
8944 @group
8945     ___ ___      ___ ___      ___ ___
8946    |___|___|--> |___|___|--> |___|___|--> nil
8947      |            |            |
8948      |            |            |
8949       --> rose     --> violet   --> buttercup
8950 @end group
8951 @end smallexample
8952 @end iftex
8953 @end ifclear
8955 @noindent
8956 In the diagram, each box represents a word of computer memory that
8957 holds a Lisp object, usually in the form of a memory address.  The boxes,
8958 i.e.@: the addresses, are in pairs.  Each arrow points to what the address
8959 is the address of, either an atom or another pair of addresses.  The
8960 first box is the electronic address of @samp{rose} and the arrow points
8961 to @samp{rose}; the second box is the address of the next pair of boxes,
8962 the first part of which is the address of @samp{violet} and the second
8963 part of which is the address of the next pair.  The very last box
8964 points to the symbol @code{nil}, which marks the end of the list.
8966 @need 1200
8967 When a variable is set to a list with a function such as @code{setq},
8968 it stores the address of the first box in the variable.  Thus,
8969 evaluation of the expression
8971 @smallexample
8972 (setq bouquet '(rose violet buttercup))
8973 @end smallexample
8975 @need 1250
8976 @noindent
8977 creates a situation like this:
8979 @c cons-cell-diagram #2
8980 @ifnottex
8981 @smallexample
8982 @group
8983 bouquet
8984      |
8985      |     ___ ___      ___ ___      ___ ___
8986       --> |___|___|--> |___|___|--> |___|___|--> nil
8987             |            |            |
8988             |            |            |
8989              --> rose     --> violet   --> buttercup
8990 @end group
8991 @end smallexample
8992 @end ifnottex
8993 @ifset print-postscript-figures
8994 @sp 1
8995 @tex
8996 @image{cons-2}
8997 %%%% old method of including an image
8998 % \input /usr/local/lib/tex/inputs/psfig.tex
8999 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
9000 % \catcode`\@=0 %
9001 @end tex
9002 @sp 1
9003 @end ifset
9004 @ifclear print-postscript-figures
9005 @iftex
9006 @smallexample
9007 @group
9008 bouquet
9009      |
9010      |     ___ ___      ___ ___      ___ ___
9011       --> |___|___|--> |___|___|--> |___|___|--> nil
9012             |            |            |
9013             |            |            |
9014              --> rose     --> violet   --> buttercup
9015 @end group
9016 @end smallexample
9017 @end iftex
9018 @end ifclear
9020 @noindent
9021 In this example, the symbol @code{bouquet} holds the address of the first
9022 pair of boxes.
9024 @need 1200
9025 This same list can be illustrated in a different sort of box notation
9026 like this:
9028 @c cons-cell-diagram #2a
9029 @ifnottex
9030 @smallexample
9031 @group
9032 bouquet
9034  |    --------------       ---------------       ----------------
9035  |   | car   | cdr  |     | car    | cdr  |     | car     | cdr  |
9036   -->| rose  |   o------->| violet |   o------->| butter- |  nil |
9037      |       |      |     |        |      |     | cup     |      |
9038       --------------       ---------------       ----------------
9039 @end group
9040 @end smallexample
9041 @end ifnottex
9042 @ifset print-postscript-figures
9043 @sp 1
9044 @tex
9045 @image{cons-2a}
9046 %%%% old method of including an image
9047 % \input /usr/local/lib/tex/inputs/psfig.tex
9048 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
9049 % \catcode`\@=0 %
9050 @end tex
9051 @sp 1
9052 @end ifset
9053 @ifclear print-postscript-figures
9054 @iftex
9055 @smallexample
9056 @group
9057 bouquet
9059  |    --------------       ---------------       ----------------
9060  |   | car   | cdr  |     | car    | cdr  |     | car     | cdr  |
9061   -->| rose  |   o------->| violet |   o------->| butter- |  nil |
9062      |       |      |     |        |      |     | cup     |      |
9063       --------------       ---------------       ----------------
9064 @end group
9065 @end smallexample
9066 @end iftex
9067 @end ifclear
9069 (Symbols consist of more than pairs of addresses, but the structure of
9070 a symbol is made up of addresses.  Indeed, the symbol @code{bouquet}
9071 consists of a group of address-boxes, one of which is the address of
9072 the printed word @samp{bouquet}, a second of which is the address of a
9073 function definition attached to the symbol, if any, a third of which
9074 is the address of the first pair of address-boxes for the list
9075 @code{(rose violet buttercup)}, and so on.  Here we are showing that
9076 the symbol's third address-box points to the first pair of
9077 address-boxes for the list.)
9079 If a symbol is set to the @sc{cdr} of a list, the list itself is not
9080 changed; the symbol simply has an address further down the list.  (In
9081 the jargon, @sc{car} and @sc{cdr} are `non-destructive'.)  Thus,
9082 evaluation of the following expression
9084 @smallexample
9085 (setq flowers (cdr bouquet))
9086 @end smallexample
9088 @need 800
9089 @noindent
9090 produces this:
9092 @c cons-cell-diagram #3
9093 @ifnottex
9094 @sp 1
9095 @smallexample
9096 @group
9097 bouquet        flowers
9098   |              |
9099   |     ___ ___  |     ___ ___      ___ ___
9100    --> |   |   |  --> |   |   |    |   |   |
9101        |___|___|----> |___|___|--> |___|___|--> nil
9102          |              |            |
9103          |              |            |
9104           --> rose       --> violet   --> buttercup
9105 @end group
9106 @end smallexample
9107 @sp 1
9108 @end ifnottex
9109 @ifset print-postscript-figures
9110 @sp 1
9111 @tex
9112 @image{cons-3}
9113 %%%% old method of including an image
9114 % \input /usr/local/lib/tex/inputs/psfig.tex
9115 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
9116 % \catcode`\@=0 %
9117 @end tex
9118 @sp 1
9119 @end ifset
9120 @ifclear print-postscript-figures
9121 @iftex
9122 @sp 1
9123 @smallexample
9124 @group
9125 bouquet        flowers
9126   |              |
9127   |     ___ ___  |     ___ ___      ___ ___
9128    --> |   |   |  --> |   |   |    |   |   |
9129        |___|___|----> |___|___|--> |___|___|--> nil
9130          |              |            |
9131          |              |            |
9132           --> rose       --> violet   --> buttercup
9133 @end group
9134 @end smallexample
9135 @sp 1
9136 @end iftex
9137 @end ifclear
9139 @noindent
9140 The value of @code{flowers} is @code{(violet buttercup)}, which is
9141 to say, the symbol @code{flowers} holds the address of the pair of
9142 address-boxes, the first of which holds the address of @code{violet},
9143 and the second of which holds the address of @code{buttercup}.
9145 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
9146 pair}.  @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
9147 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
9148 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
9149 information about cons cells and dotted pairs.
9151 @need 1200
9152 The function @code{cons} adds a new pair of addresses to the front of
9153 a series of addresses like that shown above.  For example, evaluating
9154 the expression
9156 @smallexample
9157 (setq bouquet (cons 'lily bouquet))
9158 @end smallexample
9160 @need 1500
9161 @noindent
9162 produces:
9164 @c cons-cell-diagram #4
9165 @ifnottex
9166 @sp 1
9167 @smallexample
9168 @group
9169 bouquet                       flowers
9170   |                             |
9171   |     ___ ___        ___ ___  |     ___ ___       ___ ___
9172    --> |   |   |      |   |   |  --> |   |   |     |   |   |
9173        |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9174          |              |              |             |
9175          |              |              |             |
9176           --> lily      --> rose       --> violet    --> buttercup
9177 @end group
9178 @end smallexample
9179 @sp 1
9180 @end ifnottex
9181 @ifset print-postscript-figures
9182 @sp 1
9183 @tex
9184 @image{cons-4}
9185 %%%% old method of including an image
9186 % \input /usr/local/lib/tex/inputs/psfig.tex
9187 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
9188 % \catcode`\@=0 %
9189 @end tex
9190 @sp 1
9191 @end ifset
9192 @ifclear print-postscript-figures
9193 @iftex
9194 @sp 1
9195 @smallexample
9196 @group
9197 bouquet                       flowers
9198   |                             |
9199   |     ___ ___        ___ ___  |     ___ ___       ___ ___
9200    --> |   |   |      |   |   |  --> |   |   |     |   |   |
9201        |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9202          |              |              |             |
9203          |              |              |             |
9204           --> lily      --> rose       --> violet    --> buttercup
9205 @end group
9206 @end smallexample
9207 @sp 1
9208 @end iftex
9209 @end ifclear
9211 @need 1200
9212 @noindent
9213 However, this does not change the value of the symbol
9214 @code{flowers}, as you can see by evaluating the following,
9216 @smallexample
9217 (eq (cdr (cdr bouquet)) flowers)
9218 @end smallexample
9220 @noindent
9221 which returns @code{t} for true.
9223 Until it is reset, @code{flowers} still has the value
9224 @code{(violet buttercup)}; that is, it has the address of the cons
9225 cell whose first address is of @code{violet}.  Also, this does not
9226 alter any of the pre-existing cons cells; they are all still there.
9228 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
9229 of the next cons cell in the series; to get the @sc{car} of a list,
9230 you get the address of the first element of the list; to @code{cons} a
9231 new element on a list, you add a new cons cell to the front of the list.
9232 That is all there is to it!  The underlying structure of Lisp is
9233 brilliantly simple!
9235 And what does the last address in a series of cons cells refer to?  It
9236 is the address of the empty list, of @code{nil}.
9238 In summary, when a Lisp variable is set to a value, it is provided with
9239 the address of the list to which the variable refers.
9241 @node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation
9242 @section Symbols as a Chest of Drawers
9243 @cindex Symbols as a Chest of Drawers
9244 @cindex Chest of Drawers, metaphor for a symbol
9245 @cindex Drawers, Chest of, metaphor for a symbol
9247 In an earlier section, I suggested that you might imagine a symbol as
9248 being a chest of drawers.  The function definition is put in one
9249 drawer, the value in another, and so on.  What is put in the drawer
9250 holding the value can be changed without affecting the contents of the
9251 drawer holding the function definition, and vice-versa.
9253 Actually, what is put in each drawer is the address of the value or
9254 function definition.  It is as if you found an old chest in the attic,
9255 and in one of its drawers you found a map giving you directions to
9256 where the buried treasure lies.
9258 (In addition to its name, symbol definition, and variable value, a
9259 symbol has a `drawer' for a @dfn{property list} which can be used to
9260 record other information.  Property lists are not discussed here; see
9261 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
9262 Reference Manual}.)
9264 @need 1500
9265 Here is a fanciful representation:
9267 @c chest-of-drawers diagram
9268 @ifnottex
9269 @sp 1
9270 @smallexample
9271 @group
9272             Chest of Drawers            Contents of Drawers
9274             __   o0O0o   __
9275           /                 \
9276          ---------------------
9277         |    directions to    |            [map to]
9278         |     symbol name     |             bouquet
9279         |                     |
9280         +---------------------+
9281         |    directions to    |
9282         |  symbol definition  |             [none]
9283         |                     |
9284         +---------------------+
9285         |    directions to    |            [map to]
9286         |    variable value   |             (rose violet buttercup)
9287         |                     |
9288         +---------------------+
9289         |    directions to    |
9290         |    property list    |             [not described here]
9291         |                     |
9292         +---------------------+
9293         |/                   \|
9294 @end group
9295 @end smallexample
9296 @sp 1
9297 @end ifnottex
9298 @ifset print-postscript-figures
9299 @sp 1
9300 @tex
9301 @image{drawers}
9302 %%%% old method of including an image
9303 % \input /usr/local/lib/tex/inputs/psfig.tex
9304 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
9305 % \catcode`\@=0 %
9306 @end tex
9307 @sp 1
9308 @end ifset
9309 @ifclear print-postscript-figures
9310 @iftex
9311 @sp 1
9312 @smallexample
9313 @group
9314             Chest of Drawers            Contents of Drawers
9316             __   o0O0o   __
9317           /                 \
9318          ---------------------
9319         |    directions to    |            [map to]
9320         |     symbol name     |             bouquet
9321         |                     |
9322         +---------------------+
9323         |    directions to    |
9324         |  symbol definition  |             [none]
9325         |                     |
9326         +---------------------+
9327         |    directions to    |            [map to]
9328         |    variable value   |             (rose violet buttercup)
9329         |                     |
9330         +---------------------+
9331         |    directions to    |
9332         |    property list    |             [not described here]
9333         |                     |
9334         +---------------------+
9335         |/                   \|
9336 @end group
9337 @end smallexample
9338 @sp 1
9339 @end iftex
9340 @end ifclear
9342 @node List Exercise,  , Symbols as Chest, List Implementation
9343 @section Exercise
9345 Set @code{flowers} to @code{violet} and @code{buttercup}.  Cons two
9346 more flowers on to this list and set this new list to
9347 @code{more-flowers}.  Set the @sc{car} of @code{flowers} to a fish.
9348 What does the @code{more-flowers} list now contain?
9350 @node Yanking, Loops & Recursion, List Implementation, Top
9351 @comment  node-name,  next,  previous,  up
9352 @chapter Yanking Text Back
9353 @findex yank
9354 @findex rotate-yank-pointer
9355 @cindex Text retrieval
9356 @cindex Retrieving text
9357 @cindex Pasting text
9359 Whenever you cut text out of a buffer with a `kill' command in GNU Emacs,
9360 you can bring it back with a `yank' command.  The text that is cut out of
9361 the buffer is put in the kill ring and the yank commands insert the
9362 appropriate contents of the kill ring back into a buffer (not necessarily
9363 the original buffer).
9365 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
9366 the kill ring into the current buffer.  If the @kbd{C-y} command is
9367 followed immediately by @kbd{M-y}, the first element is replaced by
9368 the second element.  Successive @kbd{M-y} commands replace the second
9369 element with the third, fourth, or fifth element, and so on.  When the
9370 last element in the kill ring is reached, it is replaced by the first
9371 element and the cycle is repeated.  (Thus the kill ring is called a
9372 `ring' rather than just a `list'.  However, the actual data structure
9373 that holds the text is a list.
9374 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
9375 list is handled as a ring.)
9377 @menu
9378 * Kill Ring Overview::          The kill ring is a list.
9379 * kill-ring-yank-pointer::      The @code{kill-ring-yank-pointer} variable.
9380 * yank nthcdr Exercises::
9381 @end menu
9383 @node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
9384 @comment  node-name,  next,  previous,  up
9385 @section Kill Ring Overview
9386 @cindex Kill ring overview
9388 The kill ring is a list of textual strings.  This is what it looks like:
9390 @smallexample
9391 ("some text" "a different piece of text" "yet more text")
9392 @end smallexample
9394 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
9395 string of characters saying @samp{some text} would be inserted in this
9396 buffer where my cursor is located.
9398 The @code{yank} command is also used for duplicating text by copying it.
9399 The copied text is not cut from the buffer, but a copy of it is put on the
9400 kill ring and is inserted by yanking it back.
9402 Three functions are used for bringing text back from the kill ring:
9403 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
9404 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
9405 which is used by the two other functions.
9407 These functions refer to the kill ring through a variable called the
9408 @code{kill-ring-yank-pointer}.  Indeed, the insertion code for both the
9409 @code{yank} and @code{yank-pop} functions is:
9411 @smallexample
9412 (insert (car kill-ring-yank-pointer))
9413 @end smallexample
9415 To begin to understand how @code{yank} and @code{yank-pop} work, it is
9416 first necessary to look at the @code{kill-ring-yank-pointer} variable
9417 and the @code{rotate-yank-pointer} function.
9419 @node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking
9420 @comment  node-name,  next,  previous,  up
9421 @section The @code{kill-ring-yank-pointer} Variable
9423 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
9424 a variable.  It points to something by being bound to the value of what
9425 it points to, like any other Lisp variable.
9427 @need 1000
9428 Thus, if the value of the kill ring is:
9430 @smallexample
9431 ("some text" "a different piece of text" "yet more text")
9432 @end smallexample
9434 @need 1250
9435 @noindent
9436 and the @code{kill-ring-yank-pointer} points to the second clause, the
9437 value of @code{kill-ring-yank-pointer} is:
9439 @smallexample
9440 ("a different piece of text" "yet more text")
9441 @end smallexample
9443 As explained in the previous chapter (@pxref{List Implementation}), the
9444 computer does not keep two different copies of the text being pointed to
9445 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}.  The
9446 words ``a different piece of text'' and ``yet more text'' are not
9447 duplicated.  Instead, the two Lisp variables point to the same pieces of
9448 text.  Here is a diagram:
9450 @c cons-cell-diagram #5
9451 @ifnottex
9452 @smallexample
9453 @group
9454 kill-ring     kill-ring-yank-pointer
9455     |               |
9456     |      ___ ___  |     ___ ___      ___ ___
9457      ---> |   |   |  --> |   |   |    |   |   |
9458           |___|___|----> |___|___|--> |___|___|--> nil
9459             |              |            |
9460             |              |            |
9461             |              |             --> "yet more text"
9462             |              |
9463             |               --> "a different piece of text
9464             |
9465              --> "some text"
9466 @end group
9467 @end smallexample
9468 @sp 1
9469 @end ifnottex
9470 @ifset print-postscript-figures
9471 @sp 1
9472 @tex
9473 @image{cons-5}
9474 %%%% old method of including an image
9475 % \input /usr/local/lib/tex/inputs/psfig.tex
9476 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
9477 % \catcode`\@=0 %
9478 @end tex
9479 @sp 1
9480 @end ifset
9481 @ifclear print-postscript-figures
9482 @iftex
9483 @smallexample
9484 @group
9485 kill-ring     kill-ring-yank-pointer
9486     |               |
9487     |      ___ ___  |     ___ ___      ___ ___
9488      ---> |   |   |  --> |   |   |    |   |   |
9489           |___|___|----> |___|___|--> |___|___|--> nil
9490             |              |            |
9491             |              |            |
9492             |              |             --> "yet more text"
9493             |              |
9494             |               --> "a different piece of text
9495             |
9496              --> "some text"
9497 @end group
9498 @end smallexample
9499 @sp 1
9500 @end iftex
9501 @end ifclear
9503 Both the variable @code{kill-ring} and the variable
9504 @code{kill-ring-yank-pointer} are pointers.  But the kill ring itself is
9505 usually described as if it were actually what it is composed of.  The
9506 @code{kill-ring} is spoken of as if it were the list rather than that it
9507 points to the list.  Conversely, the @code{kill-ring-yank-pointer} is
9508 spoken of as pointing to a list.
9510 These two ways of talking about the same thing sound confusing at first but
9511 make sense on reflection.  The kill ring is generally thought of as the
9512 complete structure of data that holds the information of what has recently
9513 been cut out of the Emacs buffers.  The @code{kill-ring-yank-pointer}
9514 on the other hand, serves to indicate---that is, to `point to'---that part
9515 of the kill ring of which the first element (the @sc{car}) will be
9516 inserted.
9518 The @code{rotate-yank-pointer} function changes the element in the
9519 kill ring to which the @code{kill-ring-yank-pointer} points; when the
9520 pointer is set to point to the next element beyond the end of the kill
9521 ring, it automatically sets it to point to the first element of the
9522 kill ring.  This is how the list is transformed into a ring.  The
9523 @code{rotate-yank-pointer} function itself is not difficult, but
9524 contains many details.  It and the much simpler @code{yank} and
9525 @code{yank-pop} functions are described in an appendix.
9526 @xref{Kill Ring, , Handling the Kill Ring}.
9528 @need 1500
9529 @node yank nthcdr Exercises,  , kill-ring-yank-pointer, Yanking
9530 @section Exercises with @code{yank} and @code{nthcdr}
9532 @itemize @bullet
9533 @item
9534 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
9535 your kill ring.  Add several items to your kill ring; look at its
9536 value again.  Using @kbd{M-y} (@code{yank-pop)}, move all the way
9537 around the kill ring.  How many items were in your kill ring?  Find
9538 the value of @code{kill-ring-max}.  Was your kill ring full, or could
9539 you have kept more blocks of text within it?
9541 @item
9542 Using @code{nthcdr} and @code{car}, construct a series of expressions
9543 to return the first, second, third, and fourth elements of a list.
9544 @end itemize
9546 @node Loops & Recursion, Regexp Search, Yanking, Top
9547 @comment  node-name,  next,  previous,  up
9548 @chapter Loops and Recursion
9549 @cindex Loops and recursion
9550 @cindex Recursion and loops
9551 @cindex Repetition (loops)
9553 Emacs Lisp has two primary ways to cause an expression, or a series of
9554 expressions, to be evaluated repeatedly: one uses a @code{while}
9555 loop, and the other uses @dfn{recursion}.
9557 Repetition can be very valuable.  For example, to move forward four
9558 sentences, you need only write a program that will move forward one
9559 sentence and then repeat the process four times.  Since a computer does
9560 not get bored or tired, such repetitive action does not have the
9561 deleterious effects that excessive or the wrong kinds of repetition can
9562 have on humans.
9564 People mostly write Emacs Lisp functions using @code{while} loops and
9565 their kin; but you can use recursion, which provides a very powerful
9566 way to think about and then to solve problems@footnote{You can write
9567 recursive functions to be frugal or wasteful of mental or computer
9568 resources; as it happens, methods that people find easy---that are
9569 frugal of `mental resources'---sometimes use considerable computer
9570 resources.  Emacs was designed to run on machines that we now consider
9571 limited and its default settings are conservative.  You may want to
9572 increase the values of @code{max-specpdl-size} and
9573 @code{max-lisp-eval-depth}.  In my @file{.emacs} file, I set them to
9574 15 and 30 times their default value.}.
9576 @menu
9577 * while::                       Causing a stretch of code to repeat.
9578 * dolist dotimes::
9579 * Recursion::                   Causing a function to call itself.
9580 * Looping exercise::
9581 @end menu
9583 @node while, dolist dotimes, Loops & Recursion, Loops & Recursion
9584 @comment  node-name,  next,  previous,  up
9585 @section @code{while}
9586 @cindex Loops
9587 @findex while
9589 The @code{while} special form tests whether the value returned by
9590 evaluating its first argument is true or false.  This is similar to what
9591 the Lisp interpreter does with an @code{if}; what the interpreter does
9592 next, however, is different.
9594 In a @code{while} expression, if the value returned by evaluating the
9595 first argument is false, the Lisp interpreter skips the rest of the
9596 expression (the @dfn{body} of the expression) and does not evaluate it.
9597 However, if the value is true, the Lisp interpreter evaluates the body
9598 of the expression and then again tests whether the first argument to
9599 @code{while} is true or false.  If the value returned by evaluating the
9600 first argument is again true, the Lisp interpreter again evaluates the
9601 body of the expression.
9603 @need 1200
9604 The template for a @code{while} expression looks like this:
9606 @smallexample
9607 @group
9608 (while @var{true-or-false-test}
9609   @var{body}@dots{})
9610 @end group
9611 @end smallexample
9613 @menu
9614 * Looping with while::          Repeat so long as test returns true.
9615 * Loop Example::                A @code{while} loop that uses a list.
9616 * print-elements-of-list::      Uses @code{while}, @code{car}, @code{cdr}.
9617 * Incrementing Loop::           A loop with an incrementing counter.
9618 * Decrementing Loop::           A loop with a decrementing counter.
9619 @end menu
9621 @node Looping with while, Loop Example, while, while
9622 @ifnottex
9623 @unnumberedsubsec Looping with @code{while}
9624 @end ifnottex
9626 So long as the true-or-false-test of the @code{while} expression
9627 returns a true value when it is evaluated, the body is repeatedly
9628 evaluated.  This process is called a loop since the Lisp interpreter
9629 repeats the same thing again and again, like an airplane doing a loop.
9630 When the result of evaluating the true-or-false-test is false, the
9631 Lisp interpreter does not evaluate the rest of the @code{while}
9632 expression and `exits the loop'.
9634 Clearly, if the value returned by evaluating the first argument to
9635 @code{while} is always true, the body following will be evaluated
9636 again and again @dots{} and again @dots{} forever.  Conversely, if the
9637 value returned is never true, the expressions in the body will never
9638 be evaluated.  The craft of writing a @code{while} loop consists of
9639 choosing a mechanism such that the true-or-false-test returns true
9640 just the number of times that you want the subsequent expressions to
9641 be evaluated, and then have the test return false.
9643 The value returned by evaluating a @code{while} is the value of the
9644 true-or-false-test.  An interesting consequence of this is that a
9645 @code{while} loop that evaluates without error will return @code{nil}
9646 or false regardless of whether it has looped 1 or 100 times or none at
9647 all.  A @code{while} expression that evaluates successfully never
9648 returns a true value!  What this means is that @code{while} is always
9649 evaluated for its side effects, which is to say, the consequences of
9650 evaluating the expressions within the body of the @code{while} loop.
9651 This makes sense.  It is not the mere act of looping that is desired,
9652 but the consequences of what happens when the expressions in the loop
9653 are repeatedly evaluated.
9655 @node Loop Example, print-elements-of-list, Looping with while, while
9656 @comment  node-name,  next,  previous,  up
9657 @subsection A @code{while} Loop and a List
9659 A common way to control a @code{while} loop is to test whether a list
9660 has any elements.  If it does, the loop is repeated; but if it does not,
9661 the repetition is ended.  Since this is an important technique, we will
9662 create a short example to illustrate it.
9664 A simple way to test whether a list has elements is to evaluate the
9665 list: if it has no elements, it is an empty list and will return the
9666 empty list, @code{()}, which is a synonym for @code{nil} or false.  On
9667 the other hand, a list with elements will return those elements when it
9668 is evaluated.  Since Emacs Lisp considers as true any value that is not
9669 @code{nil}, a list that returns elements will test true in a
9670 @code{while} loop.
9672 @need 1200
9673 For example, you can set the variable @code{empty-list} to @code{nil} by
9674 evaluating the following @code{setq} expression:
9676 @smallexample
9677 (setq empty-list ())
9678 @end smallexample
9680 @noindent
9681 After evaluating the @code{setq} expression, you can evaluate the
9682 variable @code{empty-list} in the usual way, by placing the cursor after
9683 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
9684 echo area:
9686 @smallexample
9687 empty-list
9688 @end smallexample
9690 On the other hand, if you set a variable to be a list with elements, the
9691 list will appear when you evaluate the variable, as you can see by
9692 evaluating the following two expressions:
9694 @smallexample
9695 @group
9696 (setq animals '(gazelle giraffe lion tiger))
9698 animals
9699 @end group
9700 @end smallexample
9702 Thus, to create a @code{while} loop that tests whether there are any
9703 items in the list @code{animals}, the first part of the loop will be
9704 written like this:
9706 @smallexample
9707 @group
9708 (while animals
9709        @dots{}
9710 @end group
9711 @end smallexample
9713 @noindent
9714 When the @code{while} tests its first argument, the variable
9715 @code{animals} is evaluated.  It returns a list.  So long as the list
9716 has elements, the @code{while} considers the results of the test to be
9717 true; but when the list is empty, it considers the results of the test
9718 to be false.
9720 To prevent the @code{while} loop from running forever, some mechanism
9721 needs to be provided to empty the list eventually.  An oft-used
9722 technique is to have one of the subsequent forms in the @code{while}
9723 expression set the value of the list to be the @sc{cdr} of the list.
9724 Each time the @code{cdr} function is evaluated, the list will be made
9725 shorter, until eventually only the empty list will be left.  At this
9726 point, the test of the @code{while} loop will return false, and the
9727 arguments to the @code{while} will no longer be evaluated.
9729 For example, the list of animals bound to the variable @code{animals}
9730 can be set to be the @sc{cdr} of the original list with the
9731 following expression:
9733 @smallexample
9734 (setq animals (cdr animals))
9735 @end smallexample
9737 @noindent
9738 If you have evaluated the previous expressions and then evaluate this
9739 expression, you will see @code{(giraffe lion tiger)} appear in the echo
9740 area.  If you evaluate the expression again, @code{(lion tiger)} will
9741 appear in the echo area.  If you evaluate it again and yet again,
9742 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
9744 A template for a @code{while} loop that uses the @code{cdr} function
9745 repeatedly to cause the true-or-false-test eventually to test false
9746 looks like this:
9748 @smallexample
9749 @group
9750 (while @var{test-whether-list-is-empty}
9751   @var{body}@dots{}
9752   @var{set-list-to-cdr-of-list})
9753 @end group
9754 @end smallexample
9756 This test and use of @code{cdr} can be put together in a function that
9757 goes through a list and prints each element of the list on a line of its
9758 own.
9760 @node print-elements-of-list, Incrementing Loop, Loop Example, while
9761 @subsection An Example: @code{print-elements-of-list}
9762 @findex print-elements-of-list
9764 The @code{print-elements-of-list} function illustrates a @code{while}
9765 loop with a list.
9767 @cindex @file{*scratch*} buffer
9768 The function requires several lines for its output.  If you are
9769 reading this in Emacs 21 or a later version, you can evaluate the
9770 following expression inside of Info, as usual.
9772 If you are using an earlier version of Emacs, you need to copy the
9773 necessary expressions to your @file{*scratch*} buffer and evaluate
9774 them there.  This is because the echo area had only one line in the
9775 earlier versions.
9777 You can copy the expressions by marking the beginning of the region
9778 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
9779 the end of the region and then copying the region using @kbd{M-w}
9780 (@code{copy-region-as-kill}).  In the @file{*scratch*} buffer, you can
9781 yank the expressions back by typing @kbd{C-y} (@code{yank}).
9783 After you have copied the expressions to the @file{*scratch*} buffer,
9784 evaluate each expression in turn.  Be sure to evaluate the last
9785 expression, @code{(print-elements-of-list animals)}, by typing
9786 @kbd{C-u C-x C-e}, that is, by giving an argument to
9787 @code{eval-last-sexp}.  This will cause the result of the evaluation
9788 to be printed in the @file{*scratch*} buffer instead of being printed
9789 in the echo area.  (Otherwise you will see something like this in your
9790 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
9791 each @samp{^J} stands for a `newline'.)
9793 @need 1500
9794 If you are using Emacs 21 or later, you can evaluate these expressions
9795 directly in the Info buffer, and the echo area will grow to show the
9796 results.
9798 @smallexample
9799 @group
9800 (setq animals '(gazelle giraffe lion tiger))
9802 (defun print-elements-of-list (list)
9803   "Print each element of LIST on a line of its own."
9804   (while list
9805     (print (car list))
9806     (setq list (cdr list))))
9808 (print-elements-of-list animals)
9809 @end group
9810 @end smallexample
9812 @need 1200
9813 @noindent
9814 When you evaluate the three expressions in sequence, you will see
9815 this:
9817 @smallexample
9818 @group
9819 gazelle
9821 giraffe
9823 lion
9825 tiger
9827 @end group
9828 @end smallexample
9830 Each element of the list is printed on a line of its own (that is what
9831 the function @code{print} does) and then the value returned by the
9832 function is printed.  Since the last expression in the function is the
9833 @code{while} loop, and since @code{while} loops always return
9834 @code{nil}, a @code{nil} is printed after the last element of the list.
9836 @node Incrementing Loop, Decrementing Loop, print-elements-of-list, while
9837 @comment  node-name,  next,  previous,  up
9838 @subsection A Loop with an Incrementing Counter
9840 A loop is not useful unless it stops when it ought.  Besides
9841 controlling a loop with a list, a common way of stopping a loop is to
9842 write the first argument as a test that returns false when the correct
9843 number of repetitions are complete.  This means that the loop must
9844 have a counter---an expression that counts how many times the loop
9845 repeats itself.
9847 The test can be an expression such as @code{(< count desired-number)}
9848 which returns @code{t} for true if the value of @code{count} is less
9849 than the @code{desired-number} of repetitions and @code{nil} for false if
9850 the value of @code{count} is equal to or is greater than the
9851 @code{desired-number}.  The expression that increments the count can be
9852 a simple @code{setq} such as @code{(setq count (1+ count))}, where
9853 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
9854 argument.  (The expression @w{@code{(1+ count)}} has the same result as
9855 @w{@code{(+ count 1)}}, but is easier for a human to read.)
9857 @need 1250
9858 The template for a @code{while} loop controlled by an incrementing
9859 counter looks like this:
9861 @smallexample
9862 @group
9863 @var{set-count-to-initial-value}
9864 (while (< count desired-number)         ; @r{true-or-false-test}
9865   @var{body}@dots{}
9866   (setq count (1+ count)))              ; @r{incrementer}
9867 @end group
9868 @end smallexample
9870 @noindent
9871 Note that you need to set the initial value of @code{count}; usually it
9872 is set to 1.
9874 @menu
9875 * Incrementing Example::        Counting pebbles in a triangle.
9876 * Inc Example parts::           The parts of the function definition.
9877 * Inc Example altogether::      Putting the function definition together.
9878 @end menu
9880 @node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop
9881 @unnumberedsubsubsec  Example with incrementing counter
9883 Suppose you are playing on the beach and decide to make a triangle of
9884 pebbles, putting one pebble in the first row, two in the second row,
9885 three in the third row and so on, like this:
9887 @sp 1
9888 @c pebble diagram
9889 @ifnottex
9890 @smallexample
9891 @group
9892                *
9893               * *
9894              * * *
9895             * * * *
9896 @end group
9897 @end smallexample
9898 @end ifnottex
9899 @iftex
9900 @smallexample
9901 @group
9902                @bullet{}
9903               @bullet{} @bullet{}
9904              @bullet{} @bullet{} @bullet{}
9905             @bullet{} @bullet{} @bullet{} @bullet{}
9906 @end group
9907 @end smallexample
9908 @end iftex
9909 @sp 1
9911 @noindent
9912 (About 2500 years ago, Pythagoras and others developed the beginnings of
9913 number theory by considering questions such as this.)
9915 Suppose you want to know how many pebbles you will need to make a
9916 triangle with 7 rows?
9918 Clearly, what you need to do is add up the numbers from 1 to 7.  There
9919 are two ways to do this; start with the smallest number, one, and add up
9920 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
9921 number and add the list going down: 7, 6, 5, 4 and so on.  Because both
9922 mechanisms illustrate common ways of writing @code{while} loops, we will
9923 create two examples, one counting up and the other counting down.  In
9924 this first example, we will start with 1 and add 2, 3, 4 and so on.
9926 If you are just adding up a short list of numbers, the easiest way to do
9927 it is to add up all the numbers at once.  However, if you do not know
9928 ahead of time how many numbers your list will have, or if you want to be
9929 prepared for a very long list, then you need to design your addition so
9930 that what you do is repeat a simple process many times instead of doing
9931 a more complex process once.
9933 For example, instead of adding up all the pebbles all at once, what you
9934 can do is add the number of pebbles in the first row, 1, to the number
9935 in the second row, 2, and then add the total of those two rows to the
9936 third row, 3.  Then you can add the number in the fourth row, 4, to the
9937 total of the first three rows; and so on.
9939 The critical characteristic of the process is that each repetitive
9940 action is simple.  In this case, at each step we add only two numbers,
9941 the number of pebbles in the row and the total already found.  This
9942 process of adding two numbers is repeated again and again until the last
9943 row has been added to the total of all the preceding rows.  In a more
9944 complex loop the repetitive action might not be so simple, but it will
9945 be simpler than doing everything all at once.
9947 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop
9948 @unnumberedsubsubsec The parts of the function definition
9950 The preceding analysis gives us the bones of our function definition:
9951 first, we will need a variable that we can call @code{total} that will
9952 be the total number of pebbles.  This will be the value returned by
9953 the function.
9955 Second, we know that the function will require an argument: this
9956 argument will be the total number of rows in the triangle.  It can be
9957 called @code{number-of-rows}.
9959 Finally, we need a variable to use as a counter.  We could call this
9960 variable @code{counter}, but a better name is @code{row-number}.
9961 That is because what the counter does is count rows, and a program
9962 should be written to be as understandable as possible.
9964 When the Lisp interpreter first starts evaluating the expressions in the
9965 function, the value of @code{total} should be set to zero, since we have
9966 not added anything to it.  Then the function should add the number of
9967 pebbles in the first row to the total, and then add the number of
9968 pebbles in the second to the total, and then add the number of
9969 pebbles in the third row to the total, and so on, until there are no
9970 more rows left to add.
9972 Both @code{total} and @code{row-number} are used only inside the
9973 function, so they can be declared as local variables with @code{let}
9974 and given initial values.  Clearly, the initial value for @code{total}
9975 should be 0.  The initial value of @code{row-number} should be 1,
9976 since we start with the first row.  This means that the @code{let}
9977 statement will look like this:
9979 @smallexample
9980 @group
9981   (let ((total 0)
9982         (row-number 1))
9983     @var{body}@dots{})
9984 @end group
9985 @end smallexample
9987 After the internal variables are declared and bound to their initial
9988 values, we can begin the @code{while} loop.  The expression that serves
9989 as the test should return a value of @code{t} for true so long as the
9990 @code{row-number} is less than or equal to the @code{number-of-rows}.
9991 (If the expression tests true only so long as the row number is less
9992 than the number of rows in the triangle, the last row will never be
9993 added to the total; hence the row number has to be either less than or
9994 equal to the number of rows.)
9996 @need 1500
9997 @findex <= @r{(less than or equal)}
9998 Lisp provides the @code{<=} function that returns true if the value of
9999 its first argument is less than or equal to the value of its second
10000 argument and false otherwise.  So the expression that the @code{while}
10001 will evaluate as its test should look like this:
10003 @smallexample
10004 (<= row-number number-of-rows)
10005 @end smallexample
10007 The total number of pebbles can be found by repeatedly adding the number
10008 of pebbles in a row to the total already found.  Since the number of
10009 pebbles in the row is equal to the row number, the total can be found by
10010 adding the row number to the total.  (Clearly, in a more complex
10011 situation, the number of pebbles in the row might be related to the row
10012 number in a more complicated way; if this were the case, the row number
10013 would be replaced by the appropriate expression.)
10015 @smallexample
10016 (setq total (+ total row-number))
10017 @end smallexample
10019 @noindent
10020 What this does is set the new value of @code{total} to be equal to the
10021 sum of adding the number of pebbles in the row to the previous total.
10023 After setting the value of @code{total}, the conditions need to be
10024 established for the next repetition of the loop, if there is one.  This
10025 is done by incrementing the value of the @code{row-number} variable,
10026 which serves as a counter.  After the @code{row-number} variable has
10027 been incremented, the true-or-false-test at the beginning of the
10028 @code{while} loop tests whether its value is still less than or equal to
10029 the value of the @code{number-of-rows} and if it is, adds the new value
10030 of the @code{row-number} variable to the @code{total} of the previous
10031 repetition of the loop.
10033 @need 1200
10034 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
10035 @code{row-number} variable can be incremented with this expression:
10037 @smallexample
10038 (setq row-number (1+ row-number))
10039 @end smallexample
10041 @node Inc Example altogether,  , Inc Example parts, Incrementing Loop
10042 @unnumberedsubsubsec Putting the function definition together
10044 We have created the parts for the function definition; now we need to
10045 put them together.
10047 @need 800
10048 First, the contents of the @code{while} expression:
10050 @smallexample
10051 @group
10052 (while (<= row-number number-of-rows)   ; @r{true-or-false-test}
10053   (setq total (+ total row-number))
10054   (setq row-number (1+ row-number)))    ; @r{incrementer}
10055 @end group
10056 @end smallexample
10058 Along with the @code{let} expression varlist, this very nearly
10059 completes the body of the function definition.  However, it requires
10060 one final element, the need for which is somewhat subtle.
10062 The final touch is to place the variable @code{total} on a line by
10063 itself after the @code{while} expression.  Otherwise, the value returned
10064 by the whole function is the value of the last expression that is
10065 evaluated in the body of the @code{let}, and this is the value
10066 returned by the @code{while}, which is always @code{nil}.
10068 This may not be evident at first sight.  It almost looks as if the
10069 incrementing expression is the last expression of the whole function.
10070 But that expression is part of the body of the @code{while}; it is the
10071 last element of the list that starts with the symbol @code{while}.
10072 Moreover, the whole of the @code{while} loop is a list within the body
10073 of the @code{let}.
10075 @need 1250
10076 In outline, the function will look like this:
10078 @smallexample
10079 @group
10080 (defun @var{name-of-function} (@var{argument-list})
10081   "@var{documentation}@dots{}"
10082   (let (@var{varlist})
10083     (while (@var{true-or-false-test})
10084       @var{body-of-while}@dots{} )
10085     @dots{} )                     ; @r{Need final expression here.}
10086 @end group
10087 @end smallexample
10089 The result of evaluating the @code{let} is what is going to be returned
10090 by the @code{defun} since the @code{let} is not embedded within any
10091 containing list, except for the @code{defun} as a whole.  However, if
10092 the @code{while} is the last element of the @code{let} expression, the
10093 function will always return @code{nil}.  This is not what we want!
10094 Instead, what we want is the value of the variable @code{total}.  This
10095 is returned by simply placing the symbol as the last element of the list
10096 starting with @code{let}.  It gets evaluated after the preceding
10097 elements of the list are evaluated, which means it gets evaluated after
10098 it has been assigned the correct value for the total.
10100 It may be easier to see this by printing the list starting with
10101 @code{let} all on one line.  This format makes it evident that the
10102 @var{varlist} and @code{while} expressions are the second and third
10103 elements of the list starting with @code{let}, and the @code{total} is
10104 the last element:
10106 @smallexample
10107 @group
10108 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
10109 @end group
10110 @end smallexample
10112 @need 1200
10113 Putting everything together, the @code{triangle} function definition
10114 looks like this:
10116 @smallexample
10117 @group
10118 (defun triangle (number-of-rows)    ; @r{Version with}
10119                                     ; @r{  incrementing counter.}
10120   "Add up the number of pebbles in a triangle.
10121 The first row has one pebble, the second row two pebbles,
10122 the third row three pebbles, and so on.
10123 The argument is NUMBER-OF-ROWS."
10124 @end group
10125 @group
10126   (let ((total 0)
10127         (row-number 1))
10128     (while (<= row-number number-of-rows)
10129       (setq total (+ total row-number))
10130       (setq row-number (1+ row-number)))
10131     total))
10132 @end group
10133 @end smallexample
10135 @need 1200
10136 After you have installed @code{triangle} by evaluating the function, you
10137 can try it out.  Here are two examples:
10139 @smallexample
10140 @group
10141 (triangle 4)
10143 (triangle 7)
10144 @end group
10145 @end smallexample
10147 @noindent
10148 The sum of the first four numbers is 10 and the sum of the first seven
10149 numbers is 28.
10151 @node Decrementing Loop,  , Incrementing Loop, while
10152 @comment  node-name,  next,  previous,  up
10153 @subsection Loop with a Decrementing Counter
10155 Another common way to write a @code{while} loop is to write the test
10156 so that it determines whether a counter is greater than zero.  So long
10157 as the counter is greater than zero, the loop is repeated.  But when
10158 the counter is equal to or less than zero, the loop is stopped.  For
10159 this to work, the counter has to start out greater than zero and then
10160 be made smaller and smaller by a form that is evaluated
10161 repeatedly.
10163 The test will be an expression such as @code{(> counter 0)} which
10164 returns @code{t} for true if the value of @code{counter} is greater
10165 than zero, and @code{nil} for false if the value of @code{counter} is
10166 equal to or less than zero.  The expression that makes the number
10167 smaller and smaller can be a simple @code{setq} such as @code{(setq
10168 counter (1- counter))}, where @code{1-} is a built-in function in
10169 Emacs Lisp that subtracts 1 from its argument.
10171 @need 1250
10172 The template for a decrementing @code{while} loop looks like this:
10174 @smallexample
10175 @group
10176 (while (> counter 0)                    ; @r{true-or-false-test}
10177   @var{body}@dots{}
10178   (setq counter (1- counter)))          ; @r{decrementer}
10179 @end group
10180 @end smallexample
10182 @menu
10183 * Decrementing Example::        More pebbles on the beach.
10184 * Dec Example parts::           The parts of the function definition.
10185 * Dec Example altogether::      Putting the function definition together.
10186 @end menu
10188 @node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
10189 @unnumberedsubsubsec Example with decrementing counter
10191 To illustrate a loop with a decrementing counter, we will rewrite the
10192 @code{triangle} function so the counter decreases to zero.
10194 This is the reverse of the earlier version of the function.  In this
10195 case, to find out how many pebbles are needed to make a triangle with
10196 3 rows, add the number of pebbles in the third row, 3, to the number
10197 in the preceding row, 2, and then add the total of those two rows to
10198 the row that precedes them, which is 1.
10200 Likewise, to find the number of pebbles in a triangle with 7 rows, add
10201 the number of pebbles in the seventh row, 7, to the number in the
10202 preceding row, which is 6, and then add the total of those two rows to
10203 the row that precedes them, which is 5, and so on.  As in the previous
10204 example, each addition only involves adding two numbers, the total of
10205 the rows already added up and the number of pebbles in the row that is
10206 being added to the total.  This process of adding two numbers is
10207 repeated again and again until there are no more pebbles to add.
10209 We know how many pebbles to start with: the number of pebbles in the
10210 last row is equal to the number of rows.  If the triangle has seven
10211 rows, the number of pebbles in the last row is 7.  Likewise, we know how
10212 many pebbles are in the preceding row: it is one less than the number in
10213 the row.
10215 @node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop
10216 @unnumberedsubsubsec The parts of the function definition
10218 We start with three variables: the total number of rows in the
10219 triangle; the number of pebbles in a row; and the total number of
10220 pebbles, which is what we want to calculate.  These variables can be
10221 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
10222 @code{total}, respectively.
10224 Both @code{total} and @code{number-of-pebbles-in-row} are used only
10225 inside the function and are declared with @code{let}.  The initial
10226 value of @code{total} should, of course, be zero.  However, the
10227 initial value of @code{number-of-pebbles-in-row} should be equal to
10228 the number of rows in the triangle, since the addition will start with
10229 the longest row.
10231 @need 1250
10232 This means that the beginning of the @code{let} expression will look
10233 like this:
10235 @smallexample
10236 @group
10237 (let ((total 0)
10238       (number-of-pebbles-in-row number-of-rows))
10239   @var{body}@dots{})
10240 @end group
10241 @end smallexample
10243 The total number of pebbles can be found by repeatedly adding the number
10244 of pebbles in a row to the total already found, that is, by repeatedly
10245 evaluating the following expression:
10247 @smallexample
10248 (setq total (+ total number-of-pebbles-in-row))
10249 @end smallexample
10251 @noindent
10252 After the @code{number-of-pebbles-in-row} is added to the @code{total},
10253 the @code{number-of-pebbles-in-row} should be decremented by one, since
10254 the next time the loop repeats, the preceding row will be
10255 added to the total.
10257 The number of pebbles in a preceding row is one less than the number of
10258 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
10259 used to compute the number of pebbles in the preceding row.  This can be
10260 done with the following expression:
10262 @smallexample
10263 @group
10264 (setq number-of-pebbles-in-row
10265       (1- number-of-pebbles-in-row))
10266 @end group
10267 @end smallexample
10269 Finally, we know that the @code{while} loop should stop making repeated
10270 additions when there are no pebbles in a row.  So the test for
10271 the @code{while} loop is simply:
10273 @smallexample
10274 (while (> number-of-pebbles-in-row 0)
10275 @end smallexample
10277 @node Dec Example altogether,  , Dec Example parts, Decrementing Loop
10278 @unnumberedsubsubsec Putting the function definition together
10280 We can put these expressions together to create a function definition
10281 that works.  However, on examination, we find that one of the local
10282 variables is unneeded!
10284 @need 1250
10285 The function definition looks like this:
10287 @smallexample
10288 @group
10289 ;;; @r{First subtractive version.}
10290 (defun triangle (number-of-rows)
10291   "Add up the number of pebbles in a triangle."
10292   (let ((total 0)
10293         (number-of-pebbles-in-row number-of-rows))
10294     (while (> number-of-pebbles-in-row 0)
10295       (setq total (+ total number-of-pebbles-in-row))
10296       (setq number-of-pebbles-in-row
10297             (1- number-of-pebbles-in-row)))
10298     total))
10299 @end group
10300 @end smallexample
10302 As written, this function works.
10304 However, we do not need @code{number-of-pebbles-in-row}.
10306 @cindex Argument as local variable
10307 When the @code{triangle} function is evaluated, the symbol
10308 @code{number-of-rows} will be bound to a number, giving it an initial
10309 value.  That number can be changed in the body of the function as if
10310 it were a local variable, without any fear that such a change will
10311 effect the value of the variable outside of the function.  This is a
10312 very useful characteristic of Lisp; it means that the variable
10313 @code{number-of-rows} can be used anywhere in the function where
10314 @code{number-of-pebbles-in-row} is used.
10316 @need 800
10317 Here is a second version of the function written a bit more cleanly:
10319 @smallexample
10320 @group
10321 (defun triangle (number)                ; @r{Second version.}
10322   "Return sum of numbers 1 through NUMBER inclusive."
10323   (let ((total 0))
10324     (while (> number 0)
10325       (setq total (+ total number))
10326       (setq number (1- number)))
10327     total))
10328 @end group
10329 @end smallexample
10331 In brief, a properly written @code{while} loop will consist of three parts:
10333 @enumerate
10334 @item
10335 A test that will return false after the loop has repeated itself the
10336 correct number of times.
10338 @item
10339 An expression the evaluation of which will return the value desired
10340 after being repeatedly evaluated.
10342 @item
10343 An expression to change the value passed to the true-or-false-test so
10344 that the test returns false after the loop has repeated itself the right
10345 number of times.
10346 @end enumerate
10348 @node dolist dotimes, Recursion, while, Loops & Recursion
10349 @comment  node-name,  next,  previous,  up
10350 @section Save your time: @code{dolist} and @code{dotimes}
10352 In addition to @code{while}, both @code{dolist} and @code{dotimes}
10353 provide for looping.  Sometimes these are quicker to write than the
10354 equivalent @code{while} loop.  Both are Lisp macros.  (@xref{Macros, ,
10355 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
10357 @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a
10358 list':  @code{dolist} automatically shortens the list each time it
10359 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
10360 each shorter version of the list to the first of its arguments.
10362 @code{dotimes} loops a specific number of times: you specify the number.
10364 @menu
10365 * dolist::
10366 * dotimes::
10367 @end menu
10369 @node dolist, dotimes, dolist dotimes, dolist dotimes
10370 @unnumberedsubsubsec The @code{dolist} Macro
10371 @findex dolist
10373 Suppose, for example, you want to reverse a list, so that
10374 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
10376 @need 1250
10377 In practice, you would use the @code{reverse} function, like this:
10379 @smallexample
10380 @group
10381 (setq animals '(gazelle giraffe lion tiger))
10383 (reverse animals)
10384 @end group
10385 @end smallexample
10387 @need 800
10388 @noindent
10389 Here is how you could reverse the list using a @code{while} loop:
10391 @smallexample
10392 @group
10393 (setq animals '(gazelle giraffe lion tiger))
10395 (defun reverse-list-with-while (list)
10396   "Using while, reverse the order of LIST."
10397   (let (value)  ; make sure list starts empty
10398     (while list
10399       (setq value (cons (car list) value))
10400       (setq list (cdr list)))
10401     value))
10403 (reverse-list-with-while animals)
10404 @end group
10405 @end smallexample
10407 @need 800
10408 @noindent
10409 And here is how you could use the @code{dolist} macro:
10411 @smallexample
10412 @group
10413 (setq animals '(gazelle giraffe lion tiger))
10415 (defun reverse-list-with-dolist (list)
10416   "Using dolist, reverse the order of LIST."
10417   (let (value)  ; make sure list starts empty
10418     (dolist (element list value)
10419       (setq value (cons element value)))))
10421 (reverse-list-with-dolist animals)
10422 @end group
10423 @end smallexample
10425 @need 1250
10426 @noindent
10427 In Info, you can place your cursor after the closing parenthesis of
10428 each expression and type @kbd{C-x C-e}; in each case, you should see
10430 @smallexample
10431 (tiger lion giraffe gazelle)
10432 @end smallexample
10434 @noindent
10435 in the echo area.
10437 For this example, the existing @code{reverse} function is obviously best.
10438 The @code{while} loop is just like our first example (@pxref{Loop
10439 Example, , A @code{while} Loop and a List}).  The @code{while} first
10440 checks whether the list has elements; if so, it constructs a new list
10441 by adding the first element of the list to the existing list (which in
10442 the first iteration of the loop is @code{nil}).  Since the second
10443 element is prepended in front of the first element, and the third
10444 element is prepended in front of the second element, the list is reversed.
10446 In the expression using a @code{while} loop,
10447 the @w{@code{(setq list (cdr list))}}
10448 expression shortens the list, so the @code{while} loop eventually
10449 stops.  In addition, it provides the @code{cons} expression with a new
10450 first element by creating a new and shorter list at each repetition of
10451 the loop.
10453 The @code{dolist} expression does very much the same as the
10454 @code{while} expression, except that the @code{dolist} macro does some
10455 of the work you have to do when writing a @code{while} expression.
10457 Like a @code{while} loop, a @code{dolist} loops.  What is different is
10458 that it automatically shortens the list each time it loops --- it
10459 `@sc{cdr}s down the list' on its own --- and it automatically binds
10460 the @sc{car} of each shorter version of the list to the first of its
10461 arguments.
10463 In the example, the @sc{car} of each shorter version of the list is
10464 referred to using the symbol @samp{element}, the list itself is called
10465 @samp{list}, and the value returned is called @samp{value}.  The
10466 remainder of the @code{dolist} expression is the body.
10468 The @code{dolist} expression binds the @sc{car} of each shorter
10469 version of the list to @code{element} and then evaluates the body of
10470 the expression; and repeats the loop.  The result is returned in
10471 @code{value}.
10473 @node dotimes,  , dolist, dolist dotimes
10474 @unnumberedsubsubsec The @code{dotimes} Macro
10475 @findex dotimes
10477 The @code{dotimes} macro is similar to @code{dolist}, except that it
10478 loops a specific number of times.
10480 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
10481 and so forth each time around the loop, and the value of the third
10482 argument is returned.  You need to provide the value of the second
10483 argument, which is how many times the macro loops.
10485 @need 1250
10486 For example, the following binds the numbers from 0 up to, but not
10487 including, the number 3 to the first argument, @var{number}, and then
10488 constructs a list of the three numbers.  (The first number is 0, the
10489 second number is 1, and the third number is 2; this makes a total of
10490 three numbers in all, starting with zero as the first number.)
10492 @smallexample
10493 @group
10494 (let (value)      ; otherwise a value is a void variable
10495   (dotimes (number 3 value)
10496     (setq value (cons number value))))
10498 @result{} (2 1 0)
10499 @end group
10500 @end smallexample
10502 @noindent
10503 @code{dotimes} returns @code{value}, so the way to use
10504 @code{dotimes} is to operate on some expression @var{number} number of
10505 times and then return the result, either as a list or an atom.
10507 @need 1250
10508 Here is an example of a @code{defun} that uses @code{dotimes} to add
10509 up the number of pebbles in a triangle.
10511 @smallexample
10512 @group
10513 (defun triangle-using-dotimes (number-of-rows)
10514   "Using dotimes, add up the number of pebbles in a triangle."
10515 (let ((total 0))  ; otherwise a total is a void variable
10516   (dotimes (number number-of-rows total)
10517     (setq total (+ total (1+ number))))))
10519 (triangle-using-dotimes 4)
10520 @end group
10521 @end smallexample
10523 @node Recursion, Looping exercise, dolist dotimes, Loops & Recursion
10524 @comment  node-name,  next,  previous,  up
10525 @section Recursion
10526 @cindex Recursion
10528 A recursive function contains code that tells the Lisp interpreter to
10529 call a program that runs exactly like itself, but with slightly
10530 different arguments.  The code runs exactly the same because it has
10531 the same name.  However, even though the program has the same name, it
10532 is not the same entity.  It is different.  In the jargon, it is a
10533 different `instance'.
10535 Eventually, if the program is written correctly, the `slightly
10536 different arguments' will become sufficiently different from the first
10537 arguments that the final instance will stop.
10539 @menu
10540 * Building Robots::             Same model, different serial number ...
10541 * Recursive Definition Parts::  Walk until you stop ...
10542 * Recursion with list::         Using a list as the test whether to recurse.
10543 * Recursive triangle function::
10544 * Recursion with cond::
10545 * Recursive Patterns::          Often used templates.
10546 * No Deferment::                Don't store up work ...
10547 * No deferment solution::
10548 @end menu
10550 @node Building Robots, Recursive Definition Parts, Recursion, Recursion
10551 @comment  node-name,  next,  previous,  up
10552 @subsection Building Robots: Extending the Metaphor
10553 @cindex Building robots
10554 @cindex Robots, building
10556 It is sometimes helpful to think of a running program as a robot that
10557 does a job.  In doing its job, a recursive function calls on a second
10558 robot to help it.  The second robot is identical to the first in every
10559 way, except that the second robot helps the first and has been
10560 passed different arguments than the first.
10562 In a recursive function, the second robot may call a third; and the
10563 third may call a fourth, and so on.  Each of these is a different
10564 entity; but all are clones.
10566 Since each robot has slightly different instructions---the arguments
10567 will differ from one robot to the next---the last robot should know
10568 when to stop.
10570 Let's expand on the metaphor in which a computer program is a robot.
10572 A function definition provides the blueprints for a robot.  When you
10573 install a function definition, that is, when you evaluate a
10574 @code{defun} special form, you install the necessary equipment to
10575 build robots.  It is as if you were in a factory, setting up an
10576 assembly line.  Robots with the same name are built according to the
10577 same blueprints.  So they have, as it were, the same `model number',
10578 but a different `serial number'.
10580 We often say that a recursive function `calls itself'.  What we mean
10581 is that the instructions in a recursive function cause the Lisp
10582 interpreter to run a different function that has the same name and
10583 does the same job as the first, but with different arguments.
10585 It is important that the arguments differ from one instance to the
10586 next; otherwise, the process will never stop.
10588 @node Recursive Definition Parts, Recursion with list, Building Robots, Recursion
10589 @comment  node-name,  next,  previous,  up
10590 @subsection The Parts of a Recursive Definition
10591 @cindex Parts of a Recursive Definition
10592 @cindex Recursive Definition Parts
10594 A recursive function typically contains a conditional expression which
10595 has three parts:
10597 @enumerate
10598 @item
10599 A true-or-false-test that determines whether the function is called
10600 again, here called the @dfn{do-again-test}.
10602 @item
10603 The name of the function.  When this name is called, a new instance of
10604 the function---a new robot, as it were---is created and told what to do.
10606 @item
10607 An expression that returns a different value each time the function is
10608 called, here called the @dfn{next-step-expression}.  Consequently, the
10609 argument (or arguments) passed to the new instance of the function
10610 will be different from that passed to the previous instance.  This
10611 causes the conditional expression, the @dfn{do-again-test}, to test
10612 false after the correct number of repetitions.
10613 @end enumerate
10615 Recursive functions can be much simpler than any other kind of
10616 function.  Indeed, when people first start to use them, they often look
10617 so mysteriously simple as to be incomprehensible.  Like riding a
10618 bicycle, reading a recursive function definition takes a certain knack
10619 which is hard at first but then seems simple.
10621 @need 1200
10622 There are several different common recursive patterns.  A very simple
10623 pattern looks like this:
10625 @smallexample
10626 @group
10627 (defun @var{name-of-recursive-function} (@var{argument-list})
10628   "@var{documentation}@dots{}"
10629   (if @var{do-again-test}
10630     @var{body}@dots{}
10631     (@var{name-of-recursive-function}
10632          @var{next-step-expression})))
10633 @end group
10634 @end smallexample
10636 Each time a recursive function is evaluated, a new instance of it is
10637 created and told what to do.  The arguments tell the instance what to do.
10639 An argument is bound to the value of the next-step-expression.  Each
10640 instance runs with a different value of the next-step-expression.
10642 The value in the next-step-expression is used in the do-again-test.
10644 The value returned by the next-step-expression is passed to the new
10645 instance of the function, which evaluates it (or some
10646 transmogrification of it) to determine whether to continue or stop.
10647 The next-step-expression is designed so that the do-again-test returns
10648 false when the function should no longer be repeated.
10650 The do-again-test is sometimes called the @dfn{stop condition},
10651 since it stops the repetitions when it tests false.
10653 @node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion
10654 @comment  node-name,  next,  previous,  up
10655 @subsection Recursion with a List
10657 The example of a @code{while} loop that printed the elements of a list
10658 of numbers can be written recursively.  Here is the code, including
10659 an expression to set the value of the variable @code{animals} to a list.
10661 If you are using Emacs 20 or before, this example must be copied to
10662 the @file{*scratch*} buffer and each expression must be evaluated
10663 there.  Use @kbd{C-u C-x C-e} to evaluate the
10664 @code{(print-elements-recursively animals)} expression so that the
10665 results are printed in the buffer; otherwise the Lisp interpreter will
10666 try to squeeze the results into the one line of the echo area.
10668 Also, place your cursor immediately after the last closing parenthesis
10669 of the @code{print-elements-recursively} function, before the comment.
10670 Otherwise, the Lisp interpreter will try to evaluate the comment.
10672 If you are using Emacs 21 or later, you can evaluate this expression
10673 directly in Info.
10675 @findex print-elements-recursively
10676 @smallexample
10677 @group
10678 (setq animals '(gazelle giraffe lion tiger))
10680 (defun print-elements-recursively (list)
10681   "Print each element of LIST on a line of its own.
10682 Uses recursion."
10683   (if list                              ; @r{do-again-test}
10684       (progn
10685         (print (car list))              ; @r{body}
10686         (print-elements-recursively     ; @r{recursive call}
10687          (cdr list)))))                 ; @r{next-step-expression}
10689 (print-elements-recursively animals)
10690 @end group
10691 @end smallexample
10693 The @code{print-elements-recursively} function first tests whether
10694 there is any content in the list; if there is, the function prints the
10695 first element of the list, the @sc{car} of the list.  Then the
10696 function `invokes itself', but gives itself as its argument, not the
10697 whole list, but the second and subsequent elements of the list, the
10698 @sc{cdr} of the list.
10700 Put another way, if the list is not empty, the function invokes
10701 another instance of code that is similar to the initial code, but is a
10702 different thread of execution, with different arguments than the first
10703 instance.
10705 Put in yet another way, if the list is not empty, the first robot
10706 assemblies a second robot and tells it what to do; the second robot is
10707 a different individual from the first, but is the same model.
10709 When the second evaluation occurs, the @code{if} expression is
10710 evaluated and if true, prints the first element of the list it
10711 receives as its argument (which is the second element of the original
10712 list).  Then the function `calls itself' with the @sc{cdr} of the list
10713 it is invoked with, which (the second time around) is the @sc{cdr} of
10714 the @sc{cdr} of the original list.
10716 Note that although we say that the function `calls itself', what we
10717 mean is that the Lisp interpreter assembles and instructs a new
10718 instance of the program.  The new instance is a clone of the first,
10719 but is a separate individual.
10721 Each time the function `invokes itself', it invokes itself on a
10722 shorter version of the original list.  It creates a new instance that
10723 works on a shorter list.
10725 Eventually, the function invokes itself on an empty list.  It creates
10726 a new instance whose argument is @code{nil}.  The conditional expression
10727 tests the value of @code{list}.  Since the value of @code{list} is
10728 @code{nil}, the @code{if} expression tests false so the then-part is
10729 not evaluated.  The function as a whole then returns @code{nil}.
10731 @need 1200
10732 When you evaluate @code{(print-elements-recursively animals)} in the
10733 @file{*scratch*} buffer, you see this result:
10735 @smallexample
10736 @group
10737 gazelle
10739 giraffe
10741 lion
10743 tiger
10745 @end group
10746 @end smallexample
10748 @node Recursive triangle function, Recursion with cond, Recursion with list, Recursion
10749 @comment  node-name,  next,  previous,  up
10750 @subsection Recursion in Place of a Counter
10751 @findex triangle-recursively
10753 @need 1200
10754 The @code{triangle} function described in a previous section can also
10755 be written recursively.  It looks like this:
10757 @smallexample
10758 @group
10759 (defun triangle-recursively (number)
10760   "Return the sum of the numbers 1 through NUMBER inclusive.
10761 Uses recursion."
10762   (if (= number 1)                    ; @r{do-again-test}
10763       1                               ; @r{then-part}
10764     (+ number                         ; @r{else-part}
10765        (triangle-recursively          ; @r{recursive call}
10766         (1- number)))))               ; @r{next-step-expression}
10768 (triangle-recursively 7)
10769 @end group
10770 @end smallexample
10772 @noindent
10773 You can install this function by evaluating it and then try it by
10774 evaluating @code{(triangle-recursively 7)}.  (Remember to put your
10775 cursor immediately after the last parenthesis of the function
10776 definition, before the comment.)  The function evaluates to 28.
10778 To understand how this function works, let's consider what happens in the
10779 various cases when the function is passed 1, 2, 3, or 4 as the value of
10780 its argument.
10782 @menu
10783 * Recursive Example arg of 1 or 2::
10784 * Recursive Example arg of 3 or 4::
10785 @end menu
10787 @node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function
10788 @ifnottex
10789 @unnumberedsubsubsec An argument of 1 or 2
10790 @end ifnottex
10792 First, what happens if the value of the argument is 1?
10794 The function has an @code{if} expression after the documentation
10795 string.  It tests whether the value of @code{number} is equal to 1; if
10796 so, Emacs evaluates the then-part of the @code{if} expression, which
10797 returns the number 1 as the value of the function.  (A triangle with
10798 one row has one pebble in it.)
10800 Suppose, however, that the value of the argument is 2.  In this case,
10801 Emacs evaluates the else-part of the @code{if} expression.
10803 @need 1200
10804 The else-part consists of an addition, the recursive call to
10805 @code{triangle-recursively} and a decrementing action; and it looks like
10806 this:
10808 @smallexample
10809 (+ number (triangle-recursively (1- number)))
10810 @end smallexample
10812 When Emacs evaluates this expression, the innermost expression is
10813 evaluated first; then the other parts in sequence.  Here are the steps
10814 in detail:
10816 @table @i
10817 @item Step 1 @w{  } Evaluate the innermost expression.
10819 The innermost expression is @code{(1- number)} so Emacs decrements the
10820 value of @code{number} from 2 to 1.
10822 @item Step 2 @w{  } Evaluate the @code{triangle-recursively} function.
10824 The Lisp interpreter creates an individual instance of
10825 @code{triangle-recursively}.  It does not matter that this function is
10826 contained within itself.  Emacs passes the result Step 1 as the
10827 argument used by this instance of the @code{triangle-recursively}
10828 function
10830 In this case, Emacs evaluates @code{triangle-recursively} with an
10831 argument of 1.  This means that this evaluation of
10832 @code{triangle-recursively} returns 1.
10834 @item Step 3 @w{  } Evaluate the value of @code{number}.
10836 The variable @code{number} is the second element of the list that
10837 starts with @code{+}; its value is 2.
10839 @item Step 4 @w{  } Evaluate the @code{+} expression.
10841 The @code{+} expression receives two arguments, the first
10842 from the evaluation of @code{number} (Step 3) and the second from the
10843 evaluation of @code{triangle-recursively} (Step 2).
10845 The result of the addition is the sum of 2 plus 1, and the number 3 is
10846 returned, which is correct.  A triangle with two rows has three
10847 pebbles in it.
10848 @end table
10850 @node Recursive Example arg of 3 or 4,  , Recursive Example arg of 1 or 2, Recursive triangle function
10851 @unnumberedsubsubsec An argument of 3 or 4
10853 Suppose that @code{triangle-recursively} is called with an argument of
10856 @table @i
10857 @item Step 1 @w{  } Evaluate the do-again-test.
10859 The @code{if} expression is evaluated first.  This is the do-again
10860 test and returns false, so the else-part of the @code{if} expression
10861 is evaluated.  (Note that in this example, the do-again-test causes
10862 the function to call itself when it tests false, not when it tests
10863 true.)
10865 @item Step 2 @w{  } Evaluate the innermost expression of the else-part.
10867 The innermost expression of the else-part is evaluated, which decrements
10868 3 to 2.  This is the next-step-expression.
10870 @item Step 3 @w{  } Evaluate the @code{triangle-recursively} function.
10872 The number 2 is passed to the @code{triangle-recursively} function.
10874 We know what happens when Emacs evaluates @code{triangle-recursively} with
10875 an argument of 2.  After going through the sequence of actions described
10876 earlier, it returns a value of 3.  So that is what will happen here.
10878 @item Step 4 @w{  } Evaluate the addition.
10880 3 will be passed as an argument to the addition and will be added to the
10881 number with which the function was called, which is 3.
10882 @end table
10884 @noindent
10885 The value returned by the function as a whole will be 6.
10887 Now that we know what will happen when @code{triangle-recursively} is
10888 called with an argument of 3, it is evident what will happen if it is
10889 called with an argument of 4:
10891 @quotation
10892 @need 800
10893 In the recursive call, the evaluation of
10895 @smallexample
10896 (triangle-recursively (1- 4))
10897 @end smallexample
10899 @need 800
10900 @noindent
10901 will return the value of evaluating
10903 @smallexample
10904 (triangle-recursively 3)
10905 @end smallexample
10907 @noindent
10908 which is 6 and this value will be added to 4 by the addition in the
10909 third line.
10910 @end quotation
10912 @noindent
10913 The value returned by the function as a whole will be 10.
10915 Each time @code{triangle-recursively} is evaluated, it evaluates a
10916 version of itself---a different instance of itself---with a smaller
10917 argument, until the argument is small enough so that it does not
10918 evaluate itself.
10920 Note that this particular design for a recursive function
10921 requires that operations be deferred.
10923 Before @code{(triangle-recursively 7)} can calculate its answer, it
10924 must call @code{(triangle-recursively 6)}; and before
10925 @code{(triangle-recursively 6)} can calculate its answer, it must call
10926 @code{(triangle-recursively 5)}; and so on.  That is to say, the
10927 calculation that @code{(triangle-recursively 7)} makes must be
10928 deferred until @code{(triangle-recursively 6)} makes its calculation;
10929 and @code{(triangle-recursively 6)} must defer until
10930 @code{(triangle-recursively 5)} completes; and so on.
10932 If each of these instances of @code{triangle-recursively} are thought
10933 of as different robots, the first robot must wait for the second to
10934 complete its job, which must wait until the third completes, and so
10937 There is a way around this kind of waiting, which we will discuss in
10938 @ref{No Deferment, , Recursion without Deferments}.
10940 @node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion
10941 @comment  node-name,  next,  previous,  up
10942 @subsection Recursion Example Using @code{cond}
10943 @findex cond
10945 The version of @code{triangle-recursively} described earlier is written
10946 with the @code{if} special form.  It can also be written using another
10947 special form called @code{cond}.  The name of the special form
10948 @code{cond} is an abbreviation of the word @samp{conditional}.
10950 Although the @code{cond} special form is not used as often in the
10951 Emacs Lisp sources as @code{if}, it is used often enough to justify
10952 explaining it.
10954 @need 800
10955 The template for a @code{cond} expression looks like this:
10957 @smallexample
10958 @group
10959 (cond
10960  @var{body}@dots{})
10961 @end group
10962 @end smallexample
10964 @noindent
10965 where the @var{body} is a series of lists.
10967 @need 800
10968 Written out more fully, the template looks like this:
10970 @smallexample
10971 @group
10972 (cond
10973  (@var{first-true-or-false-test} @var{first-consequent})
10974  (@var{second-true-or-false-test} @var{second-consequent})
10975  (@var{third-true-or-false-test} @var{third-consequent})
10976   @dots{})
10977 @end group
10978 @end smallexample
10980 When the Lisp interpreter evaluates the @code{cond} expression, it
10981 evaluates the first element (the @sc{car} or true-or-false-test) of
10982 the first expression in a series of expressions within the body of the
10983 @code{cond}.
10985 If the true-or-false-test returns @code{nil} the rest of that
10986 expression, the consequent, is skipped and  the true-or-false-test of the
10987 next expression is evaluated.  When an expression is found whose
10988 true-or-false-test returns a value that is not @code{nil}, the
10989 consequent of that expression is evaluated.  The consequent can be one
10990 or more expressions.  If the consequent consists of more than one
10991 expression, the expressions are evaluated in sequence and the value of
10992 the last one is returned.  If the expression does not have a consequent,
10993 the value of the true-or-false-test is returned.
10995 If none of the true-or-false-tests test true, the @code{cond} expression
10996 returns @code{nil}.
10998 @need 1250
10999 Written using @code{cond}, the @code{triangle} function looks like this:
11001 @smallexample
11002 @group
11003 (defun triangle-using-cond (number)
11004   (cond ((<= number 0) 0)
11005         ((= number 1) 1)
11006         ((> number 1)
11007          (+ number (triangle-using-cond (1- number))))))
11008 @end group
11009 @end smallexample
11011 @noindent
11012 In this example, the @code{cond} returns 0 if the number is less than or
11013 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
11014 number (triangle-using-cond (1- number)))} if the number is greater than
11017 @node Recursive Patterns, No Deferment, Recursion with cond, Recursion
11018 @comment  node-name,  next,  previous,  up
11019 @subsection Recursive Patterns
11020 @cindex Recursive Patterns
11022 Here are three common recursive patterns.  Each involves a list.
11023 Recursion does not need to involve lists, but Lisp is designed for lists
11024 and this provides a sense of its primal capabilities.
11026 @menu
11027 * Every::
11028 * Accumulate::
11029 * Keep::
11030 @end menu
11032 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
11033 @comment  node-name,  next,  previous,  up
11034 @unnumberedsubsubsec Recursive Pattern: @emph{every}
11035 @cindex Every, type of recursive pattern
11036 @cindex Recursive pattern: every
11038 In the @code{every} recursive pattern, an action is performed on every
11039 element of a list.
11041 @need 1500
11042 The basic pattern is:
11044 @itemize @bullet
11045 @item
11046 If a list be empty, return @code{nil}.
11047 @item
11048 Else, act on the beginning of the list (the @sc{car} of the list)
11049     @itemize @minus
11050     @item
11051     through a recursive call by the function on the rest (the
11052     @sc{cdr}) of the list,
11053     @item
11054     and, optionally, combine the acted-on element, using @code{cons},
11055     with the results of acting on the rest.
11056     @end itemize
11057 @end itemize
11059 @need 1500
11060 Here is example:
11062 @smallexample
11063 @group
11064 (defun square-each (numbers-list)
11065   "Square each of a NUMBERS LIST, recursively."
11066   (if (not numbers-list)                ; do-again-test
11067       nil
11068     (cons
11069      (* (car numbers-list) (car numbers-list))
11070      (square-each (cdr numbers-list))))) ; next-step-expression
11071 @end group
11073 @group
11074 (square-each '(1 2 3))
11075     @result{} (1 4 9)
11076 @end group
11077 @end smallexample
11079 @need 1200
11080 @noindent
11081 If @code{numbers-list} is empty, do nothing.  But if it has content,
11082 construct a list combining the square of the first number in the list
11083 with the result of the recursive call.
11085 (The example follows the pattern exactly: @code{nil} is returned if
11086 the numbers' list is empty.  In practice, you would write the
11087 conditional so it carries out the action when the numbers' list is not
11088 empty.)
11090 The @code{print-elements-recursively} function (@pxref{Recursion with
11091 list, , Recursion with a List}) is another example of an @code{every}
11092 pattern, except in this case, rather than bring the results together
11093 using @code{cons}, we print each element of output.
11095 @need 1250
11096 The @code{print-elements-recursively} function looks like this:
11098 @smallexample
11099 @group
11100 (setq animals '(gazelle giraffe lion tiger))
11101 @end group
11103 @group
11104 (defun print-elements-recursively (list)
11105   "Print each element of LIST on a line of its own.
11106 Uses recursion."
11107   (if list                              ; @r{do-again-test}
11108       (progn
11109         (print (car list))              ; @r{body}
11110         (print-elements-recursively     ; @r{recursive call}
11111          (cdr list)))))                 ; @r{next-step-expression}
11113 (print-elements-recursively animals)
11114 @end group
11115 @end smallexample
11117 @need 1500
11118 The pattern for @code{print-elements-recursively} is:
11120 @itemize @bullet
11121 @item
11122 If the list be empty, do nothing.
11123 @item
11124 But if the list has at least one element,
11125     @itemize @minus
11126     @item
11127     act on the beginning of the list (the @sc{car} of the list),
11128     @item
11129     and make a recursive call on the rest (the @sc{cdr}) of the list.
11130     @end itemize
11131 @end itemize
11133 @node Accumulate, Keep, Every, Recursive Patterns
11134 @comment  node-name,  next,  previous,  up
11135 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
11136 @cindex Accumulate, type of recursive pattern
11137 @cindex Recursive pattern: accumulate
11139 Another recursive pattern is called the @code{accumulate} pattern.  In
11140 the @code{accumulate} recursive pattern, an action is performed on
11141 every element of a list and the result of that action is accumulated
11142 with the results of performing the action on the other elements.
11144 This is very like the `every' pattern using @code{cons}, except that
11145 @code{cons} is not used, but some other combiner.
11147 @need 1500
11148 The pattern is:
11150 @itemize @bullet
11151 @item
11152 If a list be empty, return zero or some other constant.
11153 @item
11154 Else, act on the beginning of the list (the @sc{car} of the list),
11155     @itemize @minus
11156     @item
11157     and combine that acted-on element, using @code{+} or
11158     some other combining function, with
11159     @item
11160     a recursive call by the function on the rest (the @sc{cdr}) of the list.
11161     @end itemize
11162 @end itemize
11164 @need 1500
11165 Here is an example:
11167 @smallexample
11168 @group
11169 (defun add-elements (numbers-list)
11170   "Add the elements of NUMBERS-LIST together."
11171   (if (not numbers-list)
11172       0
11173     (+ (car numbers-list) (add-elements (cdr numbers-list)))))
11174 @end group
11176 @group
11177 (add-elements '(1 2 3 4))
11178     @result{} 10
11179 @end group
11180 @end smallexample
11182 @xref{Files List, , Making a List of Files}, for an example of the
11183 accumulate pattern.
11185 @node Keep,  , Accumulate, Recursive Patterns
11186 @comment  node-name,  next,  previous,  up
11187 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
11188 @cindex Keep, type of recursive pattern
11189 @cindex Recursive pattern: keep
11191 A third recursive pattern is called the @code{keep} pattern.
11192 In the @code{keep} recursive pattern, each element of a list is tested;
11193 the element is acted on and the results are kept only if the element
11194 meets a criterion.
11196 Again, this is very like the `every' pattern, except the element is
11197 skipped unless it meets a criterion.
11199 @need 1500
11200 The pattern has three parts:
11202 @itemize @bullet
11203 @item
11204 If a list be empty, return @code{nil}.
11205 @item
11206 Else, if the beginning of the list (the @sc{car} of the list) passes
11207         a test
11208     @itemize @minus
11209     @item
11210     act on that element and combine it, using @code{cons} with
11211     @item
11212     a recursive call by the function on the rest (the @sc{cdr}) of the list.
11213     @end itemize
11214 @item
11215 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
11216 the test
11217     @itemize @minus
11218     @item
11219     skip on that element,
11220     @item
11221     and, recursively call the function on the rest (the @sc{cdr}) of the list.
11222     @end itemize
11223 @end itemize
11225 @need 1500
11226 Here is an example that uses @code{cond}:
11228 @smallexample
11229 @group
11230 (defun keep-three-letter-words (word-list)
11231   "Keep three letter words in WORD-LIST."
11232   (cond
11233    ;; First do-again-test: stop-condition
11234    ((not word-list) nil)
11236    ;; Second do-again-test: when to act
11237    ((eq 3 (length (symbol-name (car word-list))))
11238     ;; combine acted-on element with recursive call on shorter list
11239     (cons (car word-list) (keep-three-letter-words (cdr word-list))))
11241    ;; Third do-again-test: when to skip element;
11242    ;;   recursively call shorter list with next-step expression
11243    (t  (keep-three-letter-words (cdr word-list)))))
11244 @end group
11246 @group
11247 (keep-three-letter-words '(one two three four five six))
11248     @result{} (one two six)
11249 @end group
11250 @end smallexample
11252 It goes without saying that you need not use @code{nil} as the test for
11253 when to stop; and you can, of course, combine these patterns.
11255 @node No Deferment, No deferment solution, Recursive Patterns, Recursion
11256 @subsection Recursion without Deferments
11257 @cindex Deferment in recursion
11258 @cindex Recursion without Deferments
11260 Let's consider again what happens with the @code{triangle-recursively}
11261 function.  We will find that the intermediate calculations are
11262 deferred until all can be done.
11264 @need 800
11265 Here is the function definition:
11267 @smallexample
11268 @group
11269 (defun triangle-recursively (number)
11270   "Return the sum of the numbers 1 through NUMBER inclusive.
11271 Uses recursion."
11272   (if (= number 1)                    ; @r{do-again-test}
11273       1                               ; @r{then-part}
11274     (+ number                         ; @r{else-part}
11275        (triangle-recursively          ; @r{recursive call}
11276         (1- number)))))               ; @r{next-step-expression}
11277 @end group
11278 @end smallexample
11280 What happens when we call this function with a argument of 7?
11282 The first instance of the @code{triangle-recursively} function adds
11283 the number 7 to the value returned by a second instance of
11284 @code{triangle-recursively}, an instance that has been passed an
11285 argument of 6.  That is to say, the first calculation is:
11287 @smallexample
11288 (+ 7 (triangle-recursively 6))
11289 @end smallexample
11291 @noindent
11292 The first instance of @code{triangle-recursively}---you may want to
11293 think of it as a little robot---cannot complete its job.  It must hand
11294 off the calculation for @code{(triangle-recursively 6)} to a second
11295 instance of the program, to a second robot.  This second individual is
11296 completely different from the first one; it is, in the jargon, a
11297 `different instantiation'.  Or, put another way, it is a different
11298 robot.  It is the same model as the first; it calculates triangle
11299 numbers recursively; but it has a different serial number.
11301 And what does @code{(triangle-recursively 6)} return?  It returns the
11302 number 6 added to the value returned by evaluating
11303 @code{triangle-recursively} with an argument of 5.  Using the robot
11304 metaphor, it asks yet another robot to help it.
11306 @need 800
11307 Now the total is:
11309 @smallexample
11310 (+ 7 6 (triangle-recursively 5))
11311 @end smallexample
11313 @need 800
11314 And what happens next?
11316 @smallexample
11317 (+ 7 6 5 (triangle-recursively 4))
11318 @end smallexample
11320 Each time @code{triangle-recursively} is called, except for the last
11321 time, it creates another instance of the program---another robot---and
11322 asks it to make a calculation.
11324 @need 800
11325 Eventually, the full addition is set up and performed:
11327 @smallexample
11328 (+ 7 6 5 4 3 2 1)
11329 @end smallexample
11331 This design for the function defers the calculation of the first step
11332 until the second can be done, and defers that until the third can be
11333 done, and so on.  Each deferment means the computer must remember what
11334 is being waited on.  This is not a problem when there are only a few
11335 steps, as in this example.  But it can be a problem when there are
11336 more steps.
11338 @node No deferment solution,  , No Deferment, Recursion
11339 @subsection No Deferment Solution
11340 @cindex No deferment solution
11341 @cindex Defermentless solution
11342 @cindex Solution without deferment
11344 The solution to the problem of deferred operations is to write in a
11345 manner that does not defer operations@footnote{The phrase @dfn{tail
11346 recursive} is used to describe such a process, one that uses
11347 `constant space'.}.  This requires
11348 writing to a different pattern, often one that involves writing two
11349 function definitions, an `initialization' function and a `helper'
11350 function.
11352 The `initialization' function sets up the job; the `helper' function
11353 does the work.
11355 @need 1200
11356 Here are the two function definitions for adding up numbers.  They are
11357 so simple, I find them hard to understand.
11359 @smallexample
11360 @group
11361 (defun triangle-initialization (number)
11362   "Return the sum of the numbers 1 through NUMBER inclusive.
11363 This is the `initialization' component of a two function
11364 duo that uses recursion."
11365   (triangle-recursive-helper 0 0 number))
11366 @end group
11367 @end smallexample
11369 @smallexample
11370 @group
11371 (defun triangle-recursive-helper (sum counter number)
11372   "Return SUM, using COUNTER, through NUMBER inclusive.
11373 This is the `helper' component of a two function duo
11374 that uses recursion."
11375   (if (> counter number)
11376       sum
11377     (triangle-recursive-helper (+ sum counter)  ; @r{sum}
11378                                (1+ counter)     ; @r{counter}
11379                                number)))        ; @r{number}
11380 @end group
11381 @end smallexample
11383 @need 1250
11384 Install both function definitions by evaluating them, then call
11385 @code{triangle-initialization} with 2 rows:
11387 @smallexample
11388 @group
11389 (triangle-initialization 2)
11390     @result{} 3
11391 @end group
11392 @end smallexample
11394 The `initialization' function calls the first instance of the `helper'
11395 function with three arguments: zero, zero, and a number which is the
11396 number of rows in the triangle.
11398 The first two arguments passed to the `helper' function are
11399 initialization values.  These values are changed when
11400 @code{triangle-recursive-helper} invokes new instances.@footnote{The
11401 jargon is mildly confusing:  @code{triangle-recursive-helper} uses a
11402 process that is iterative in a procedure that is recursive.  The
11403 process is called iterative because the computer need only record the
11404 three values, @code{sum}, @code{counter}, and @code{number}; the
11405 procedure is recursive because the function `calls itself'.  On the
11406 other hand, both the process and the procedure used by
11407 @code{triangle-recursively} are called recursive.  The word
11408 `recursive' has different meanings in the two contexts.}
11410 Let's see what happens when we have a triangle that has one row.  (This
11411 triangle will have one pebble in it!)
11413 @need 1200
11414 @code{triangle-initialization} will call its helper with
11415 the arguments @w{@code{0 0 1}}.  That function will run the conditional
11416 test whether @code{(> counter number)}:
11418 @smallexample
11419 (> 0 1)
11420 @end smallexample
11422 @need 1200
11423 @noindent
11424 and find that the result is false, so it will invoke
11425 the then-part of the @code{if} clause:
11427 @smallexample
11428 @group
11429     (triangle-recursive-helper
11430      (+ sum counter)  ; @r{sum plus counter} @result{} @r{sum}
11431      (1+ counter)     ; @r{increment counter} @result{} @r{counter}
11432      number)          ; @r{number stays the same}
11433 @end group
11434 @end smallexample
11436 @need 800
11437 @noindent
11438 which will first compute:
11440 @smallexample
11441 @group
11442 (triangle-recursive-helper (+ 0 0)  ; @r{sum}
11443                            (1+ 0)   ; @r{counter}
11444                            1)       ; @r{number}
11445 @exdent which is:
11447 (triangle-recursive-helper 0 1 1)
11448 @end group
11449 @end smallexample
11451 Again, @code{(> counter number)} will be false, so again, the Lisp
11452 interpreter will evaluate @code{triangle-recursive-helper}, creating a
11453 new instance with new arguments.
11455 @need 800
11456 This new instance will be;
11458 @smallexample
11459 @group
11460     (triangle-recursive-helper
11461      (+ sum counter)  ; @r{sum plus counter} @result{} @r{sum}
11462      (1+ counter)     ; @r{increment counter} @result{} @r{counter}
11463      number)          ; @r{number stays the same}
11465 @exdent which is:
11467 (triangle-recursive-helper 1 2 1)
11468 @end group
11469 @end smallexample
11471 In this case, the @code{(> counter number)} test will be true!  So the
11472 instance will return the value of the sum, which will be 1, as
11473 expected.
11475 Now, let's pass @code{triangle-initialization} an argument
11476 of 2, to find out how many pebbles there are in a triangle with two rows.
11478 That function calls @code{(triangle-recursive-helper 0 0 2)}.
11480 @need 800
11481 In stages, the instances called will be:
11483 @smallexample
11484 @group
11485                           @r{sum counter number}
11486 (triangle-recursive-helper 0    1       2)
11488 (triangle-recursive-helper 1    2       2)
11490 (triangle-recursive-helper 3    3       2)
11491 @end group
11492 @end smallexample
11494 When the last instance is called, the @code{(> counter number)} test
11495 will be true, so the instance will return the value of @code{sum},
11496 which will be 3.
11498 This kind of pattern helps when you are writing functions that can use
11499 many resources in a computer.
11501 @need 1500
11502 @node Looping exercise,  , Recursion, Loops & Recursion
11503 @section Looping Exercise
11505 @itemize @bullet
11506 @item
11507 Write a function similar to @code{triangle} in which each row has a
11508 value which is the square of the row number.  Use a @code{while} loop.
11510 @item
11511 Write a function similar to @code{triangle} that multiplies instead of
11512 adds the values.
11514 @item
11515 Rewrite these two functions recursively.  Rewrite these functions
11516 using @code{cond}.
11518 @c comma in printed title causes problem in Info cross reference
11519 @item
11520 Write a function for Texinfo mode that creates an index entry at the
11521 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
11522 (In a Texinfo file, @samp{@@dfn} marks a definition.  This book is
11523 written in Texinfo.)
11525 Many of the functions you will need are described in two of the
11526 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
11527 Text}, and @ref{Yanking, , Yanking Text Back}.  If you use
11528 @code{forward-paragraph} to put the index entry at the beginning of
11529 the paragraph, you will have to use @w{@kbd{C-h f}}
11530 (@code{describe-function}) to find out how to make the command go
11531 backwards.
11533 For more information, see
11534 @ifinfo
11535 @ref{Indicating, , Indicating Definitions, texinfo}.
11536 @end ifinfo
11537 @ifhtml
11538 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
11539 a Texinfo manual in the current directory.  Or, if you are on the
11540 Internet, see
11541 @uref{http://www.gnu.org/manual/texinfo-4.6/html_node/Indicating.html}
11542 @end ifhtml
11543 @iftex
11544 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
11545 Documentation Format}.
11546 @end iftex
11547 @end itemize
11549 @node Regexp Search, Counting Words, Loops & Recursion, Top
11550 @comment  node-name,  next,  previous,  up
11551 @chapter Regular Expression Searches
11552 @cindex Searches, illustrating
11553 @cindex Regular expression searches
11554 @cindex Patterns, searching for
11555 @cindex Motion by sentence and paragraph
11556 @cindex Sentences, movement by
11557 @cindex Paragraphs, movement by
11559 Regular expression searches are used extensively in GNU Emacs.  The
11560 two functions, @code{forward-sentence} and @code{forward-paragraph},
11561 illustrate these searches well.  They use regular expressions to find
11562 where to move point.  The phrase `regular expression' is often written
11563 as `regexp'.
11565 Regular expression searches are described in @ref{Regexp Search, ,
11566 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
11567 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
11568 Manual}.  In writing this chapter, I am presuming that you have at
11569 least a mild acquaintance with them.  The major point to remember is
11570 that regular expressions permit you to search for patterns as well as
11571 for literal strings of characters.  For example, the code in
11572 @code{forward-sentence} searches for the pattern of possible
11573 characters that could mark the end of a sentence, and moves point to
11574 that spot.
11576 Before looking at the code for the @code{forward-sentence} function, it
11577 is worth considering what the pattern that marks the end of a sentence
11578 must be.  The pattern is discussed in the next section; following that
11579 is a description of the regular expression search function,
11580 @code{re-search-forward}.  The @code{forward-sentence} function
11581 is described in the section following.  Finally, the
11582 @code{forward-paragraph} function is described in the last section of
11583 this chapter.  @code{forward-paragraph} is a complex function that
11584 introduces several new features.
11586 @menu
11587 * sentence-end::                The regular expression for @code{sentence-end}.
11588 * re-search-forward::           Very similar to @code{search-forward}.
11589 * forward-sentence::            A straightforward example of regexp search.
11590 * forward-paragraph::           A somewhat complex example.
11591 * etags::                       How to create your own @file{TAGS} table.
11592 * Regexp Review::
11593 * re-search Exercises::
11594 @end menu
11596 @node sentence-end, re-search-forward, Regexp Search, Regexp Search
11597 @comment  node-name,  next,  previous,  up
11598 @section The Regular Expression for @code{sentence-end}
11599 @findex sentence-end
11601 The symbol @code{sentence-end} is bound to the pattern that marks the
11602 end of a sentence.  What should this regular expression be?
11604 Clearly, a sentence may be ended by a period, a question mark, or an
11605 exclamation mark.  Indeed, only clauses that end with one of those three
11606 characters should be considered the end of a sentence.  This means that
11607 the pattern should include the character set:
11609 @smallexample
11610 [.?!]
11611 @end smallexample
11613 However, we do not want @code{forward-sentence} merely to jump to a
11614 period, a question mark, or an exclamation mark, because such a character
11615 might be used in the middle of a sentence.  A period, for example, is
11616 used after abbreviations.  So other information is needed.
11618 According to convention, you type two spaces after every sentence, but
11619 only one space after a period, a question mark, or an exclamation mark in
11620 the body of a sentence.  So a period, a question mark, or an exclamation
11621 mark followed by two spaces is a good indicator of an end of sentence.
11622 However, in a file, the two spaces may instead be a tab or the end of a
11623 line.  This means that the regular expression should include these three
11624 items as alternatives.
11626 @need 800
11627 This group of alternatives will look like this:
11629 @smallexample
11630 @group
11631 \\($\\| \\|  \\)
11632        ^   ^^
11633       TAB  SPC
11634 @end group
11635 @end smallexample
11637 @noindent
11638 Here, @samp{$} indicates the end of the line, and I have pointed out
11639 where the tab and two spaces are inserted in the expression.  Both are
11640 inserted by putting the actual characters into the expression.
11642 Two backslashes, @samp{\\}, are required before the parentheses and
11643 vertical bars: the first backslash quotes the following backslash in
11644 Emacs; and the second indicates that the following character, the
11645 parenthesis or the vertical bar, is special.
11647 @need 1000
11648 Also, a sentence may be followed by one or more carriage returns, like
11649 this:
11651 @smallexample
11652 @group
11655 @end group
11656 @end smallexample
11658 @noindent
11659 Like tabs and spaces, a carriage return is inserted into a regular
11660 expression by inserting it literally.  The asterisk indicates that the
11661 @key{RET} is repeated zero or more times.
11663 But a sentence end does not consist only of a period, a question mark or
11664 an exclamation mark followed by appropriate space: a closing quotation
11665 mark or a closing brace of some kind may precede the space.  Indeed more
11666 than one such mark or brace may precede the space.  These require a
11667 expression that looks like this:
11669 @smallexample
11670 []\"')@}]*
11671 @end smallexample
11673 In this expression, the first @samp{]} is the first character in the
11674 expression; the second character is @samp{"}, which is preceded by a
11675 @samp{\} to tell Emacs the @samp{"} is @emph{not} special.  The last
11676 three characters are @samp{'}, @samp{)}, and @samp{@}}.
11678 All this suggests what the regular expression pattern for matching the
11679 end of a sentence should be; and, indeed, if we evaluate
11680 @code{sentence-end} we find that it returns the following value:
11682 @smallexample
11683 @group
11684 sentence-end
11685      @result{} "[.?!][]\"')@}]*\\($\\|     \\|  \\)[
11687 @end group
11688 @end smallexample
11690 @ignore
11692 @noindent
11693 (Note that here the @key{TAB}, two spaces, and  @key{RET} are shown
11694 literally in the pattern.)
11696 This regular expression can be decyphered as follows:
11698 @table @code
11699 @item [.?!]
11700 The first part of the pattern is the three characters, a period, a question
11701 mark and an exclamation mark, within square brackets.  The pattern must
11702 begin with one or other of these characters.
11704 @item []\"')@}]*
11705 The second part of the pattern is the group of closing braces and
11706 quotation marks, which can appear zero or more times.  These may follow
11707 the period, question mark or exclamation mark.  In a regular expression,
11708 the backslash, @samp{\}, followed by the double quotation mark,
11709 @samp{"}, indicates the class of string-quote characters.  Usually, the
11710 double quotation mark is the only character in this class.  The
11711 asterisk, @samp{*}, indicates that the items in the previous group (the
11712 group surrounded by square brackets, @samp{[]}) may be repeated zero or
11713 more times.
11715 @item \\($\\|   \\|  \\)
11716 The third part of the pattern is one or other of: either the end of a
11717 line, or two blank spaces, or a tab.  The double back-slashes are used
11718 to prevent Emacs from reading the parentheses and vertical bars as part
11719 of the search pattern; the parentheses are used to mark the group and
11720 the vertical bars are used to indicated that the patterns to either side
11721 of them are alternatives.  The dollar sign is used to indicate the end
11722 of a line and both the two spaces and the tab are each inserted as is to
11723 indicate what they are.
11725 @item [@key{RET}]*
11726 Finally, the last part of the pattern indicates that the end of the line
11727 or the whitespace following the period, question mark or exclamation
11728 mark may, but need not, be followed by one or more carriage returns.  In
11729 the pattern, the carriage return is inserted as an actual carriage
11730 return between square brackets but here it is shown as @key{RET}.
11731 @end table
11733 @end ignore
11735 @node re-search-forward, forward-sentence, sentence-end, Regexp Search
11736 @comment  node-name,  next,  previous,  up
11737 @section The @code{re-search-forward} Function
11738 @findex re-search-forward
11740 The @code{re-search-forward} function is very like the
11741 @code{search-forward} function.  (@xref{search-forward, , The
11742 @code{search-forward} Function}.)
11744 @code{re-search-forward} searches for a regular expression.  If the
11745 search is successful, it leaves point immediately after the last
11746 character in the target.  If the search is backwards, it leaves point
11747 just before the first character in the target.  You may tell
11748 @code{re-search-forward} to return @code{t} for true.  (Moving point
11749 is therefore a `side effect'.)
11751 Like @code{search-forward}, the @code{re-search-forward} function takes
11752 four arguments:
11754 @enumerate
11755 @item
11756 The first argument is the regular expression that the function searches
11757 for.  The regular expression will be a string between quotations marks.
11759 @item
11760 The optional second argument limits how far the function will search; it is a
11761 bound, which is specified as a position in the buffer.
11763 @item
11764 The optional third argument specifies how the function responds to
11765 failure: @code{nil} as the third argument causes the function to
11766 signal an error (and print a message) when the search fails; any other
11767 value causes it to return @code{nil} if the search fails and @code{t}
11768 if the search succeeds.
11770 @item
11771 The optional fourth argument is the repeat count.  A negative repeat
11772 count causes @code{re-search-forward} to search backwards.
11773 @end enumerate
11775 @need 800
11776 The template for @code{re-search-forward} looks like this:
11778 @smallexample
11779 @group
11780 (re-search-forward "@var{regular-expression}"
11781                 @var{limit-of-search}
11782                 @var{what-to-do-if-search-fails}
11783                 @var{repeat-count})
11784 @end group
11785 @end smallexample
11787 The second, third, and fourth arguments are optional.  However, if you
11788 want to pass a value to either or both of the last two arguments, you
11789 must also pass a value to all the preceding arguments.  Otherwise, the
11790 Lisp interpreter will mistake which argument you are passing the value
11793 @need 1200
11794 In the @code{forward-sentence} function, the regular expression will be
11795 the value of the variable @code{sentence-end}, namely:
11797 @smallexample
11798 @group
11799 "[.?!][]\"')@}]*\\($\\|  \\|  \\)[
11801 @end group
11802 @end smallexample
11804 @noindent
11805 The limit of the search will be the end of the paragraph (since a
11806 sentence cannot go beyond a paragraph).  If the search fails, the
11807 function will return @code{nil}; and the repeat count will be provided
11808 by the argument to the @code{forward-sentence} function.
11810 @node forward-sentence, forward-paragraph, re-search-forward, Regexp Search
11811 @comment  node-name,  next,  previous,  up
11812 @section @code{forward-sentence}
11813 @findex forward-sentence
11815 The command to move the cursor forward a sentence is a straightforward
11816 illustration of how to use regular expression searches in Emacs Lisp.
11817 Indeed, the function looks longer and more complicated than it is; this
11818 is because the function is designed to go backwards as well as forwards;
11819 and, optionally, over more than one sentence.  The function is usually
11820 bound to the key command @kbd{M-e}.
11822 @menu
11823 * Complete forward-sentence::
11824 * fwd-sentence while loops::    Two @code{while} loops.
11825 * fwd-sentence re-search::      A regular expression search.
11826 @end menu
11828 @node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
11829 @ifnottex
11830 @unnumberedsubsec Complete @code{forward-sentence} function definition
11831 @end ifnottex
11833 @need 1250
11834 Here is the code for @code{forward-sentence}:
11836 @smallexample
11837 @group
11838 (defun forward-sentence (&optional arg)
11839   "Move forward to next sentence-end.  With argument, repeat.
11840 With negative argument, move backward repeatedly to sentence-beginning.
11841 Sentence ends are identified by the value of sentence-end
11842 treated as a regular expression.  Also, every paragraph boundary
11843 terminates sentences as well."
11844 @end group
11845 @group
11846   (interactive "p")
11847   (or arg (setq arg 1))
11848   (while (< arg 0)
11849     (let ((par-beg
11850            (save-excursion (start-of-paragraph-text) (point))))
11851       (if (re-search-backward
11852            (concat sentence-end "[^ \t\n]") par-beg t)
11853           (goto-char (1- (match-end 0)))
11854         (goto-char par-beg)))
11855     (setq arg (1+ arg)))
11856   (while (> arg 0)
11857     (let ((par-end
11858            (save-excursion (end-of-paragraph-text) (point))))
11859       (if (re-search-forward sentence-end par-end t)
11860           (skip-chars-backward " \t\n")
11861         (goto-char par-end)))
11862     (setq arg (1- arg))))
11863 @end group
11864 @end smallexample
11866 The function looks long at first sight and it is best to look at its
11867 skeleton first, and then its muscle.  The way to see the skeleton is to
11868 look at the expressions that start in the left-most columns:
11870 @smallexample
11871 @group
11872 (defun forward-sentence (&optional arg)
11873   "@var{documentation}@dots{}"
11874   (interactive "p")
11875   (or arg (setq arg 1))
11876   (while (< arg 0)
11877     @var{body-of-while-loop}
11878   (while (> arg 0)
11879     @var{body-of-while-loop}
11880 @end group
11881 @end smallexample
11883 This looks much simpler!  The function definition consists of
11884 documentation, an @code{interactive} expression, an @code{or}
11885 expression, and @code{while} loops.
11887 Let's look at each of these parts in turn.
11889 We note that the documentation is thorough and understandable.
11891 The function has an @code{interactive "p"} declaration.  This means
11892 that the processed prefix argument, if any, is passed to the
11893 function as its argument.  (This will be a number.)  If the function
11894 is not passed an argument (it is optional) then the argument
11895 @code{arg} will be bound to 1.  When @code{forward-sentence} is called
11896 non-interactively without an argument, @code{arg} is bound to
11897 @code{nil}.
11899 The @code{or} expression handles the prefix argument.  What it does is
11900 either leave the value of @code{arg} as it is, but only if @code{arg}
11901 is bound to a value; or it sets the value of @code{arg} to 1, in the
11902 case when @code{arg} is bound to @code{nil}.
11904 @node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
11905 @unnumberedsubsec The @code{while} loops
11907 Two @code{while} loops follow the @code{or} expression.  The first
11908 @code{while} has a true-or-false-test that tests true if the prefix
11909 argument for @code{forward-sentence} is a negative number.  This is for
11910 going backwards.  The body of this loop is similar to the body of the
11911 second @code{while} clause, but it is not exactly the same.  We will
11912 skip this @code{while} loop and concentrate on the second @code{while}
11913 loop.
11915 @need 1500
11916 The second @code{while} loop is for moving point forward.  Its skeleton
11917 looks like this:
11919 @smallexample
11920 @group
11921 (while (> arg 0)            ; @r{true-or-false-test}
11922   (let @var{varlist}
11923     (if (@var{true-or-false-test})
11924         @var{then-part}
11925       @var{else-part}
11926   (setq arg (1- arg))))     ; @code{while} @r{loop decrementer}
11927 @end group
11928 @end smallexample
11930 The @code{while} loop is of the decrementing kind.
11931 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.)  It
11932 has a true-or-false-test that tests true so long as the counter (in
11933 this case, the variable @code{arg}) is greater than zero; and it has a
11934 decrementer that subtracts 1 from the value of the counter every time
11935 the loop repeats.
11937 If no prefix argument is given to @code{forward-sentence}, which is
11938 the most common way the command is used, this @code{while} loop will
11939 run once, since the value of @code{arg} will be 1.
11941 The body of the @code{while} loop consists of a @code{let} expression,
11942 which creates and binds a local variable, and has, as its body, an
11943 @code{if} expression.
11945 @need 1250
11946 The body of the @code{while} loop looks like this:
11948 @smallexample
11949 @group
11950 (let ((par-end
11951        (save-excursion (end-of-paragraph-text) (point))))
11952   (if (re-search-forward sentence-end par-end t)
11953       (skip-chars-backward " \t\n")
11954     (goto-char par-end)))
11955 @end group
11956 @end smallexample
11958 The @code{let} expression creates and binds the local variable
11959 @code{par-end}.  As we shall see, this local variable is designed to
11960 provide a bound or limit to the regular expression search.  If the
11961 search fails to find a proper sentence ending in the paragraph, it will
11962 stop on reaching the end of the paragraph.
11964 But first, let us examine how @code{par-end} is bound to the value of
11965 the end of the paragraph.  What happens is that the @code{let} sets the
11966 value of @code{par-end} to the value returned when the Lisp interpreter
11967 evaluates the expression
11969 @smallexample
11970 @group
11971 (save-excursion (end-of-paragraph-text) (point))
11972 @end group
11973 @end smallexample
11975 @noindent
11976 In this expression, @code{(end-of-paragraph-text)} moves point to the
11977 end of the paragraph, @code{(point)} returns the value of point, and then
11978 @code{save-excursion} restores point to its original position.  Thus,
11979 the @code{let} binds @code{par-end} to the value returned by the
11980 @code{save-excursion} expression, which is the position of the end of
11981 the paragraph.  (The @code{(end-of-paragraph-text)} function uses
11982 @code{forward-paragraph}, which we will discuss shortly.)
11984 @need 1200
11985 Emacs next evaluates the body of the @code{let}, which is an @code{if}
11986 expression that looks like this:
11988 @smallexample
11989 @group
11990 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
11991     (skip-chars-backward " \t\n")              ; @r{then-part}
11992   (goto-char par-end)))                        ; @r{else-part}
11993 @end group
11994 @end smallexample
11996 The @code{if} tests whether its first argument is true and if so,
11997 evaluates its then-part; otherwise, the Emacs Lisp interpreter
11998 evaluates the else-part.  The true-or-false-test of the @code{if}
11999 expression is the regular expression search.
12001 It may seem odd to have what looks like the `real work' of
12002 the @code{forward-sentence} function buried here, but this is a common
12003 way this kind of operation is carried out in Lisp.
12005 @node fwd-sentence re-search,  , fwd-sentence while loops, forward-sentence
12006 @unnumberedsubsec The regular expression search
12008 The @code{re-search-forward} function searches for the end of the
12009 sentence, that is, for the pattern defined by the @code{sentence-end}
12010 regular expression.  If the pattern is found---if the end of the sentence is
12011 found---then the @code{re-search-forward} function does two things:
12013 @enumerate
12014 @item
12015 The @code{re-search-forward} function carries out a side effect, which
12016 is to move point to the end of the occurrence found.
12018 @item
12019 The @code{re-search-forward} function returns a value of true.  This is
12020 the value received by the @code{if}, and means that the search was
12021 successful.
12022 @end enumerate
12024 @noindent
12025 The side effect, the movement of point, is completed before the
12026 @code{if} function is handed the value returned by the successful
12027 conclusion of the search.
12029 When the @code{if} function receives the value of true from a successful
12030 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
12031 which is the expression @code{(skip-chars-backward " \t\n")}.  This
12032 expression moves backwards over any blank spaces, tabs or carriage
12033 returns until a printed character is found and then leaves point after
12034 the character.  Since point has already been moved to the end of the
12035 pattern that marks the end of the sentence, this action leaves point
12036 right after the closing printed character of the sentence, which is
12037 usually a period.
12039 On the other hand, if the @code{re-search-forward} function fails to
12040 find a pattern marking the end of the sentence, the function returns
12041 false.  The false then causes the @code{if} to evaluate its third
12042 argument, which is @code{(goto-char par-end)}:  it moves point to the
12043 end of the paragraph.
12045 Regular expression searches are exceptionally useful and the pattern
12046 illustrated by @code{re-search-forward}, in which the search is the
12047 test of an @code{if} expression, is handy.  You will see or write code
12048 incorporating this pattern often.
12050 @node forward-paragraph, etags, forward-sentence, Regexp Search
12051 @comment  node-name,  next,  previous,  up
12052 @section @code{forward-paragraph}: a Goldmine of Functions
12053 @findex forward-paragraph
12055 The @code{forward-paragraph} function moves point forward to the end
12056 of the paragraph.  It is usually bound to @kbd{M-@}} and makes use of a
12057 number of functions that are important in themselves, including
12058 @code{let*}, @code{match-beginning}, and @code{looking-at}.
12060 The function definition for @code{forward-paragraph} is considerably
12061 longer than the function definition for @code{forward-sentence}
12062 because it works with a paragraph, each line of which may begin with a
12063 fill prefix.
12065 A fill prefix consists of a string of characters that are repeated at
12066 the beginning of each line.  For example, in Lisp code, it is a
12067 convention to start each line of a paragraph-long comment with
12068 @samp{;;; }.  In Text mode, four blank spaces make up another common
12069 fill prefix, creating an indented paragraph.  (@xref{Fill Prefix, , ,
12070 emacs, The GNU Emacs Manual}, for more information about fill
12071 prefixes.)
12073 The existence of a fill prefix means that in addition to being able to
12074 find the end of a paragraph whose lines begin on the left-most
12075 column, the @code{forward-paragraph} function must be able to find the
12076 end of a paragraph when all or many of the lines in the buffer begin
12077 with the fill prefix.
12079 Moreover, it is sometimes practical to ignore a fill prefix that
12080 exists, especially when blank lines separate paragraphs.
12081 This is an added complication.
12083 @menu
12084 * forward-paragraph in brief::  Key parts of the function definition.
12085 * fwd-para let::                The @code{let*} expression.
12086 * fwd-para while::              The forward motion @code{while} loop.
12087 * fwd-para between paragraphs::  Movement between paragraphs.
12088 * fwd-para within paragraph::   Movement within paragraphs.
12089 * fwd-para no fill prefix::     When there is no fill prefix.
12090 * fwd-para with fill prefix::   When there is a fill prefix.
12091 * fwd-para summary::            Summary of @code{forward-paragraph} code.
12092 @end menu
12094 @node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
12095 @ifnottex
12096 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
12097 @end ifnottex
12099 Rather than print all of the @code{forward-paragraph} function, we
12100 will only print parts of it.  Read without preparation, the function
12101 can be daunting!
12103 @need 800
12104 In outline, the function looks like this:
12106 @smallexample
12107 @group
12108 (defun forward-paragraph (&optional arg)
12109   "@var{documentation}@dots{}"
12110   (interactive "p")
12111   (or arg (setq arg 1))
12112   (let*
12113       @var{varlist}
12114     (while (< arg 0)        ; @r{backward-moving-code}
12115       @dots{}
12116       (setq arg (1+ arg)))
12117     (while (> arg 0)        ; @r{forward-moving-code}
12118       @dots{}
12119       (setq arg (1- arg)))))
12120 @end group
12121 @end smallexample
12123 The first parts of the function are routine: the function's argument
12124 list consists of one optional argument.  Documentation follows.
12126 The lower case @samp{p} in the @code{interactive} declaration means
12127 that the processed prefix argument, if any, is passed to the function.
12128 This will be a number, and is the repeat count of how many paragraphs
12129 point will move.  The @code{or} expression in the next line handles
12130 the common case when no argument is passed to the function, which occurs
12131 if the function is called from other code rather than interactively.
12132 This case was described earlier.  (@xref{forward-sentence, The
12133 @code{forward-sentence} function}.)  Now we reach the end of the
12134 familiar part of this function.
12136 @node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph
12137 @unnumberedsubsec The @code{let*} expression
12139 The next line of the @code{forward-paragraph} function begins a
12140 @code{let*} expression.  This is a different kind of expression than
12141 we have seen so far.  The symbol is @code{let*} not @code{let}.
12143 The @code{let*} special form is like @code{let} except that Emacs sets
12144 each variable in sequence, one after another, and variables in the
12145 latter part of the varlist can make use of the values to which Emacs
12146 set variables in the earlier part of the varlist.
12148 In the @code{let*} expression in this function, Emacs binds two
12149 variables: @code{fill-prefix-regexp} and @code{paragraph-separate}.
12150 The value to which @code{paragraph-separate} is bound depends on the
12151 value of @code{fill-prefix-regexp}.
12153 @need 1200
12154 Let's look at each in turn.  The symbol @code{fill-prefix-regexp} is
12155 set to the value returned by evaluating the following list:
12157 @smallexample
12158 @group
12159 (and fill-prefix
12160      (not (equal fill-prefix ""))
12161      (not paragraph-ignore-fill-prefix)
12162      (regexp-quote fill-prefix))
12163 @end group
12164 @end smallexample
12166 @noindent
12167 This is an expression whose first element is the @code{and} special form.
12169 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
12170 function}), the @code{and} special form evaluates each of its
12171 arguments until one of the arguments returns a value of @code{nil}, in
12172 which case the @code{and} expression returns @code{nil}; however, if
12173 none of the arguments returns a value of @code{nil}, the value
12174 resulting from evaluating the last argument is returned.  (Since such
12175 a value is not @code{nil}, it is considered true in Lisp.)  In other
12176 words, an @code{and} expression returns a true value only if all its
12177 arguments are true.
12178 @findex and
12180 In this case, the variable @code{fill-prefix-regexp} is bound to a
12181 non-@code{nil} value only if the following four expressions produce a
12182 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
12183 @code{fill-prefix-regexp} is bound to @code{nil}.
12185 @table @code
12186 @item fill-prefix
12187 When this variable is evaluated, the value of the fill prefix, if any,
12188 is returned.  If there is no fill prefix, this variable returns
12189 @code{nil}.
12191 @item (not (equal fill-prefix "")
12192 This expression checks whether an existing fill prefix is an empty
12193 string, that is, a string with no characters in it.  An empty string is
12194 not a useful fill prefix.
12196 @item (not paragraph-ignore-fill-prefix)
12197 This expression returns @code{nil} if the variable
12198 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
12199 true value such as @code{t}.
12201 @item (regexp-quote fill-prefix)
12202 This is the last argument to the @code{and} special form.  If all the
12203 arguments to the @code{and} are true, the value resulting from
12204 evaluating this expression will be returned by the @code{and} expression
12205 and bound to the variable @code{fill-prefix-regexp},
12206 @end table
12208 @findex regexp-quote
12209 @noindent
12210 The result of evaluating this @code{and} expression successfully is that
12211 @code{fill-prefix-regexp} will be bound to the value of
12212 @code{fill-prefix} as modified by the @code{regexp-quote} function.
12213 What @code{regexp-quote} does is read a string and return a regular
12214 expression that will exactly match the string and match nothing else.
12215 This means that @code{fill-prefix-regexp} will be set to a value that
12216 will exactly match the fill prefix if the fill prefix exists.
12217 Otherwise, the variable will be set to @code{nil}.
12219 The second local variable in the @code{let*} expression is
12220 @code{paragraph-separate}.  It is bound to the value returned by
12221 evaluating the expression:
12223 @smallexample
12224 @group
12225 (if fill-prefix-regexp
12226     (concat paragraph-separate
12227             "\\|^" fill-prefix-regexp "[ \t]*$")
12228   paragraph-separate)))
12229 @end group
12230 @end smallexample
12232 This expression shows why @code{let*} rather than @code{let} was used.
12233 The true-or-false-test for the @code{if} depends on whether the variable
12234 @code{fill-prefix-regexp} evaluates to @code{nil} or some other value.
12236 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
12237 the else-part of the @code{if} expression and binds
12238 @code{paragraph-separate} to its local value.
12239 (@code{paragraph-separate} is a regular expression that matches what
12240 separates paragraphs.)
12242 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
12243 the then-part of the @code{if} expression and binds
12244 @code{paragraph-separate} to a regular expression that includes the
12245 @code{fill-prefix-regexp} as part of the pattern.
12247 Specifically, @code{paragraph-separate} is set to the original value
12248 of the paragraph separate regular expression concatenated with an
12249 alternative expression that consists of the @code{fill-prefix-regexp}
12250 followed by a blank line.  The @samp{^} indicates that the
12251 @code{fill-prefix-regexp} must begin a line, and the optional
12252 whitespace to the end of the line is defined by @w{@code{"[ \t]*$"}}.)
12253 The @samp{\\|} defines this portion of the regexp as an alternative to
12254 @code{paragraph-separate}.
12256 Now we get into the body of the @code{let*}.  The first part of the body
12257 of the @code{let*} deals with the case when the function is given a
12258 negative argument and is therefore moving backwards.  We will skip this
12259 section.
12261 @node fwd-para while, fwd-para between paragraphs, fwd-para let, forward-paragraph
12262 @unnumberedsubsec The forward motion @code{while} loop
12264 The second part of the body of the @code{let*} deals with forward
12265 motion.  It is a @code{while} loop that repeats itself so long as the
12266 value of @code{arg} is greater than zero.  In the most common use of
12267 the function, the value of the argument is 1, so the body of the
12268 @code{while} loop is evaluated exactly once, and the cursor moves
12269 forward one paragraph.
12271 This part handles three situations: when point is between paragraphs,
12272 when point is within a paragraph and there is a fill prefix, and
12273 when point is within a paragraph and there is no fill prefix.
12275 @need 800
12276 The @code{while} loop looks like this:
12278 @smallexample
12279 @group
12280 (while (> arg 0)
12281   (beginning-of-line)
12283   ;; @r{between paragraphs}
12284   (while (prog1 (and (not (eobp))
12285                      (looking-at paragraph-separate))
12286            (forward-line 1)))
12287 @end group
12289 @group
12290   ;; @r{within paragraphs, with a fill prefix}
12291   (if fill-prefix-regexp
12292       ;; @r{There is a fill prefix; it overrides paragraph-start.}
12293       (while (and (not (eobp))
12294                   (not (looking-at paragraph-separate))
12295                   (looking-at fill-prefix-regexp))
12296         (forward-line 1))
12297 @end group
12299 @group
12300     ;; @r{within paragraphs, no fill prefix}
12301     (if (re-search-forward paragraph-start nil t)
12302         (goto-char (match-beginning 0))
12303       (goto-char (point-max))))
12305   (setq arg (1- arg)))
12306 @end group
12307 @end smallexample
12309 We can see immediately that this is a decrementing counter @code{while}
12310 loop, using the expression @code{(setq arg (1- arg))} as the decrementer.
12312 @need 800
12313 The body of the loop consists of three expressions:
12315 @smallexample
12316 @group
12317 ;; @r{between paragraphs}
12318 (beginning-of-line)
12319 (while
12320     @var{body-of-while})
12321 @end group
12323 @group
12324 ;; @r{within paragraphs, with fill prefix}
12325 (if @var{true-or-false-test}
12326     @var{then-part}
12327 @end group
12329 @group
12330 ;; @r{within paragraphs, no fill prefix}
12331   @var{else-part}
12332 @end group
12333 @end smallexample
12335 @noindent
12336 When the Emacs Lisp interpreter evaluates the body of the
12337 @code{while} loop, the first thing it does is evaluate the
12338 @code{(beginning-of-line)} expression and move point to the beginning
12339 of the line.  Then there is an inner @code{while} loop.  This
12340 @code{while} loop is designed to move the cursor out of the blank
12341 space between paragraphs, if it should happen to be there.  Finally,
12342 there is an @code{if} expression that actually moves point to the end
12343 of the paragraph.
12345 @node fwd-para between paragraphs, fwd-para within paragraph, fwd-para while, forward-paragraph
12346 @unnumberedsubsec Between paragraphs
12348 First, let us look at the inner @code{while} loop.  This loop handles
12349 the case when point is between paragraphs; it uses three functions
12350 that are new to us: @code{prog1}, @code{eobp} and @code{looking-at}.
12351 @findex prog1
12352 @findex eobp
12353 @findex looking-at
12355 @itemize @bullet
12356 @item
12357 @code{prog1} is similar to the @code{progn} special form,
12358 except that @code{prog1} evaluates its arguments in sequence and then
12359 returns the value of its first argument as the value of the whole
12360 expression.  (@code{progn} returns the value of its last argument as the
12361 value of the expression.) The second and subsequent arguments to
12362 @code{prog1} are evaluated only for their side effects.
12364 @item
12365 @code{eobp} is an abbreviation of @samp{End Of Buffer P} and is a
12366 function that returns true if point is at the end of the buffer.
12368 @item
12369 @code{looking-at} is a function that returns true if the text following
12370 point matches the regular expression passed @code{looking-at} as its
12371 argument.
12372 @end itemize
12374 @need 800
12375 The @code{while} loop we are studying looks like this:
12377 @smallexample
12378 @group
12379 (while (prog1 (and (not (eobp))
12380                    (looking-at paragraph-separate))
12381               (forward-line 1)))
12382 @end group
12383 @end smallexample
12385 @need 1200
12386 @noindent
12387 This is a @code{while} loop with no body!  The true-or-false-test of the
12388 loop is the expression:
12390 @smallexample
12391 @group
12392 (prog1 (and (not (eobp))
12393             (looking-at paragraph-separate))
12394        (forward-line 1))
12395 @end group
12396 @end smallexample
12398 @noindent
12399 The first argument to the @code{prog1} is the @code{and} expression.  It
12400 has within in it a test of whether point is at the end of the buffer and
12401 also a test of whether the pattern following point matches the regular
12402 expression for separating paragraphs.
12404 If the cursor is not at the end of the buffer and if the characters
12405 following the cursor mark the separation between two paragraphs, then
12406 the @code{and} expression is true.  After evaluating the @code{and}
12407 expression, the Lisp interpreter evaluates the second argument to
12408 @code{prog1}, which is @code{forward-line}.  This moves point forward
12409 one line.  The value returned by the @code{prog1} however, is the
12410 value of its first argument, so the @code{while} loop continues so
12411 long as point is not at the end of the buffer and is between
12412 paragraphs.  When, finally, point is moved to a paragraph, the
12413 @code{and} expression tests false.  Note however, that the
12414 @code{forward-line} command is carried out anyhow.  This means that
12415 when point is moved from between paragraphs to a paragraph, it is left
12416 at the beginning of the second line of the paragraph.
12418 @node fwd-para within paragraph, fwd-para no fill prefix, fwd-para between paragraphs, forward-paragraph
12419 @unnumberedsubsec Within paragraphs
12421 The next expression in the outer @code{while} loop is an @code{if}
12422 expression.  The Lisp interpreter evaluates the then-part of the
12423 @code{if} when the @code{fill-prefix-regexp} variable has a value other
12424 than @code{nil}, and it evaluates the else-part when the value of
12425 @code{if fill-prefix-regexp} is @code{nil}, that is, when there is no
12426 fill prefix.
12428 @node fwd-para no fill prefix, fwd-para with fill prefix, fwd-para within paragraph, forward-paragraph
12429 @unnumberedsubsec No fill prefix
12431 It is simplest to look at the code for the case when there is no fill
12432 prefix first.  This code consists of yet another inner @code{if}
12433 expression, and reads as follows:
12435 @smallexample
12436 @group
12437 (if (re-search-forward paragraph-start nil t)
12438     (goto-char (match-beginning 0))
12439   (goto-char (point-max)))
12440 @end group
12441 @end smallexample
12443 @noindent
12444 This expression actually does the work that most people think of as
12445 the primary purpose of the @code{forward-paragraph} command: it causes
12446 a regular expression search to occur that searches forward to the
12447 start of the next paragraph and if it is found, moves point there; but
12448 if the start of another paragraph if not found, it moves point to the
12449 end of the accessible region of the buffer.
12451 The only unfamiliar part of this is the use of @code{match-beginning}.
12452 This is another function that is new to us.  The
12453 @code{match-beginning} function returns a number specifying the
12454 location of the start of the text that was matched by the last regular
12455 expression search.
12457 The @code{match-beginning} function is used here because of a
12458 characteristic of a forward search: a successful forward search,
12459 regardless of whether it is a plain search or a regular expression
12460 search, will move point to the end of the text that is found.  In this
12461 case, a successful search will move point to the end of the pattern for
12462 @code{paragraph-start}, which will be the beginning of the next
12463 paragraph rather than the end of the current one.
12465 However, we want to put point at the end of the current paragraph, not at
12466 the beginning of the next one.  The two positions may be different,
12467 because there may be several blank lines between paragraphs.
12469 @findex match-beginning
12470 When given an argument of 0, @code{match-beginning} returns the position
12471 that is the start of the text that the most recent regular
12472 expression search matched.  In this case, the most recent regular
12473 expression search is the one looking for @code{paragraph-start}, so
12474 @code{match-beginning} returns the beginning position of the pattern,
12475 rather than the end of the pattern.  The beginning position is the end
12476 of the paragraph.
12478 (Incidentally, when passed a positive number as an argument, the
12479 @code{match-beginning} function will place point at that parenthesized
12480 expression in the last regular expression.  It is a useful function.)
12482 @node fwd-para with fill prefix, fwd-para summary, fwd-para no fill prefix, forward-paragraph
12483 @unnumberedsubsec With a fill prefix
12485 The inner @code{if} expression just discussed is the else-part of an enclosing
12486 @code{if} expression which tests whether there is a fill prefix.  If
12487 there is a fill prefix, the then-part of this @code{if} is evaluated.
12488 It looks like this:
12490 @smallexample
12491 @group
12492 (while (and (not (eobp))
12493             (not (looking-at paragraph-separate))
12494             (looking-at fill-prefix-regexp))
12495   (forward-line 1))
12496 @end group
12497 @end smallexample
12499 @noindent
12500 What this expression does is move point forward line by line so long
12501 as three conditions are true:
12503 @enumerate
12504 @item
12505 Point is not at the end of the buffer.
12507 @item
12508 The text following point does not separate paragraphs.
12510 @item
12511 The pattern following point is the fill prefix regular expression.
12512 @end enumerate
12514 The last condition may be puzzling, until you remember that point was
12515 moved to the beginning of the line early in the @code{forward-paragraph}
12516 function.  This means that if the text has a fill prefix, the
12517 @code{looking-at} function will see it.
12519 @node fwd-para summary,  , fwd-para with fill prefix, forward-paragraph
12520 @unnumberedsubsec Summary
12522 In summary, when moving forward, the @code{forward-paragraph} function
12523 does the following:
12525 @itemize @bullet
12526 @item
12527 Move point to the beginning of the line.
12529 @item
12530 Skip over lines between paragraphs.
12532 @item
12533 Check whether there is a fill prefix, and if there is:
12535 @itemize ---
12537 @item
12538 Go forward line by line so long as the line is not a paragraph
12539 separating line.
12540 @end itemize
12542 @item
12543 But if there is no fill prefix,
12545 @itemize ---
12547 @item
12548 Search for the next paragraph start pattern.
12550 @item
12551 Go to the beginning of the paragraph start pattern, which will be the
12552 end of the previous paragraph.
12554 @item
12555 Or else go to the end of the accessible portion of the buffer.
12556 @end itemize
12557 @end itemize
12559 @need 1200
12560 For review, here is the code we have just been discussing, formatted
12561 for clarity:
12563 @smallexample
12564 @group
12565 (interactive "p")
12566 (or arg (setq arg 1))
12567 (let* (
12568        (fill-prefix-regexp
12569         (and fill-prefix (not (equal fill-prefix ""))
12570              (not paragraph-ignore-fill-prefix)
12571              (regexp-quote fill-prefix)))
12572 @end group
12574 @group
12575        (paragraph-separate
12576         (if fill-prefix-regexp
12577             (concat paragraph-separate
12578                     "\\|^"
12579                     fill-prefix-regexp
12580                     "[ \t]*$")
12581           paragraph-separate)))
12583   @var{omitted-backward-moving-code} @dots{}
12584 @end group
12586 @group
12587   (while (> arg 0)                ; @r{forward-moving-code}
12588     (beginning-of-line)
12590     (while (prog1 (and (not (eobp))
12591                        (looking-at paragraph-separate))
12592              (forward-line 1)))
12593 @end group
12595 @group
12596     (if fill-prefix-regexp
12597         (while (and (not (eobp))  ; @r{then-part}
12598                     (not (looking-at paragraph-separate))
12599                     (looking-at fill-prefix-regexp))
12600           (forward-line 1))
12601 @end group
12602 @group
12603                                   ; @r{else-part: the inner-if}
12604       (if (re-search-forward paragraph-start nil t)
12605           (goto-char (match-beginning 0))
12606         (goto-char (point-max))))
12608     (setq arg (1- arg)))))        ; @r{decrementer}
12609 @end group
12610 @end smallexample
12612 The full definition for the @code{forward-paragraph} function not only
12613 includes this code for going forwards, but also code for going backwards.
12615 If you are reading this inside of GNU Emacs and you want to see the
12616 whole function, you can type @kbd{C-h f} (@code{describe-function})
12617 and the name of the function.  This gives you the function
12618 documentation and the name of the library containing the function's
12619 source.  Place point over the name of the library and press the RET
12620 key; you will be taken directly to the source.  (Be sure to install
12621 your sources!  Without them, you are like a person who tries to drive
12622 a car with his eyes shut!)
12624 @c !!! again, 21.0.100 tags table location in this paragraph
12625 Or -- a good habit to get into -- you can type @kbd{M-.}
12626 (@code{find-tag}) and the name of the function when prompted for it.
12627 This will take you directly to the source.  If the @code{find-tag}
12628 function first asks you for the name of a @file{TAGS} table, give it
12629 the name of the @file{TAGS} file such as
12630 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS}.  (The exact path to your
12631 @file{TAGS} file depends on how your copy of Emacs was installed.)
12633 You can also create your own @file{TAGS} file for directories that
12634 lack one.
12635 @ifnottex
12636 @xref{etags, , Create Your Own @file{TAGS} File}.
12637 @end ifnottex
12639 @node etags, Regexp Review, forward-paragraph, Regexp Search
12640 @section Create Your Own @file{TAGS} File
12641 @findex etags
12642 @cindex @file{TAGS} file, create own
12644 The @kbd{M-.} (@code{find-tag}) command takes you directly to the
12645 source for a function, variable, node, or other source.  The function
12646 depends on tags tables to tell it where to go.
12648 You often need to build and install tags tables yourself.  They are
12649 not built automatically.  A tags table is called a @file{TAGS} file;
12650 the name is in upper case letters.
12652 You can create a @file{TAGS} file by calling the @code{etags} program
12653 that comes as a part of the Emacs distribution.  Usually, @code{etags}
12654 is compiled and installed when Emacs is built.  (@code{etags} is not
12655 an Emacs Lisp function or a part of Emacs; it is a C program.)
12657 @need 1250
12658 To create a @file{TAGS} file, first switch to the directory in which
12659 you want to create the file.  In Emacs you can do this with the
12660 @kbd{M-x cd} command, or by visiting a file in the directory, or by
12661 listing the directory with @kbd{C-x d} (@code{dired}).  Then run the
12662 compile command, with @w{@code{etags *.el}} as the command to execute
12664 @smallexample
12665 M-x compile RET etags *.el RET
12666 @end smallexample
12668 @noindent
12669 to create a @file{TAGS} file.
12671 For example, if you have a large number of files in your
12672 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
12673 of which I load 12---you can create a @file{TAGS} file for the Emacs
12674 Lisp files in that directory.
12676 @need 1250
12677 The @code{etags} program takes all the
12678 usual shell `wildcards'.  For example, if you have two directories for
12679 which you want a single @file{TAGS file}, type
12680 @w{@code{etags *.el ../elisp/*.el}},
12681 where @file{../elisp/} is the second directory:
12683 @smallexample
12684 M-x compile RET etags *.el ../elisp/*.el RET
12685 @end smallexample
12687 @need 1250
12688 Type
12690 @smallexample
12691 M-x compile RET etags --help RET
12692 @end smallexample
12694 @noindent
12695 to see a list of the options accepted by @code{etags} as well as a
12696 list of supported languages.
12698 The @code{etags} program handles more than 20 languages, including
12699 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, Java, LaTeX,
12700 Pascal, Perl, Python, Texinfo, makefiles, and most assemblers.  The
12701 program has no switches for specifying the language; it recognizes the
12702 language in an input file according to its file name and contents.
12704 @file{etags} is very helpful when you are writing code yourself and
12705 want to refer back to functions you have already written.  Just run
12706 @code{etags} again at intervals as you write new functions, so they
12707 become part of the @file{TAGS} file.
12709 If you think an appropriate @file{TAGS} file already exists for what
12710 you want, but do not know where it is, you can use the @code{locate}
12711 program to attempt to find it.
12713 Type @w{@kbd{M-x locate RET TAGS RET}} and Emacs will list for you the
12714 full path names of all your @file{TAGS} files.  On my system, this
12715 command lists 34 @file{TAGS} files.  On the other hand, a `plain
12716 vanilla' system I recently installed did not contain any @file{TAGS}
12717 files.
12719 If the tags table you want has been created, you can use the @code{M-x
12720 visit-tags-table} command to specify it.  Otherwise, you will need to
12721 create the tag table yourself and then use @code{M-x
12722 visit-tags-table}.
12724 @subsubheading Building Tags in the Emacs sources
12725 @cindex Building Tags in the Emacs sources
12726 @cindex Tags in the Emacs sources
12727 @findex make tags
12729 The GNU Emacs sources come with a @file{Makefile} that contains a
12730 sophisticated @code{etags} command that creates, collects, and merges
12731 tags tables from all over the Emacs sources and puts the information
12732 into one @file{TAGS} file in the @file{src/} directory below the top
12733 level of your Emacs source directory.
12735 @need 1250
12736 To build this @file{TAGS} file, go to the top level of your Emacs
12737 source directory and run the compile command @code{make tags}:
12739 @smallexample
12740 M-x compile RET make tags RET
12741 @end smallexample
12743 @noindent
12744 (The @code{make tags} command works well with the GNU Emacs sources,
12745 as well as with some other source packages.)
12747 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
12748 Manual}.
12750 @node Regexp Review, re-search Exercises, etags, Regexp Search
12751 @comment  node-name,  next,  previous,  up
12752 @section Review
12754 Here is a brief summary of some recently introduced functions.
12756 @table @code
12757 @item while
12758 Repeatedly evaluate the body of the expression so long as the first
12759 element of the body tests true.  Then return @code{nil}.  (The
12760 expression is evaluated only for its side effects.)
12762 @need 1250
12763 For example:
12765 @smallexample
12766 @group
12767 (let ((foo 2))
12768   (while (> foo 0)
12769     (insert (format "foo is %d.\n" foo))
12770     (setq foo (1- foo))))
12772      @result{}      foo is 2.
12773              foo is 1.
12774              nil
12775 @end group
12776 @end smallexample
12777 @noindent
12778 (The @code{insert} function inserts its arguments at point; the
12779 @code{format} function returns a string formatted from its arguments
12780 the way @code{message} formats its arguments; @code{\n} produces a new
12781 line.)
12783 @item re-search-forward
12784 Search for a pattern, and if the pattern is found, move point to rest
12785 just after it.
12787 @noindent
12788 Takes four arguments, like @code{search-forward}:
12790 @enumerate
12791 @item
12792 A regular expression that specifies the pattern to search for.
12794 @item
12795 Optionally, the limit of the search.
12797 @item
12798 Optionally, what to do if the search fails, return @code{nil} or an
12799 error message.
12801 @item
12802 Optionally, how many times to repeat the search; if negative, the
12803 search goes backwards.
12804 @end enumerate
12806 @item let*
12807 Bind some variables locally to particular values,
12808 and then evaluate the remaining arguments, returning the value of the
12809 last one.  While binding the local variables, use the local values of
12810 variables bound earlier, if any.
12812 @need 1250
12813 For example:
12815 @smallexample
12816 @group
12817 (let* ((foo 7)
12818       (bar (* 3 foo)))
12819   (message "`bar' is %d." bar))
12820      @result{} `bar' is 21.
12821 @end group
12822 @end smallexample
12824 @item match-beginning
12825 Return the position of the start of the text found by the last regular
12826 expression search.
12828 @item looking-at
12829 Return @code{t} for true if the text after point matches the argument,
12830 which should be a regular expression.
12832 @item eobp
12833 Return @code{t} for true if point is at the end of the accessible part
12834 of a buffer.  The end of the accessible part is the end of the buffer
12835 if the buffer is not narrowed; it is the end of the narrowed part if
12836 the buffer is narrowed.
12838 @item prog1
12839 Evaluate each argument in sequence and then return the value of the
12840 @emph{first}.
12842 @need 1250
12843 For example:
12845 @smallexample
12846 @group
12847 (prog1 1 2 3 4)
12848      @result{} 1
12849 @end group
12850 @end smallexample
12851 @end table
12853 @need 1500
12854 @node re-search Exercises,  , Regexp Review, Regexp Search
12855 @section Exercises with @code{re-search-forward}
12857 @itemize @bullet
12858 @item
12859 Write a function to search for a regular expression that matches two
12860 or more blank lines in sequence.
12862 @item
12863 Write a function to search for duplicated words, such as `the the'.
12864 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
12865 Manual}, for information on how to write a regexp (a regular
12866 expression) to match a string that is composed of two identical
12867 halves.  You can devise several regexps; some are better than others.
12868 The function I use is described in an appendix, along with several
12869 regexps.  @xref{the-the, , @code{the-the} Duplicated Words Function}.
12870 @end itemize
12872 @node Counting Words, Words in a defun, Regexp Search, Top
12873 @chapter Counting: Repetition and Regexps
12874 @cindex Repetition for word counting
12875 @cindex Regular expressions for word counting
12877 Repetition and regular expression searches are powerful tools that you
12878 often use when you write code in Emacs Lisp.  This chapter illustrates
12879 the use of regular expression searches through the construction of
12880 word count commands using @code{while} loops and recursion.
12882 @menu
12883 * Why Count Words::
12884 * count-words-region::          Use a regexp, but find a problem.
12885 * recursive-count-words::       Start with case of no words in region.
12886 * Counting Exercise::
12887 @end menu
12889 @node Why Count Words, count-words-region, Counting Words, Counting Words
12890 @ifnottex
12891 @unnumberedsec Counting words
12892 @end ifnottex
12894 The standard Emacs distribution contains a function for counting the
12895 number of lines within a region.  However, there is no corresponding
12896 function for counting words.
12898 Certain types of writing ask you to count words.  Thus, if you write
12899 an essay, you may be limited to 800 words; if you write a novel, you
12900 may discipline yourself to write 1000 words a day.  It seems odd to me
12901 that Emacs lacks a word count command.  Perhaps people use Emacs
12902 mostly for code or types of documentation that do not require word
12903 counts; or perhaps they restrict themselves to the operating system
12904 word count command, @code{wc}.  Alternatively, people may follow
12905 the publishers' convention and compute a word count by dividing the
12906 number of characters in a document by five.  In any event, here are
12907 commands to count words.
12909 @node count-words-region, recursive-count-words, Why Count Words, Counting Words
12910 @comment  node-name,  next,  previous,  up
12911 @section The @code{count-words-region} Function
12912 @findex count-words-region
12914 A word count command could count words in a line, paragraph, region,
12915 or buffer.  What should the command cover?  You could design the
12916 command to count the number of words in a complete buffer.  However,
12917 the Emacs tradition encourages flexibility---you may want to count
12918 words in just a section, rather than all of a buffer.  So it makes
12919 more sense to design the command to count the number of words in a
12920 region.  Once you have a @code{count-words-region} command, you can,
12921 if you wish, count words in a whole buffer by marking it with @kbd{C-x
12922 h} (@code{mark-whole-buffer}).
12924 Clearly, counting words is a repetitive act: starting from the
12925 beginning of the region, you count the first word, then the second
12926 word, then the third word, and so on, until you reach the end of the
12927 region.  This means that word counting is ideally suited to recursion
12928 or to a @code{while} loop.
12930 @menu
12931 * Design count-words-region::   The definition using a @code{while} loop.
12932 * Whitespace Bug::              The Whitespace Bug in @code{count-words-region}.
12933 @end menu
12935 @node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
12936 @ifnottex
12937 @unnumberedsubsec Designing @code{count-words-region}
12938 @end ifnottex
12940 First, we will implement the word count command with a @code{while}
12941 loop, then with recursion.  The command will, of course, be
12942 interactive.
12944 @need 800
12945 The template for an interactive function definition is, as always:
12947 @smallexample
12948 @group
12949 (defun @var{name-of-function} (@var{argument-list})
12950   "@var{documentation}@dots{}"
12951   (@var{interactive-expression}@dots{})
12952   @var{body}@dots{})
12953 @end group
12954 @end smallexample
12956 What we need to do is fill in the slots.
12958 The name of the function should be self-explanatory and similar to the
12959 existing @code{count-lines-region} name.  This makes the name easier
12960 to remember.  @code{count-words-region} is a good choice.
12962 The function counts words within a region.  This means that the
12963 argument list must contain symbols that are bound to the two
12964 positions, the beginning and end of the region.  These two positions
12965 can be called @samp{beginning} and @samp{end} respectively.  The first
12966 line of the documentation should be a single sentence, since that is
12967 all that is printed as documentation by a command such as
12968 @code{apropos}.  The interactive expression will be of the form
12969 @samp{(interactive "r")}, since that will cause Emacs to pass the
12970 beginning and end of the region to the function's argument list.  All
12971 this is routine.
12973 The body of the function needs to be written to do three tasks:
12974 first, to set up conditions under which the @code{while} loop can
12975 count words, second, to run the @code{while} loop, and third, to send
12976 a message to the user.
12978 When a user calls @code{count-words-region}, point may be at the
12979 beginning or the end of the region.  However, the counting process
12980 must start at the beginning of the region.  This means we will want
12981 to put point there if it is not already there.  Executing
12982 @code{(goto-char beginning)} ensures this.  Of course, we will want to
12983 return point to its expected position when the function finishes its
12984 work.  For this reason, the body must be enclosed in a
12985 @code{save-excursion} expression.
12987 The central part of the body of the function consists of a
12988 @code{while} loop in which one expression jumps point forward word by
12989 word, and another expression counts those jumps.  The true-or-false-test
12990 of the @code{while} loop should test true so long as point should jump
12991 forward, and false when point is at the end of the region.
12993 We could use @code{(forward-word 1)} as the expression for moving point
12994 forward word by word, but it is easier to see what Emacs identifies as a
12995 `word' if we use a regular expression search.
12997 A regular expression search that finds the pattern for which it is
12998 searching leaves point after the last character matched.  This means
12999 that a succession of successful word searches will move point forward
13000 word by word.
13002 As a practical matter, we want the regular expression search to jump
13003 over whitespace and punctuation between words as well as over the
13004 words themselves.  A regexp that refuses to jump over interword
13005 whitespace would never jump more than one word!  This means that
13006 the regexp should include the whitespace and punctuation that follows
13007 a word, if any, as well as the word itself.  (A word may end a buffer
13008 and not have any following whitespace or punctuation, so that part of
13009 the regexp must be optional.)
13011 Thus, what we want for the regexp is a pattern defining one or more
13012 word constituent characters followed, optionally, by one or more
13013 characters that are not word constituents.  The regular expression for
13014 this is:
13016 @smallexample
13017 \w+\W*
13018 @end smallexample
13020 @noindent
13021 The buffer's syntax table determines which characters are and are not
13022 word constituents.  (@xref{Syntax, , What Constitutes a Word or
13023 Symbol?}, for more about syntax.  Also, see @ref{Syntax, Syntax, The
13024 Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, ,
13025 Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
13027 @need 800
13028 The search expression looks like this:
13030 @smallexample
13031 (re-search-forward "\\w+\\W*")
13032 @end smallexample
13034 @noindent
13035 (Note that paired backslashes precede the @samp{w} and @samp{W}.  A
13036 single backslash has special meaning to the Emacs Lisp interpreter.  It
13037 indicates that the following character is interpreted differently than
13038 usual.  For example, the two characters, @samp{\n}, stand for
13039 @samp{newline}, rather than for a backslash followed by @samp{n}.  Two
13040 backslashes in a row stand for an ordinary, `unspecial' backslash.)
13042 We need a counter to count how many words there are; this variable
13043 must first be set to 0 and then incremented each time Emacs goes
13044 around the @code{while} loop.  The incrementing expression is simply:
13046 @smallexample
13047 (setq count (1+ count))
13048 @end smallexample
13050 Finally, we want to tell the user how many words there are in the
13051 region.  The @code{message} function is intended for presenting this
13052 kind of information to the user.  The message has to be phrased so
13053 that it reads properly regardless of how many words there are in the
13054 region: we don't want to say that ``there are 1 words in the region''.
13055 The conflict between singular and plural is ungrammatical.  We can
13056 solve this problem by using a conditional expression that evaluates
13057 different messages depending on the number of words in the region.
13058 There are three possibilities: no words in the region, one word in the
13059 region, and more than one word.  This means that the @code{cond}
13060 special form is appropriate.
13062 @need 1500
13063 All this leads to the following function definition:
13065 @smallexample
13066 @group
13067 ;;; @r{First version; has bugs!}
13068 (defun count-words-region (beginning end)
13069   "Print number of words in the region.
13070 Words are defined as at least one word-constituent
13071 character followed by at least one character that
13072 is not a word-constituent.  The buffer's syntax
13073 table determines which characters these are."
13074   (interactive "r")
13075   (message "Counting words in region ... ")
13076 @end group
13078 @group
13079 ;;; @r{1. Set up appropriate conditions.}
13080   (save-excursion
13081     (goto-char beginning)
13082     (let ((count 0))
13083 @end group
13085 @group
13086 ;;; @r{2. Run the} while @r{loop.}
13087       (while (< (point) end)
13088         (re-search-forward "\\w+\\W*")
13089         (setq count (1+ count)))
13090 @end group
13092 @group
13093 ;;; @r{3. Send a message to the user.}
13094       (cond ((zerop count)
13095              (message
13096               "The region does NOT have any words."))
13097             ((= 1 count)
13098              (message
13099               "The region has 1 word."))
13100             (t
13101              (message
13102               "The region has %d words." count))))))
13103 @end group
13104 @end smallexample
13106 @noindent
13107 As written, the function works, but not in all circumstances.
13109 @node Whitespace Bug,  , Design count-words-region, count-words-region
13110 @comment  node-name,  next,  previous,  up
13111 @subsection The Whitespace Bug in @code{count-words-region}
13113 The @code{count-words-region} command described in the preceding
13114 section has two bugs, or rather, one bug with two manifestations.
13115 First, if you mark a region containing only whitespace in the middle
13116 of some text, the @code{count-words-region} command tells you that the
13117 region contains one word!  Second, if you mark a region containing
13118 only whitespace at the end of the buffer or the accessible portion of
13119 a narrowed buffer, the command displays an error message that looks
13120 like this:
13122 @smallexample
13123 Search failed: "\\w+\\W*"
13124 @end smallexample
13126 If you are reading this in Info in GNU Emacs, you can test for these
13127 bugs yourself.
13129 First, evaluate the function in the usual manner to install it.
13130 @ifinfo
13131 Here is a copy of the definition.  Place your cursor after the closing
13132 parenthesis and type @kbd{C-x C-e} to install it.
13134 @smallexample
13135 @group
13136 ;; @r{First version; has bugs!}
13137 (defun count-words-region (beginning end)
13138   "Print number of words in the region.
13139 Words are defined as at least one word-constituent character followed
13140 by at least one character that is not a word-constituent.  The buffer's
13141 syntax table determines which characters these are."
13142 @end group
13143 @group
13144   (interactive "r")
13145   (message "Counting words in region ... ")
13146 @end group
13148 @group
13149 ;;; @r{1. Set up appropriate conditions.}
13150   (save-excursion
13151     (goto-char beginning)
13152     (let ((count 0))
13153 @end group
13155 @group
13156 ;;; @r{2. Run the} while @r{loop.}
13157       (while (< (point) end)
13158         (re-search-forward "\\w+\\W*")
13159         (setq count (1+ count)))
13160 @end group
13162 @group
13163 ;;; @r{3. Send a message to the user.}
13164       (cond ((zerop count)
13165              (message "The region does NOT have any words."))
13166             ((= 1 count) (message "The region has 1 word."))
13167             (t (message "The region has %d words." count))))))
13168 @end group
13169 @end smallexample
13170 @end ifinfo
13172 @need 1000
13173 If you wish, you can also install this keybinding by evaluating it:
13175 @smallexample
13176 (global-set-key "\C-c=" 'count-words-region)
13177 @end smallexample
13179 To conduct the first test, set mark and point to the beginning and end
13180 of the following line and then type @kbd{C-c =} (or @kbd{M-x
13181 count-words-region} if you have not bound @kbd{C-c =}):
13183 @smallexample
13184     one   two  three
13185 @end smallexample
13187 @noindent
13188 Emacs will tell you, correctly, that the region has three words.
13190 Repeat the test, but place mark at the beginning of the line and place
13191 point just @emph{before} the word @samp{one}.  Again type the command
13192 @kbd{C-c =} (or @kbd{M-x count-words-region}).  Emacs should tell you
13193 that the region has no words, since it is composed only of the
13194 whitespace at the beginning of the line.  But instead Emacs tells you
13195 that the region has one word!
13197 For the third test, copy the sample line to the end of the
13198 @file{*scratch*} buffer and then type several spaces at the end of the
13199 line.  Place mark right after the word @samp{three} and point at the
13200 end of line.  (The end of the line will be the end of the buffer.)
13201 Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before.
13202 Again, Emacs should tell you that the region has no words, since it is
13203 composed only of the whitespace at the end of the line.  Instead,
13204 Emacs displays an error message saying @samp{Search failed}.
13206 The two bugs stem from the same problem.
13208 Consider the first manifestation of the bug, in which the command
13209 tells you that the whitespace at the beginning of the line contains
13210 one word.  What happens is this: The @code{M-x count-words-region}
13211 command moves point to the beginning of the region.  The @code{while}
13212 tests whether the value of point is smaller than the value of
13213 @code{end}, which it is.  Consequently, the regular expression search
13214 looks for and finds the first word.  It leaves point after the word.
13215 @code{count} is set to one.  The @code{while} loop repeats; but this
13216 time the value of point is larger than the value of @code{end}, the
13217 loop is exited; and the function displays a message saying the number
13218 of words in the region is one.  In brief, the regular expression
13219 search looks for and finds the word even though it is outside
13220 the marked region.
13222 In the second manifestation of the bug, the region is whitespace at
13223 the end of the buffer.  Emacs says @samp{Search failed}.  What happens
13224 is that the true-or-false-test in the @code{while} loop tests true, so
13225 the search expression is executed.  But since there are no more words
13226 in the buffer, the search fails.
13228 In both manifestations of the bug, the search extends or attempts to
13229 extend outside of the region.
13231 The solution is to limit the search to the region---this is a fairly
13232 simple action, but as you may have come to expect, it is not quite as
13233 simple as you might think.
13235 As we have seen, the @code{re-search-forward} function takes a search
13236 pattern as its first argument.  But in addition to this first,
13237 mandatory argument, it accepts three optional arguments.  The optional
13238 second argument bounds the search.  The optional third argument, if
13239 @code{t}, causes the function to return @code{nil} rather than signal
13240 an error if the search fails.  The optional fourth argument is a
13241 repeat count.  (In Emacs, you can see a function's documentation by
13242 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
13244 In the @code{count-words-region} definition, the value of the end of
13245 the region is held by the variable @code{end} which is passed as an
13246 argument to the function.  Thus, we can add @code{end} as an argument
13247 to the regular expression search expression:
13249 @smallexample
13250 (re-search-forward "\\w+\\W*" end)
13251 @end smallexample
13253 However, if you make only this change to the @code{count-words-region}
13254 definition and then test the new version of the definition on a
13255 stretch of whitespace, you will receive an error message saying
13256 @samp{Search failed}.
13258 What happens is this: the search is limited to the region, and fails
13259 as you expect because there are no word-constituent characters in the
13260 region.  Since it fails, we receive an error message.  But we do not
13261 want to receive an error message in this case; we want to receive the
13262 message that "The region does NOT have any words."
13264 The solution to this problem is to provide @code{re-search-forward}
13265 with a third argument of @code{t}, which causes the function to return
13266 @code{nil} rather than signal an error if the search fails.
13268 However, if you make this change and try it, you will see the message
13269 ``Counting words in region ... '' and @dots{} you will keep on seeing
13270 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
13272 Here is what happens: the search is limited to the region, as before,
13273 and it fails because there are no word-constituent characters in the
13274 region, as expected.  Consequently, the @code{re-search-forward}
13275 expression returns @code{nil}.  It does nothing else.  In particular,
13276 it does not move point, which it does as a side effect if it finds the
13277 search target.  After the @code{re-search-forward} expression returns
13278 @code{nil}, the next expression in the @code{while} loop is evaluated.
13279 This expression increments the count.  Then the loop repeats.  The
13280 true-or-false-test tests true because the value of point is still less
13281 than the value of end, since the @code{re-search-forward} expression
13282 did not move point. @dots{} and the cycle repeats @dots{}
13284 The @code{count-words-region} definition requires yet another
13285 modification, to cause the true-or-false-test of the @code{while} loop
13286 to test false if the search fails.  Put another way, there are two
13287 conditions that must be satisfied in the true-or-false-test before the
13288 word count variable is incremented: point must still be within the
13289 region and the search expression must have found a word to count.
13291 Since both the first condition and the second condition must be true
13292 together, the two expressions, the region test and the search
13293 expression, can be joined with an @code{and} special form and embedded in
13294 the @code{while} loop as the true-or-false-test, like this:
13296 @smallexample
13297 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
13298 @end smallexample
13300 @c colon in printed section title causes problem in Info cross reference
13301 @c also trouble with an overfull hbox
13302 @iftex
13303 @noindent
13304 (For information about @code{and}, see
13305 @ref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
13306 Functions}.)
13307 @end iftex
13308 @ifinfo
13309 @noindent
13310 (@xref{forward-paragraph}, for information about @code{and}.)
13311 @end ifinfo
13313 The @code{re-search-forward} expression returns @code{t} if the search
13314 succeeds and as a side effect moves point.  Consequently, as words are
13315 found, point is moved through the region.  When the search
13316 expression fails to find another word, or when point reaches the end
13317 of the region, the true-or-false-test tests false, the @code{while}
13318 loop exists, and the @code{count-words-region} function displays one
13319 or other of its messages.
13321 After incorporating these final changes, the @code{count-words-region}
13322 works without bugs (or at least, without bugs that I have found!).
13323 Here is what it looks like:
13325 @smallexample
13326 @group
13327 ;;; @r{Final version:} @code{while}
13328 (defun count-words-region (beginning end)
13329   "Print number of words in the region."
13330   (interactive "r")
13331   (message "Counting words in region ... ")
13332 @end group
13334 @group
13335 ;;; @r{1. Set up appropriate conditions.}
13336   (save-excursion
13337     (let ((count 0))
13338       (goto-char beginning)
13339 @end group
13341 @group
13342 ;;; @r{2. Run the} while @r{loop.}
13343       (while (and (< (point) end)
13344                   (re-search-forward "\\w+\\W*" end t))
13345         (setq count (1+ count)))
13346 @end group
13348 @group
13349 ;;; @r{3. Send a message to the user.}
13350       (cond ((zerop count)
13351              (message
13352               "The region does NOT have any words."))
13353             ((= 1 count)
13354              (message
13355               "The region has 1 word."))
13356             (t
13357              (message
13358               "The region has %d words." count))))))
13359 @end group
13360 @end smallexample
13362 @node recursive-count-words, Counting Exercise, count-words-region, Counting Words
13363 @comment  node-name,  next,  previous,  up
13364 @section Count Words Recursively
13365 @cindex Count words recursively
13366 @cindex Recursively counting words
13367 @cindex Words, counted recursively
13369 You can write the function for counting words recursively as well as
13370 with a @code{while} loop.  Let's see how this is done.
13372 First, we need to recognize that the @code{count-words-region}
13373 function has three jobs: it sets up the appropriate conditions for
13374 counting to occur; it counts the words in the region; and it sends a
13375 message to the user telling how many words there are.
13377 If we write a single recursive function to do everything, we will
13378 receive a message for every recursive call.  If the region contains 13
13379 words, we will receive thirteen messages, one right after the other.
13380 We don't want this!  Instead, we must write two functions to do the
13381 job, one of which (the recursive function) will be used inside of the
13382 other.  One function will set up the conditions and display the
13383 message; the other will return the word count.
13385 Let us start with the function that causes the message to be displayed.
13386 We can continue to call this @code{count-words-region}.
13388 This is the function that the user will call.  It will be interactive.
13389 Indeed, it will be similar to our previous versions of this
13390 function, except that it will call @code{recursive-count-words} to
13391 determine how many words are in the region.
13393 @need 1250
13394 We can readily construct a template for this function, based on our
13395 previous versions:
13397 @smallexample
13398 @group
13399 ;; @r{Recursive version; uses regular expression search}
13400 (defun count-words-region (beginning end)
13401   "@var{documentation}@dots{}"
13402   (@var{interactive-expression}@dots{})
13403 @end group
13404 @group
13406 ;;; @r{1. Set up appropriate conditions.}
13407   (@var{explanatory message})
13408   (@var{set-up functions}@dots{}
13409 @end group
13410 @group
13412 ;;; @r{2. Count the words.}
13413     @var{recursive call}
13414 @end group
13415 @group
13417 ;;; @r{3. Send a message to the user.}
13418     @var{message providing word count}))
13419 @end group
13420 @end smallexample
13422 The definition looks straightforward, except that somehow the count
13423 returned by the recursive call must be passed to the message
13424 displaying the word count.  A little thought suggests that this can be
13425 done by making use of a @code{let} expression: we can bind a variable
13426 in the varlist of a @code{let} expression to the number of words in
13427 the region, as returned by the recursive call; and then the
13428 @code{cond} expression, using binding, can display the value to the
13429 user.
13431 Often, one thinks of the binding within a @code{let} expression as
13432 somehow secondary to the `primary' work of a function.  But in this
13433 case, what you might consider the `primary' job of the function,
13434 counting words, is done within the @code{let} expression.
13436 @need 1250
13437 Using @code{let}, the function definition looks like this:
13439 @smallexample
13440 @group
13441 (defun count-words-region (beginning end)
13442   "Print number of words in the region."
13443   (interactive "r")
13444 @end group
13446 @group
13447 ;;; @r{1. Set up appropriate conditions.}
13448   (message "Counting words in region ... ")
13449   (save-excursion
13450     (goto-char beginning)
13451 @end group
13453 @group
13454 ;;; @r{2. Count the words.}
13455     (let ((count (recursive-count-words end)))
13456 @end group
13458 @group
13459 ;;; @r{3. Send a message to the user.}
13460       (cond ((zerop count)
13461              (message
13462               "The region does NOT have any words."))
13463             ((= 1 count)
13464              (message
13465               "The region has 1 word."))
13466             (t
13467              (message
13468               "The region has %d words." count))))))
13469 @end group
13470 @end smallexample
13472 Next, we need to write the recursive counting function.
13474 A recursive function has at least three parts: the `do-again-test', the
13475 `next-step-expression', and the recursive call.
13477 The do-again-test determines whether the function will or will not be
13478 called again.  Since we are counting words in a region and can use a
13479 function that moves point forward for every word, the do-again-test
13480 can check whether point is still within the region.  The do-again-test
13481 should find the value of point and determine whether point is before,
13482 at, or after the value of the end of the region.  We can use the
13483 @code{point} function to locate point.  Clearly, we must pass the
13484 value of the end of the region to the recursive counting function as an
13485 argument.
13487 In addition, the do-again-test should also test whether the search finds a
13488 word.  If it does not, the function should not call itself again.
13490 The next-step-expression changes a value so that when the recursive
13491 function is supposed to stop calling itself, it stops.  More
13492 precisely, the next-step-expression changes a value so that at the
13493 right time, the do-again-test stops the recursive function from
13494 calling itself again.  In this case, the next-step-expression can be
13495 the expression that moves point forward, word by word.
13497 The third part of a recursive function is the recursive call.
13499 Somewhere, also, we also need a part that does the `work' of the
13500 function, a part that does the counting.  A vital part!
13502 @need 1250
13503 But already, we have an outline of the recursive counting function:
13505 @smallexample
13506 @group
13507 (defun recursive-count-words (region-end)
13508   "@var{documentation}@dots{}"
13509    @var{do-again-test}
13510    @var{next-step-expression}
13511    @var{recursive call})
13512 @end group
13513 @end smallexample
13515 Now we need to fill in the slots.  Let's start with the simplest cases
13516 first:  if point is at or beyond the end of the region, there cannot
13517 be any words in the region, so the function should return zero.
13518 Likewise, if the search fails, there are no words to count, so the
13519 function should return zero.
13521 On the other hand, if point is within the region and the search
13522 succeeds, the function should call itself again.
13524 @need 800
13525 Thus, the do-again-test should look like this:
13527 @smallexample
13528 @group
13529 (and (< (point) region-end)
13530      (re-search-forward "\\w+\\W*" region-end t))
13531 @end group
13532 @end smallexample
13534 Note that the search expression is part of the do-again-test---the
13535 function returns @code{t} if its search succeeds and @code{nil} if it
13536 fails.  (@xref{Whitespace Bug, , The Whitespace Bug in
13537 @code{count-words-region}}, for an explanation of how
13538 @code{re-search-forward} works.)
13540 The do-again-test is the true-or-false test of an @code{if} clause.
13541 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
13542 clause should call the function again; but if it fails, the else-part
13543 should return zero since either point is outside the region or the
13544 search failed because there were no words to find.
13546 But before considering the recursive call, we need to consider the
13547 next-step-expression.  What is it?  Interestingly, it is the search
13548 part of the do-again-test.
13550 In addition to returning @code{t} or @code{nil} for the
13551 do-again-test, @code{re-search-forward} moves point forward as a side
13552 effect of a successful search.  This is the action that changes the
13553 value of point so that the recursive function stops calling itself
13554 when point completes its movement through the region.  Consequently,
13555 the @code{re-search-forward} expression is the next-step-expression.
13557 @need 1200
13558 In outline, then, the body of the @code{recursive-count-words}
13559 function looks like this:
13561 @smallexample
13562 @group
13563 (if @var{do-again-test-and-next-step-combined}
13564     ;; @r{then}
13565     @var{recursive-call-returning-count}
13566   ;; @r{else}
13567   @var{return-zero})
13568 @end group
13569 @end smallexample
13571 How to incorporate the mechanism that counts?
13573 If you are not used to writing recursive functions, a question like
13574 this can be troublesome.  But it can and should be approached
13575 systematically.
13577 We know that the counting mechanism should be associated in some way
13578 with the recursive call.  Indeed, since the next-step-expression moves
13579 point forward by one word, and since a recursive call is made for
13580 each word, the counting mechanism must be an expression that adds one
13581 to the value returned by a call to @code{recursive-count-words}.
13583 Consider several cases:
13585 @itemize @bullet
13586 @item
13587 If there are two words in the region, the function should return
13588 a value resulting from adding one to the value returned when it counts
13589 the first word, plus the number returned when it counts the remaining
13590 words in the region, which in this case is one.
13592 @item
13593 If there is one word in the region, the function should return
13594 a value resulting from adding one to the value returned when it counts
13595 that word, plus the number returned when it counts the remaining
13596 words in the region, which in this case is zero.
13598 @item
13599 If there are no words in the region, the function should return zero.
13600 @end itemize
13602 From the sketch we can see that the else-part of the @code{if} returns
13603 zero for the case of no words.  This means that the then-part of the
13604 @code{if} must return a value resulting from adding one to the value
13605 returned from a count of the remaining words.
13607 @need 1200
13608 The expression will look like this, where @code{1+} is a function that
13609 adds one to its argument.
13611 @smallexample
13612 (1+ (recursive-count-words region-end))
13613 @end smallexample
13615 @need 1200
13616 The whole @code{recursive-count-words} function will then look like
13617 this:
13619 @smallexample
13620 @group
13621 (defun recursive-count-words (region-end)
13622   "@var{documentation}@dots{}"
13624 ;;; @r{1. do-again-test}
13625   (if (and (< (point) region-end)
13626            (re-search-forward "\\w+\\W*" region-end t))
13627 @end group
13629 @group
13630 ;;; @r{2. then-part: the recursive call}
13631       (1+ (recursive-count-words region-end))
13633 ;;; @r{3. else-part}
13634     0))
13635 @end group
13636 @end smallexample
13638 @need 1250
13639 Let's examine how this works:
13641 If there are no words in the region, the else part of the @code{if}
13642 expression is evaluated and consequently the function returns zero.
13644 If there is one word in the region, the value of point is less than
13645 the value of @code{region-end} and the search succeeds.  In this case,
13646 the true-or-false-test of the @code{if} expression tests true, and the
13647 then-part of the @code{if} expression is evaluated.  The counting
13648 expression is evaluated.  This expression returns a value (which will
13649 be the value returned by the whole function) that is the sum of one
13650 added to the value returned by a recursive call.
13652 Meanwhile, the next-step-expression has caused point to jump over the
13653 first (and in this case only) word in the region.  This means that
13654 when @code{(recursive-count-words region-end)} is evaluated a second
13655 time, as a result of the recursive call, the value of point will be
13656 equal to or greater than the value of region end.  So this time,
13657 @code{recursive-count-words} will return zero.  The zero will be added
13658 to one, and the original evaluation of @code{recursive-count-words}
13659 will return one plus zero, which is one, which is the correct amount.
13661 Clearly, if there are two words in the region, the first call to
13662 @code{recursive-count-words} returns one added to the value returned
13663 by calling @code{recursive-count-words} on a region containing the
13664 remaining word---that is, it adds one to one, producing two, which is
13665 the correct amount.
13667 Similarly, if there are three words in the region, the first call to
13668 @code{recursive-count-words} returns one added to the value returned
13669 by calling @code{recursive-count-words} on a region containing the
13670 remaining two words---and so on and so on.
13672 @need 1250
13673 @noindent
13674 With full documentation the two functions look like this:
13676 @need 1250
13677 @noindent
13678 The recursive function:
13680 @findex recursive-count-words
13681 @smallexample
13682 @group
13683 (defun recursive-count-words (region-end)
13684   "Number of words between point and REGION-END."
13685 @end group
13687 @group
13688 ;;; @r{1. do-again-test}
13689   (if (and (< (point) region-end)
13690            (re-search-forward "\\w+\\W*" region-end t))
13691 @end group
13693 @group
13694 ;;; @r{2. then-part: the recursive call}
13695       (1+ (recursive-count-words region-end))
13697 ;;; @r{3. else-part}
13698     0))
13699 @end group
13700 @end smallexample
13702 @need 800
13703 @noindent
13704 The wrapper:
13706 @smallexample
13707 @group
13708 ;;; @r{Recursive version}
13709 (defun count-words-region (beginning end)
13710   "Print number of words in the region.
13711 @end group
13713 @group
13714 Words are defined as at least one word-constituent
13715 character followed by at least one character that is
13716 not a word-constituent.  The buffer's syntax table
13717 determines which characters these are."
13718 @end group
13719 @group
13720   (interactive "r")
13721   (message "Counting words in region ... ")
13722   (save-excursion
13723     (goto-char beginning)
13724     (let ((count (recursive-count-words end)))
13725 @end group
13726 @group
13727       (cond ((zerop count)
13728              (message
13729               "The region does NOT have any words."))
13730 @end group
13731 @group
13732             ((= 1 count)
13733              (message "The region has 1 word."))
13734             (t
13735              (message
13736               "The region has %d words." count))))))
13737 @end group
13738 @end smallexample
13740 @node Counting Exercise,  , recursive-count-words, Counting Words
13741 @section Exercise: Counting Punctuation
13743 Using a @code{while} loop, write a function to count the number of
13744 punctuation marks in a region---period, comma, semicolon, colon,
13745 exclamation mark, and question mark.  Do the same using recursion.
13747 @node Words in a defun, Readying a Graph, Counting Words, Top
13748 @chapter Counting Words in a @code{defun}
13749 @cindex Counting words in a @code{defun}
13750 @cindex Word counting in a @code{defun}
13752 Our next project is to count the number of words in a function
13753 definition.  Clearly, this can be done using some variant of
13754 @code{count-word-region}.  @xref{Counting Words, , Counting Words:
13755 Repetition and Regexps}.  If we are just going to count the words in
13756 one definition, it is easy enough to mark the definition with the
13757 @kbd{C-M-h} (@code{mark-defun}) command, and then call
13758 @code{count-word-region}.
13760 However, I am more ambitious: I want to count the words and symbols in
13761 every definition in the Emacs sources and then print a graph that
13762 shows how many functions there are of each length: how many contain 40
13763 to 49 words or symbols, how many contain 50 to 59 words or symbols,
13764 and so on.  I have often been curious how long a typical function is,
13765 and this will tell.
13767 @menu
13768 * Divide and Conquer::
13769 * Words and Symbols::           What to count?
13770 * Syntax::                      What constitutes a word or symbol?
13771 * count-words-in-defun::        Very like @code{count-words}.
13772 * Several defuns::              Counting several defuns in a file.
13773 * Find a File::                 Do you want to look at a file?
13774 * lengths-list-file::           A list of the lengths of many definitions.
13775 * Several files::               Counting in definitions in different files.
13776 * Several files recursively::   Recursively counting in different files.
13777 * Prepare the data::            Prepare the data for display in a graph.
13778 @end menu
13780 @node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
13781 @ifnottex
13782 @unnumberedsec Divide and Conquer
13783 @end ifnottex
13785 Described in one phrase, the histogram project is daunting; but
13786 divided into numerous small steps, each of which we can take one at a
13787 time, the project becomes less fearsome.  Let us consider what the
13788 steps must be:
13790 @itemize @bullet
13791 @item
13792 First, write a function to count the words in one definition.  This
13793 includes the problem of handling symbols as well as words.
13795 @item
13796 Second, write a function to list the numbers of words in each function
13797 in a file.  This function can use the @code{count-words-in-defun}
13798 function.
13800 @item
13801 Third, write a function to list the numbers of words in each function
13802 in each of several files.  This entails automatically finding the
13803 various files, switching to them, and counting the words in the
13804 definitions within them.
13806 @item
13807 Fourth, write a function to convert the list of numbers that we
13808 created in step three to a form that will be suitable for printing as
13809 a graph.
13811 @item
13812 Fifth, write a function to print the results as a graph.
13813 @end itemize
13815 This is quite a project!  But if we take each step slowly, it will not
13816 be difficult.
13818 @node Words and Symbols, Syntax, Divide and Conquer, Words in a defun
13819 @section What to Count?
13820 @cindex Words and symbols in defun
13822 When we first start thinking about how to count the words in a
13823 function definition, the first question is (or ought to be) what are
13824 we going to count?  When we speak of `words' with respect to a Lisp
13825 function definition, we are actually speaking, in large part, of
13826 `symbols'.  For example, the following @code{multiply-by-seven}
13827 function contains the five symbols @code{defun},
13828 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}.  In
13829 addition, in the documentation string, it contains the four words
13830 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}.  The
13831 symbol @samp{number} is repeated, so the definition contains a total
13832 of ten words and symbols.
13834 @smallexample
13835 @group
13836 (defun multiply-by-seven (number)
13837   "Multiply NUMBER by seven."
13838   (* 7 number))
13839 @end group
13840 @end smallexample
13842 @noindent
13843 However, if we mark the @code{multiply-by-seven} definition with
13844 @kbd{C-M-h} (@code{mark-defun}), and then call
13845 @code{count-words-region} on it, we will find that
13846 @code{count-words-region} claims the definition has eleven words, not
13847 ten!  Something is wrong!
13849 The problem is twofold: @code{count-words-region} does not count the
13850 @samp{*} as a word, and it counts the single symbol,
13851 @code{multiply-by-seven}, as containing three words.  The hyphens are
13852 treated as if they were interword spaces rather than intraword
13853 connectors: @samp{multiply-by-seven} is counted as if it were written
13854 @samp{multiply by seven}.
13856 The cause of this confusion is the regular expression search within
13857 the @code{count-words-region} definition that moves point forward word
13858 by word.  In the canonical version of @code{count-words-region}, the
13859 regexp is:
13861 @smallexample
13862 "\\w+\\W*"
13863 @end smallexample
13865 @noindent
13866 This regular expression is a pattern defining one or more word
13867 constituent characters possibly followed by one or more characters
13868 that are not word constituents.  What is meant by `word constituent
13869 characters' brings us to the issue of syntax, which is worth a section
13870 of its own.
13872 @node Syntax, count-words-in-defun, Words and Symbols, Words in a defun
13873 @section What Constitutes a Word or Symbol?
13874 @cindex Syntax categories and tables
13876 Emacs treats different characters as belonging to different
13877 @dfn{syntax categories}.  For example, the regular expression,
13878 @samp{\\w+}, is a pattern specifying one or more @emph{word
13879 constituent} characters.  Word constituent characters are members of
13880 one syntax category.  Other syntax categories include the class of
13881 punctuation characters, such as the period and the comma, and the
13882 class of whitespace characters, such as the blank space and the tab
13883 character.  (For more information, see @ref{Syntax, Syntax, The Syntax
13884 Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax
13885 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
13887 Syntax tables specify which characters belong to which categories.
13888 Usually, a hyphen is not specified as a `word constituent character'.
13889 Instead, it is specified as being in the `class of characters that are
13890 part of symbol names but not words.'  This means that the
13891 @code{count-words-region} function treats it in the same way it treats
13892 an interword white space, which is why @code{count-words-region}
13893 counts @samp{multiply-by-seven} as three words.
13895 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
13896 one symbol: modify the syntax table or modify the regular expression.
13898 We could redefine a hyphen as a word constituent character by
13899 modifying the syntax table that Emacs keeps for each mode.  This
13900 action would serve our purpose, except that a hyphen is merely the
13901 most common character within symbols that is not typically a word
13902 constituent character; there are others, too.
13904 Alternatively, we can redefine the regular expression used in the
13905 @code{count-words} definition so as to include symbols.  This
13906 procedure has the merit of clarity, but the task is a little tricky.
13908 @need 1200
13909 The first part is simple enough: the pattern must match ``at least one
13910 character that is a word or symbol constituent''.  Thus:
13912 @smallexample
13913 "\\(\\w\\|\\s_\\)+"
13914 @end smallexample
13916 @noindent
13917 The @samp{\\(} is the first part of the grouping construct that
13918 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
13919 by the @samp{\\|}.  The @samp{\\w} matches any word-constituent
13920 character and the @samp{\\s_} matches any character that is part of a
13921 symbol name but not a word-constituent character.  The @samp{+}
13922 following the group indicates that the word or symbol constituent
13923 characters must be matched at least once.
13925 However, the second part of the regexp is more difficult to design.
13926 What we want is to follow the first part with ``optionally one or more
13927 characters that are not constituents of a word or symbol''.  At first,
13928 I thought I could define this with the following:
13930 @smallexample
13931 "\\(\\W\\|\\S_\\)*"
13932 @end smallexample
13934 @noindent
13935 The upper case @samp{W} and @samp{S} match characters that are
13936 @emph{not} word or symbol constituents.  Unfortunately, this
13937 expression matches any character that is either not a word constituent
13938 or not a symbol constituent.  This matches any character!
13940 I then noticed that every word or symbol in my test region was
13941 followed by white space (blank space, tab, or newline).  So I tried
13942 placing a pattern to match one or more blank spaces after the pattern
13943 for one or more word or symbol constituents.  This failed, too.  Words
13944 and symbols are often separated by whitespace, but in actual code
13945 parentheses may follow symbols and punctuation may follow words.  So
13946 finally, I designed a pattern in which the word or symbol constituents
13947 are followed optionally by characters that are not white space and
13948 then followed optionally by white space.
13950 @need 800
13951 Here is the full regular expression:
13953 @smallexample
13954 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
13955 @end smallexample
13957 @node count-words-in-defun, Several defuns, Syntax, Words in a defun
13958 @section The @code{count-words-in-defun} Function
13959 @cindex Counting words in a @code{defun}
13961 We have seen that there are several ways to write a
13962 @code{count-word-region} function.  To write a
13963 @code{count-words-in-defun}, we need merely adapt one of these
13964 versions.
13966 The version that uses a @code{while} loop is easy to understand, so I
13967 am going to adapt that.  Because @code{count-words-in-defun} will be
13968 part of a more complex program, it need not be interactive and it need
13969 not display a message but just return the count.  These considerations
13970 simplify the definition a little.
13972 On the other hand, @code{count-words-in-defun} will be used within a
13973 buffer that contains function definitions.  Consequently, it is
13974 reasonable to ask that the function determine whether it is called
13975 when point is within a function definition, and if it is, to return
13976 the count for that definition.  This adds complexity to the
13977 definition, but saves us from needing to pass arguments to the
13978 function.
13980 @need 1250
13981 These considerations lead us to prepare the following template:
13983 @smallexample
13984 @group
13985 (defun count-words-in-defun ()
13986   "@var{documentation}@dots{}"
13987   (@var{set up}@dots{}
13988      (@var{while loop}@dots{})
13989    @var{return count})
13990 @end group
13991 @end smallexample
13993 @noindent
13994 As usual, our job is to fill in the slots.
13996 First, the set up.
13998 We are presuming that this function will be called within a buffer
13999 containing function definitions.  Point will either be within a
14000 function definition or not.  For @code{count-words-in-defun} to work,
14001 point must move to the beginning of the definition, a counter must
14002 start at zero, and the counting loop must stop when point reaches the
14003 end of the definition.
14005 The @code{beginning-of-defun} function searches backwards for an
14006 opening delimiter such as a @samp{(} at the beginning of a line, and
14007 moves point to that position, or else to the limit of the search.  In
14008 practice, this means that @code{beginning-of-defun} moves point to the
14009 beginning of an enclosing or preceding function definition, or else to
14010 the beginning of the buffer.  We can use @code{beginning-of-defun} to
14011 place point where we wish to start.
14013 The @code{while} loop requires a counter to keep track of the words or
14014 symbols being counted.  A @code{let} expression can be used to create
14015 a local variable for this purpose, and bind it to an initial value of zero.
14017 The @code{end-of-defun} function works like @code{beginning-of-defun}
14018 except that it moves point to the end of the definition.
14019 @code{end-of-defun} can be used as part of an expression that
14020 determines the position of the end of the definition.
14022 The set up for @code{count-words-in-defun} takes shape rapidly: first
14023 we move point to the beginning of the definition, then we create a
14024 local variable to hold the count, and finally, we record the position
14025 of the end of the definition so the @code{while} loop will know when to stop
14026 looping.
14028 @need 1250
14029 The code looks like this:
14031 @smallexample
14032 @group
14033 (beginning-of-defun)
14034 (let ((count 0)
14035       (end (save-excursion (end-of-defun) (point))))
14036 @end group
14037 @end smallexample
14039 @noindent
14040 The code is simple.  The only slight complication is likely to concern
14041 @code{end}: it is bound to the position of the end of the definition
14042 by a @code{save-excursion} expression that returns the value of point
14043 after @code{end-of-defun} temporarily moves it to the end of the
14044 definition.
14046 The second part of the @code{count-words-in-defun}, after the set up,
14047 is the @code{while} loop.
14049 The loop must contain an expression that jumps point forward word by
14050 word and symbol by symbol, and another expression that counts the
14051 jumps.  The true-or-false-test for the @code{while} loop should test
14052 true so long as point should jump forward, and false when point is at
14053 the end of the definition.  We have already redefined the regular
14054 expression for this (@pxref{Syntax}), so the loop is straightforward:
14056 @smallexample
14057 @group
14058 (while (and (< (point) end)
14059             (re-search-forward
14060              "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
14061   (setq count (1+ count)))
14062 @end group
14063 @end smallexample
14065 The third part of the function definition returns the count of words
14066 and symbols.  This part is the last expression within the body of the
14067 @code{let} expression, and can be, very simply, the local variable
14068 @code{count}, which when evaluated returns the count.
14070 @need 1250
14071 Put together, the @code{count-words-in-defun} definition looks like this:
14073 @findex count-words-in-defun
14074 @smallexample
14075 @group
14076 (defun count-words-in-defun ()
14077   "Return the number of words and symbols in a defun."
14078   (beginning-of-defun)
14079   (let ((count 0)
14080         (end (save-excursion (end-of-defun) (point))))
14081 @end group
14082 @group
14083     (while
14084         (and (< (point) end)
14085              (re-search-forward
14086               "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14087               end t))
14088       (setq count (1+ count)))
14089     count))
14090 @end group
14091 @end smallexample
14093 How to test this?  The function is not interactive, but it is easy to
14094 put a wrapper around the function to make it interactive; we can use
14095 almost the same code as for the recursive version of
14096 @code{count-words-region}:
14098 @smallexample
14099 @group
14100 ;;; @r{Interactive version.}
14101 (defun count-words-defun ()
14102   "Number of words and symbols in a function definition."
14103   (interactive)
14104   (message
14105    "Counting words and symbols in function definition ... ")
14106 @end group
14107 @group
14108   (let ((count (count-words-in-defun)))
14109     (cond
14110      ((zerop count)
14111       (message
14112        "The definition does NOT have any words or symbols."))
14113 @end group
14114 @group
14115      ((= 1 count)
14116       (message
14117        "The definition has 1 word or symbol."))
14118      (t
14119       (message
14120        "The definition has %d words or symbols." count)))))
14121 @end group
14122 @end smallexample
14124 @need 800
14125 @noindent
14126 Let's re-use @kbd{C-c =} as a convenient keybinding:
14128 @smallexample
14129 (global-set-key "\C-c=" 'count-words-defun)
14130 @end smallexample
14132 Now we can try out @code{count-words-defun}: install both
14133 @code{count-words-in-defun} and @code{count-words-defun}, and set the
14134 keybinding, and then place the cursor within the following definition:
14136 @smallexample
14137 @group
14138 (defun multiply-by-seven (number)
14139   "Multiply NUMBER by seven."
14140   (* 7 number))
14141      @result{} 10
14142 @end group
14143 @end smallexample
14145 @noindent
14146 Success!  The definition has 10 words and symbols.
14148 The next problem is to count the numbers of words and symbols in
14149 several definitions within a single file.
14151 @node Several defuns, Find a File, count-words-in-defun, Words in a defun
14152 @section Count Several @code{defuns} Within a File
14154 A file such as @file{simple.el} may have 80 or more function
14155 definitions within it.  Our long term goal is to collect statistics on
14156 many files, but as a first step, our immediate goal is to collect
14157 statistics on one file.
14159 The information will be a series of numbers, each number being the
14160 length of a function definition.  We can store the numbers in a list.
14162 We know that we will want to incorporate the information regarding one
14163 file with information about many other files; this means that the
14164 function for counting definition lengths within one file need only
14165 return the list of lengths.  It need not and should not display any
14166 messages.
14168 The word count commands contain one expression to jump point forward
14169 word by word and another expression to count the jumps.  The function
14170 to return the lengths of definitions can be designed to work the same
14171 way, with one expression to jump point forward definition by
14172 definition and another expression to construct the lengths' list.
14174 This statement of the problem makes it elementary to write the
14175 function definition.  Clearly, we will start the count at the
14176 beginning of the file, so the first command will be @code{(goto-char
14177 (point-min))}.  Next, we start the @code{while} loop; and the
14178 true-or-false test of the loop can be a regular expression search for
14179 the next function definition---so long as the search succeeds, point
14180 is moved forward and then the body of the loop is evaluated.  The body
14181 needs an expression that constructs the lengths' list.  @code{cons},
14182 the list construction command, can be used to create the list.  That
14183 is almost all there is to it.
14185 @need 800
14186 Here is what this fragment of code looks like:
14188 @smallexample
14189 @group
14190 (goto-char (point-min))
14191 (while (re-search-forward "^(defun" nil t)
14192   (setq lengths-list
14193         (cons (count-words-in-defun) lengths-list)))
14194 @end group
14195 @end smallexample
14197 What we have left out is the mechanism for finding the file that
14198 contains the function definitions.
14200 In previous examples, we either used this, the Info file, or we
14201 switched back and forth to some other buffer, such as the
14202 @file{*scratch*} buffer.
14204 Finding a file is a new process that we have not yet discussed.
14206 @node Find a File, lengths-list-file, Several defuns, Words in a defun
14207 @comment  node-name,  next,  previous,  up
14208 @section Find a File
14209 @cindex Find a File
14211 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
14212 command.  This command is almost, but not quite right for the lengths
14213 problem.
14215 @need 1200
14216 Let's look at the source for @code{find-file} (you can use the
14217 @code{find-tag} command or @kbd{C-h f} (@code{describe-function}) to
14218 find the source of a function):
14220 @smallexample
14221 @group
14222 (defun find-file (filename)
14223   "Edit file FILENAME.
14224 Switch to a buffer visiting file FILENAME,
14225 creating one if none already exists."
14226   (interactive "FFind file: ")
14227   (switch-to-buffer (find-file-noselect filename)))
14228 @end group
14229 @end smallexample
14231 The definition possesses short but complete documentation and an
14232 interactive specification that prompts you for a file name when you
14233 use the command interactively.  The body of the definition contains
14234 two functions, @code{find-file-noselect} and @code{switch-to-buffer}.
14236 According to its documentation as shown by @kbd{C-h f} (the
14237 @code{describe-function} command), the @code{find-file-noselect}
14238 function reads the named file into a buffer and returns the buffer.
14239 However, the buffer is not selected.  Emacs does not switch its
14240 attention (or yours if you are using @code{find-file-noselect}) to the
14241 named buffer.  That is what @code{switch-to-buffer} does: it switches
14242 the buffer to which Emacs attention is directed; and it switches the
14243 buffer displayed in the window to the new buffer.  We have discussed
14244 buffer switching elsewhere.  (@xref{Switching Buffers}.)
14246 In this histogram project, we do not need to display each file on the
14247 screen as the program determines the length of each definition within
14248 it.  Instead of employing @code{switch-to-buffer}, we can work with
14249 @code{set-buffer}, which redirects the attention of the computer
14250 program to a different buffer but does not redisplay it on the screen.
14251 So instead of calling on @code{find-file} to do the job, we must write
14252 our own expression.
14254 The task is easy: use  @code{find-file-noselect} and @code{set-buffer}.
14256 @node lengths-list-file, Several files, Find a File, Words in a defun
14257 @section @code{lengths-list-file} in Detail
14259 The core of the @code{lengths-list-file} function is a @code{while}
14260 loop containing a function to move point forward `defun by defun' and
14261 a function to count the number of words and symbols in each defun.
14262 This core must be surrounded by functions that do various other tasks,
14263 including finding the file, and ensuring that point starts out at the
14264 beginning of the file.  The function definition looks like this:
14265 @findex lengths-list-file
14267 @smallexample
14268 @group
14269 (defun lengths-list-file (filename)
14270   "Return list of definitions' lengths within FILE.
14271 The returned list is a list of numbers.
14272 Each number is the number of words or
14273 symbols in one function definition."
14274 @end group
14275 @group
14276   (message "Working on `%s' ... " filename)
14277   (save-excursion
14278     (let ((buffer (find-file-noselect filename))
14279           (lengths-list))
14280       (set-buffer buffer)
14281       (setq buffer-read-only t)
14282       (widen)
14283       (goto-char (point-min))
14284       (while (re-search-forward "^(defun" nil t)
14285         (setq lengths-list
14286               (cons (count-words-in-defun) lengths-list)))
14287       (kill-buffer buffer)
14288       lengths-list)))
14289 @end group
14290 @end smallexample
14292 @noindent
14293 The function is passed one argument, the name of the file on which it
14294 will work.  It has four lines of documentation, but no interactive
14295 specification.  Since people worry that a computer is broken if they
14296 don't see anything going on, the first line of the body is a
14297 message.
14299 The next line contains a @code{save-excursion} that returns Emacs'
14300 attention to the current buffer when the function completes.  This is
14301 useful in case you embed this function in another function that
14302 presumes point is restored to the original buffer.
14304 In the varlist of the @code{let} expression, Emacs finds the file and
14305 binds the local variable @code{buffer} to the buffer containing the
14306 file.  At the same time, Emacs creates @code{lengths-list} as a local
14307 variable.
14309 Next, Emacs switches its attention to the buffer.
14311 In the following line, Emacs makes the buffer read-only.  Ideally,
14312 this line is not necessary.  None of the functions for counting words
14313 and symbols in a function definition should change the buffer.
14314 Besides, the buffer is not going to be saved, even if it were changed.
14315 This line is entirely the consequence of great, perhaps excessive,
14316 caution.  The reason for the caution is that this function and those
14317 it calls work on the sources for Emacs and it is very inconvenient if
14318 they are inadvertently modified.  It goes without saying that I did
14319 not realize a need for this line until an experiment went awry and
14320 started to modify my Emacs source files @dots{}
14322 Next comes a call to widen the buffer if it is narrowed.  This
14323 function is usually not needed---Emacs creates a fresh buffer if none
14324 already exists; but if a buffer visiting the file already exists Emacs
14325 returns that one.  In this case, the buffer may be narrowed and must
14326 be widened.  If we wanted to be fully `user-friendly', we would
14327 arrange to save the restriction and the location of point, but we
14328 won't.
14330 The @code{(goto-char (point-min))} expression moves point to the
14331 beginning of the buffer.
14333 Then comes a @code{while} loop in which the `work' of the function is
14334 carried out.  In the loop, Emacs determines the length of each
14335 definition and constructs a lengths' list containing the information.
14337 Emacs kills the buffer after working through it.  This is to save
14338 space inside of Emacs.  My version of Emacs 19 contained over 300
14339 source files of interest; Emacs 21 contains over 800 source files.
14340 Another function will apply @code{lengths-list-file} to each of the
14341 files.
14343 Finally, the last expression within the @code{let} expression is the
14344 @code{lengths-list} variable; its value is returned as the value of
14345 the whole function.
14347 You can try this function by installing it in the usual fashion.  Then
14348 place your cursor after the following expression and type @kbd{C-x
14349 C-e} (@code{eval-last-sexp}).
14351 @c !!! 21.0.100 lisp sources location here
14352 @smallexample
14353 (lengths-list-file
14354  "/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el")
14355 @end smallexample
14357 @c was: (lengths-list-file "../lisp/debug.el")
14358 @c !!!  as of 21, Info file is in
14359 @c /usr/share/info/emacs-lisp-intro.info.gz
14360 @c but debug.el is in  /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
14362 @noindent
14363 (You may need to change the pathname of the file; the one here worked
14364 with GNU Emacs version 21.0.100.  To change the expression, copy it to
14365 the @file{*scratch*} buffer and edit it.
14367 @need 1200
14368 @noindent
14369 (Also, to see the full length of the list, rather than a truncated
14370 version, you may have to evaluate the following:
14372 @smallexample
14373 (custom-set-variables '(eval-expression-print-length nil))
14374 @end smallexample
14376 @noindent
14377 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.)
14378 Then evaluate the @code{lengths-list-file} expression.)
14380 @need 1200
14381 The lengths' list for @file{debug.el} takes less than a second to
14382 produce and looks like this:
14384 @smallexample
14385 (77 95 85 87 131 89 50 25 44 44 68 35 64 45 17 34 167 457)
14386 @end smallexample
14388 @need 1500
14389 (Using my old machine, the version 19 lengths' list for @file{debug.el}
14390 took seven seconds to produce and looked like this:
14392 @smallexample
14393 (75 41 80 62 20 45 44 68 45 12 34 235)
14394 @end smallexample
14396 (The newer version of  @file{debug.el} contains more defuns than the
14397 earlier one; and my new machine is much faster than the old one.)
14399 Note that the length of the last definition in the file is first in
14400 the list.
14402 @node Several files, Several files recursively, lengths-list-file, Words in a defun
14403 @section Count Words in @code{defuns} in Different Files
14405 In the previous section, we created a function that returns a list of
14406 the lengths of each definition in a file.  Now, we want to define a
14407 function to return a master list of the lengths of the definitions in
14408 a list of files.
14410 Working on each of a list of files is a repetitious act, so we can use
14411 either a @code{while} loop or recursion.
14413 @menu
14414 * lengths-list-many-files::     Return a list of the lengths of defuns.
14415 * append::                      Attach one list to another.
14416 @end menu
14418 @node lengths-list-many-files, append, Several files, Several files
14419 @ifnottex
14420 @unnumberedsubsec Determine the lengths of @code{defuns}
14421 @end ifnottex
14423 The design using a @code{while} loop is routine.  The argument passed
14424 the function is a list of files.  As we saw earlier (@pxref{Loop
14425 Example}), you can write a @code{while} loop so that the body of the
14426 loop is evaluated if such a list contains elements, but to exit the
14427 loop if the list is empty.  For this design to work, the body of the
14428 loop must contain an expression that shortens the list each time the
14429 body is evaluated, so that eventually the list is empty.  The usual
14430 technique is to set the value of the list to the value of the @sc{cdr}
14431 of the list each time the body is evaluated.
14433 @need 800
14434 The template looks like this:
14436 @smallexample
14437 @group
14438 (while @var{test-whether-list-is-empty}
14439   @var{body}@dots{}
14440   @var{set-list-to-cdr-of-list})
14441 @end group
14442 @end smallexample
14444 Also, we remember that a @code{while} loop returns @code{nil} (the
14445 result of evaluating the true-or-false-test), not the result of any
14446 evaluation within its body.  (The evaluations within the body of the
14447 loop are done for their side effects.)  However, the expression that
14448 sets the lengths' list is part of the body---and that is the value
14449 that we want returned by the function as a whole.  To do this, we
14450 enclose the @code{while} loop within a @code{let} expression, and
14451 arrange that the last element of the @code{let} expression contains
14452 the value of the lengths' list.  (@xref{Incrementing Example, , Loop
14453 Example with an Incrementing Counter}.)
14455 @findex lengths-list-many-files
14456 @need 1250
14457 These considerations lead us directly to the function itself:
14459 @smallexample
14460 @group
14461 ;;; @r{Use @code{while} loop.}
14462 (defun lengths-list-many-files (list-of-files)
14463   "Return list of lengths of defuns in LIST-OF-FILES."
14464 @end group
14465 @group
14466   (let (lengths-list)
14468 ;;; @r{true-or-false-test}
14469     (while list-of-files
14470       (setq lengths-list
14471             (append
14472              lengths-list
14474 ;;; @r{Generate a lengths' list.}
14475              (lengths-list-file
14476               (expand-file-name (car list-of-files)))))
14477 @end group
14479 @group
14480 ;;; @r{Make files' list shorter.}
14481       (setq list-of-files (cdr list-of-files)))
14483 ;;; @r{Return final value of lengths' list.}
14484     lengths-list))
14485 @end group
14486 @end smallexample
14488 @code{expand-file-name} is a built-in function that converts a file
14489 name to the absolute, long, path name form of the directory in which
14490 the function is called.
14492 @c !!! 21.0.100 lisp sources location here
14493 @need 1500
14494 Thus, if @code{expand-file-name} is called on @code{debug.el} when
14495 Emacs is visiting the
14496 @file{/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/} directory,
14498 @smallexample
14499 debug.el
14500 @end smallexample
14502 @need 800
14503 @noindent
14504 becomes
14506 @c !!! 21.0.100 lisp sources location here
14507 @smallexample
14508 /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
14509 @end smallexample
14511 The only other new element of this function definition is the as yet
14512 unstudied function @code{append}, which merits a short section for
14513 itself.
14515 @node append,  , lengths-list-many-files, Several files
14516 @subsection The @code{append} Function
14518 @need 800
14519 The @code{append} function attaches one list to another.  Thus,
14521 @smallexample
14522 (append '(1 2 3 4) '(5 6 7 8))
14523 @end smallexample
14525 @need 800
14526 @noindent
14527 produces the list
14529 @smallexample
14530 (1 2 3 4 5 6 7 8)
14531 @end smallexample
14533 This is exactly how we want to attach two lengths' lists produced by
14534 @code{lengths-list-file} to each other.  The results contrast with
14535 @code{cons},
14537 @smallexample
14538 (cons '(1 2 3 4) '(5 6 7 8))
14539 @end smallexample
14541 @need 1250
14542 @noindent
14543 which constructs a new list in which the first argument to @code{cons}
14544 becomes the first element of the new list:
14546 @smallexample
14547 ((1 2 3 4) 5 6 7 8)
14548 @end smallexample
14550 @node Several files recursively, Prepare the data, Several files, Words in a defun
14551 @section Recursively Count Words in Different Files
14553 Besides a @code{while} loop, you can work on each of a list of files
14554 with recursion.  A recursive version of @code{lengths-list-many-files}
14555 is short and simple.
14557 The recursive function has the usual parts: the `do-again-test', the
14558 `next-step-expression', and the recursive call.  The `do-again-test'
14559 determines whether the function should call itself again, which it
14560 will do if the @code{list-of-files} contains any remaining elements;
14561 the `next-step-expression' resets the @code{list-of-files} to the
14562 @sc{cdr} of itself, so eventually the list will be empty; and the
14563 recursive call calls itself on the shorter list.  The complete
14564 function is shorter than this description!
14565 @findex recursive-lengths-list-many-files
14567 @smallexample
14568 @group
14569 (defun recursive-lengths-list-many-files (list-of-files)
14570   "Return list of lengths of each defun in LIST-OF-FILES."
14571   (if list-of-files                     ; @r{do-again-test}
14572       (append
14573        (lengths-list-file
14574         (expand-file-name (car list-of-files)))
14575        (recursive-lengths-list-many-files
14576         (cdr list-of-files)))))
14577 @end group
14578 @end smallexample
14580 @noindent
14581 In a sentence, the function returns the lengths' list for the first of
14582 the @code{list-of-files} appended to the result of calling itself on
14583 the rest of the @code{list-of-files}.
14585 Here is a test of @code{recursive-lengths-list-many-files}, along with
14586 the results of running @code{lengths-list-file} on each of the files
14587 individually.
14589 Install @code{recursive-lengths-list-many-files} and
14590 @code{lengths-list-file}, if necessary, and then evaluate the
14591 following expressions.  You may need to change the files' pathnames;
14592 those here work when this Info file and the Emacs sources are located
14593 in their customary places.  To change the expressions, copy them to
14594 the @file{*scratch*} buffer, edit them, and then evaluate them.
14596 The results are shown after the @samp{@result{}}.  (These results are
14597 for files from Emacs Version 21.0.100; files from other versions of
14598 Emacs may produce different results.)
14600 @c !!! 21.0.100 lisp sources location here
14601 @smallexample
14602 @group
14603 (cd "/usr/local/share/emacs/21.0.100/")
14605 (lengths-list-file "./lisp/macros.el")
14606      @result{} (273 263 456 90)
14607 @end group
14609 @group
14610 (lengths-list-file "./lisp/mail/mailalias.el")
14611      @result{} (38 32 26 77 174 180 321 198 324)
14612 @end group
14614 @group
14615 (lengths-list-file "./lisp/makesum.el")
14616      @result{} (85 181)
14617 @end group
14619 @group
14620 (recursive-lengths-list-many-files
14621  '("./lisp/macros.el"
14622    "./lisp/mail/mailalias.el"
14623    "./lisp/makesum.el"))
14624        @result{} (273 263 456 90 38 32 26 77 174 180 321 198 324 85 181)
14625 @end group
14626 @end smallexample
14628 The @code{recursive-lengths-list-many-files} function produces the
14629 output we want.
14631 The next step is to prepare the data in the list for display in a graph.
14633 @node Prepare the data,  , Several files recursively, Words in a defun
14634 @section Prepare the Data for Display in a Graph
14636 The @code{recursive-lengths-list-many-files} function returns a list
14637 of numbers.  Each number records the length of a function definition.
14638 What we need to do now is transform this data into a list of numbers
14639 suitable for generating a graph.  The new list will tell how many
14640 functions definitions contain less than 10 words and
14641 symbols, how many contain between 10 and 19 words and symbols, how
14642 many contain between 20 and 29 words and symbols, and so on.
14644 In brief, we need to go through the lengths' list produced by the
14645 @code{recursive-lengths-list-many-files} function and count the number
14646 of defuns within each range of lengths, and produce a list of those
14647 numbers.
14649 Based on what we have done before, we can readily foresee that it
14650 should not be too hard to write a function that `@sc{cdr}s' down the
14651 lengths' list, looks at each element, determines which length range it
14652 is in, and increments a counter for that range.
14654 However, before beginning to write such a function, we should consider
14655 the advantages of sorting the lengths' list first, so the numbers are
14656 ordered from smallest to largest.  First, sorting will make it easier
14657 to count the numbers in each range, since two adjacent numbers will
14658 either be in the same length range or in adjacent ranges.  Second, by
14659 inspecting a sorted list, we can discover the highest and lowest
14660 number, and thereby determine the largest and smallest length range
14661 that we will need.
14663 @menu
14664 * Sorting::                     Sorting lists.
14665 * Files List::                  Making a list of files.
14666 * Counting function definitions::
14667 @end menu
14669 @node Sorting, Files List, Prepare the data, Prepare the data
14670 @subsection Sorting Lists
14671 @findex sort
14673 Emacs contains a function to sort lists, called (as you might guess)
14674 @code{sort}.  The @code{sort} function takes two arguments, the list
14675 to be sorted, and a predicate that determines whether the first of
14676 two list elements is ``less'' than the second.
14678 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
14679 Type Object as an Argument}), a predicate is a function that
14680 determines whether some property is true or false.  The @code{sort}
14681 function will reorder a list according to whatever property the
14682 predicate uses; this means that @code{sort} can be used to sort
14683 non-numeric lists by non-numeric criteria---it can, for example,
14684 alphabetize a list.
14686 @need 1250
14687 The @code{<} function is used when sorting a numeric list.  For example,
14689 @smallexample
14690 (sort '(4 8 21 17 33 7 21 7) '<)
14691 @end smallexample
14693 @need 800
14694 @noindent
14695 produces this:
14697 @smallexample
14698 (4 7 7 8 17 21 21 33)
14699 @end smallexample
14701 @noindent
14702 (Note that in this example, both the arguments are quoted so that the
14703 symbols are not evaluated before being passed to @code{sort} as
14704 arguments.)
14706 Sorting the list returned by the
14707 @code{recursive-lengths-list-many-files} function is straightforward;
14708 it uses the @code{<} function:
14710 @smallexample
14711 @group
14712 (sort
14713  (recursive-lengths-list-many-files
14714   '("../lisp/macros.el"
14715     "../lisp/mailalias.el"
14716     "../lisp/makesum.el"))
14717  '<)
14718 @end group
14719 @end smallexample
14721 @need 800
14722 @noindent
14723 which produces:
14725 @smallexample
14726 (85 86 116 122 154 176 179 265)
14727 @end smallexample
14729 @noindent
14730 (Note that in this example, the first argument to @code{sort} is not
14731 quoted, since the expression must be evaluated so as to produce the
14732 list that is passed to @code{sort}.)
14734 @node Files List, Counting function definitions, Sorting, Prepare the data
14735 @subsection Making a List of Files
14737 The @code{recursive-lengths-list-many-files} function requires a list
14738 of files as its argument.  For our test examples, we constructed such
14739 a list by hand; but the Emacs Lisp source directory is too large for
14740 us to do for that.  Instead, we will write a function to do the job
14741 for us.  In this function, we will use both a @code{while} loop and a
14742 recursive call.
14744 @findex directory-files
14745 We did not have to write a function like this for older versions of
14746 GNU Emacs, since they placed all the @samp{.el} files in one
14747 directory.  Instead, we were able to use the @code{directory-files}
14748 function, which lists the names of files that match a specified
14749 pattern within a single directory.
14751 However, recent versions of Emacs place Emacs Lisp files in
14752 sub-directories of the top level @file{lisp} directory.  This
14753 re-arrangement eases navigation.  For example, all the mail related
14754 files are in a @file{lisp} sub-directory called @file{mail}.  But at
14755 the same time, this arrangement forces us to create a file listing
14756 function that descends into the sub-directories.
14758 @findex files-in-below-directory
14759 We can create this function, called @code{files-in-below-directory},
14760 using familiar functions such as @code{car}, @code{nthcdr}, and
14761 @code{substring} in conjunction with an existing function called
14762 @code{directory-files-and-attributes}.  This latter function not only
14763 lists all the filenames in a directory, including the names
14764 of sub-directories, but also their attributes.
14766 To restate our goal: to create a function that will enable us
14767 to feed filenames to @code{recursive-lengths-list-many-files}
14768 as a list that looks like this (but with more elements):
14770 @smallexample
14771 @group
14772 ("../lisp/macros.el"
14773  "../lisp/mail/rmail.el"
14774  "../lisp/makesum.el")
14775 @end group
14776 @end smallexample
14778 The @code{directory-files-and-attributes} function returns a list of
14779 lists.  Each of the lists within the main list consists of 13
14780 elements.  The first element is a string that contains the name of the
14781 file -- which, in GNU/Linux, may be a `directory file', that is to
14782 say, a file with the special attributes of a directory.  The second
14783 element of the list is @code{t} for a directory, a string
14784 for symbolic link (the string is the name linked to), or @code{nil}.
14786 For example, the first @samp{.el} file in the @file{lisp/} directory
14787 is @file{abbrev.el}.  Its name is
14788 @file{/usr/local/share/emacs/21.0.100/lisp/abbrev.el} and it is not a
14789 directory or a symbolic link.
14791 @need 1000
14792 This is how @code{directory-files-and-attributes} lists that file and
14793 its attributes:
14795 @smallexample
14796 @group
14797 ("/usr/local/share/emacs/21.0.100/lisp/abbrev.el"
14800 1000
14802 @end group
14803 @group
14804 (15019 32380)
14805 (14883 48041)
14806 (15214 49336)
14807 11583
14808 "-rw-rw-r--"
14809 @end group
14810 @group
14812 341385
14813 776)
14814 @end group
14815 @end smallexample
14817 @need 1200
14818 On the other hand, @file{mail/} is a directory within the @file{lisp/}
14819 directory.  The beginning of its listing looks like this:
14821 @smallexample
14822 @group
14823 ("/usr/local/share/emacs/21.0.100/lisp/mail"
14825 @dots{}
14827 @end group
14828 @end smallexample
14830 (Look at the documentation of @code{file-attributes} to learn about
14831 the different attributes.  Bear in mind that the
14832 @code{file-attributes} function does not list the filename, so its
14833 first element is @code{directory-files-and-attributes}'s second
14834 element.)
14836 We will want our new function, @code{files-in-below-directory}, to
14837 list the @samp{.el} files in the directory it is told to check, and in
14838 any directories below that directory.
14840 This gives us a hint on how to construct
14841 @code{files-in-below-directory}:  within a directory, the function
14842 should add @samp{.el} filenames to a list; and if, within a directory,
14843 the function comes upon a sub-directory, it should go into that
14844 sub-directory and repeat its actions.
14846 However, we should note that every directory contains a name that
14847 refers to itself, called @file{.}, (``dot'') and a name that refers to
14848 its parent directory, called @file{..} (``double dot'').  (In
14849 @file{/}, the root directory, @file{..} refers to itself, since
14850 @file{/} has no parent.)  Clearly, we do not want our
14851 @code{files-in-below-directory} function to enter those directories,
14852 since they always lead us, directly or indirectly, to the current
14853 directory.
14855 Consequently, our @code{files-in-below-directory} function must do
14856 several tasks:
14858 @itemize @bullet
14859 @item
14860 Check to see whether it is looking at a filename that ends in
14861 @samp{.el}; and if so, add its name to a list.
14863 @item
14864 Check to see whether it is looking at a filename that is the name of a
14865 directory; and if so,
14867 @itemize @minus
14868 @item
14869 Check to see whether it is looking at @file{.}  or @file{..}; and if
14870 so skip it.
14872 @item
14873 Or else, go into that directory and repeat the process.
14874 @end itemize
14875 @end itemize
14877 Let's write a function definition to do these tasks.  We will use a
14878 @code{while} loop to move from one filename to another within a
14879 directory, checking what needs to be done; and we will use a recursive
14880 call to repeat the actions on each sub-directory.  The recursive
14881 pattern is `accumulate'
14882 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
14883 using @code{append} as the combiner.
14885 @ignore
14886 (directory-files "/usr/local/share/emacs/21.0.100/lisp/" t "\\.el$")
14887 (shell-command "find /usr/local/share/emacs/21.0.100/lisp/ -name '*.el'")
14888 @end ignore
14890 @c  /usr/local/share/emacs/21.0.100/lisp/
14892 @need 800
14893 Here is the function:
14895 @smallexample
14896 @group
14897 (defun files-in-below-directory (directory)
14898   "List the .el files in DIRECTORY and in its sub-directories."
14899   ;; Although the function will be used non-interactively,
14900   ;; it will be easier to test if we make it interactive.
14901   ;; The directory will have a name such as
14902   ;;  "/usr/local/share/emacs/21.0.100/lisp/"
14903   (interactive "DDirectory name: ")
14904 @end group
14905 @group
14906   (let (el-files-list
14907         (current-directory-list
14908          (directory-files-and-attributes directory t)))
14909     ;; while we are in the current directory
14910     (while current-directory-list
14911 @end group
14912 @group
14913       (cond
14914        ;; check to see whether filename ends in `.el'
14915        ;; and if so, append its name to a list.
14916        ((equal ".el" (substring (car (car current-directory-list)) -3))
14917         (setq el-files-list
14918               (cons (car (car current-directory-list)) el-files-list)))
14919 @end group
14920 @group
14921        ;; check whether filename is that of a directory
14922        ((eq t (car (cdr (car current-directory-list))))
14923         ;; decide whether to skip or recurse
14924         (if
14925             (equal (or "." "..")
14926                    (substring (car (car current-directory-list)) -1))
14927             ;; then do nothing if filename is that of
14928             ;;   current directory or parent
14929             ()
14930 @end group
14931 @group
14932           ;; else descend into the directory and repeat the process
14933           (setq el-files-list
14934                 (append
14935                  (files-in-below-directory
14936                   (car (car current-directory-list)))
14937                  el-files-list)))))
14938       ;; move to the next filename in the list; this also
14939       ;; shortens the list so the while loop eventually comes to an end
14940       (setq current-directory-list (cdr current-directory-list)))
14941     ;; return the filenames
14942     el-files-list))
14943 @end group
14944 @end smallexample
14946 @c (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
14948 The @code{files-in-below-directory} @code{directory-files} function
14949 takes one argument, the name of a directory.
14951 @need 1250
14952 Thus, on my system,
14954 @c !!! 21.0.100 lisp sources location here
14955 @smallexample
14956 @group
14957 (length
14958  (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/"))
14959 @end group
14960 @end smallexample
14962 @noindent
14963 tells me that my version 21.0.100 Lisp sources directory contains 754
14964 @samp{.el} files.
14966 @code{files-in-below-directory} returns a list in reverse alphabetical
14967 order.  An expression to sort the list in alphabetical order looks
14968 like this:
14970 @smallexample
14971 @group
14972 (sort
14973  (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
14974  'string-lessp)
14975 @end group
14976 @end smallexample
14978 @ignore
14979 (defun test ()
14980   "Test how long it takes to find lengths of all elisp defuns."
14981   (insert "\n" (current-time-string) "\n")
14982   (sit-for 0)
14983   (sort
14984    (recursive-lengths-list-many-files
14985     '("../lisp/macros.el"
14986       "../lisp/mailalias.el"
14987       "../lisp/makesum.el"))
14988    '<)
14989   (insert (format "%s" (current-time-string))))
14991 @end ignore
14993 @node Counting function definitions,  , Files List, Prepare the data
14994 @subsection Counting function definitions
14996 Our immediate goal is to generate a list that tells us how many
14997 function definitions contain fewer than 10 words and symbols, how many
14998 contain between 10 and 19 words and symbols, how many contain between
14999 20 and 29 words and symbols, and so on.
15001 With a sorted list of numbers, this is easy: count how many elements
15002 of the list are smaller than 10, then, after moving past the numbers
15003 just counted, count how many are smaller than 20, then, after moving
15004 past the numbers just counted, count how many are smaller than 30, and
15005 so on.  Each of the numbers, 10, 20, 30, 40, and the like, is one
15006 larger than the top of that range.  We can call the list of such
15007 numbers the @code{top-of-ranges} list.
15009 @need 1200
15010 If we wished, we could generate this list automatically, but it is
15011 simpler to write a list manually.  Here it is:
15012 @vindex top-of-ranges
15014 @smallexample
15015 @group
15016 (defvar top-of-ranges
15017  '(10  20  30  40  50
15018    60  70  80  90 100
15019   110 120 130 140 150
15020   160 170 180 190 200
15021   210 220 230 240 250
15022   260 270 280 290 300)
15023  "List specifying ranges for `defuns-per-range'.")
15024 @end group
15025 @end smallexample
15027 To change the ranges, we edit this list.
15029 Next, we need to write the function that creates the list of the
15030 number of definitions within each range.  Clearly, this function must
15031 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
15032 as arguments.
15034 The @code{defuns-per-range} function must do two things again and
15035 again: it must count the number of definitions within a range
15036 specified by the current top-of-range value; and it must shift to the
15037 next higher value in the @code{top-of-ranges} list after counting the
15038 number of definitions in the current range.  Since each of these
15039 actions is repetitive, we can use @code{while} loops for the job.
15040 One loop counts the number of definitions in the range defined by the
15041 current top-of-range value, and the other loop selects each of the
15042 top-of-range values in turn.
15044 Several entries of the @code{sorted-lengths} list are counted for each
15045 range; this means that the loop for the @code{sorted-lengths} list
15046 will be inside the loop for the @code{top-of-ranges} list, like a
15047 small gear inside a big gear.
15049 The inner loop counts the number of definitions within the range.  It
15050 is a simple counting loop of the type we have seen before.
15051 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
15052 The true-or-false test of the loop tests whether the value from the
15053 @code{sorted-lengths} list is smaller than the current value of the
15054 top of the range.  If it is, the function increments the counter and
15055 tests the next value from the @code{sorted-lengths} list.
15057 @need 1250
15058 The inner loop looks like this:
15060 @smallexample
15061 @group
15062 (while @var{length-element-smaller-than-top-of-range}
15063   (setq number-within-range (1+ number-within-range))
15064   (setq sorted-lengths (cdr sorted-lengths)))
15065 @end group
15066 @end smallexample
15068 The outer loop must start with the lowest value of the
15069 @code{top-of-ranges} list, and then be set to each of the succeeding
15070 higher values in turn.  This can be done with a loop like this:
15072 @smallexample
15073 @group
15074 (while top-of-ranges
15075   @var{body-of-loop}@dots{}
15076   (setq top-of-ranges (cdr top-of-ranges)))
15077 @end group
15078 @end smallexample
15080 @need 1200
15081 Put together, the two loops look like this:
15083 @smallexample
15084 @group
15085 (while top-of-ranges
15087   ;; @r{Count the number of elements within the current range.}
15088   (while @var{length-element-smaller-than-top-of-range}
15089     (setq number-within-range (1+ number-within-range))
15090     (setq sorted-lengths (cdr sorted-lengths)))
15092   ;; @r{Move to next range.}
15093   (setq top-of-ranges (cdr top-of-ranges)))
15094 @end group
15095 @end smallexample
15097 In addition, in each circuit of the outer loop, Emacs should record
15098 the number of definitions within that range (the value of
15099 @code{number-within-range}) in a list.  We can use @code{cons} for
15100 this purpose.  (@xref{cons, , @code{cons}}.)
15102 The @code{cons} function works fine, except that the list it
15103 constructs will contain the number of definitions for the highest
15104 range at its beginning and the number of definitions for the lowest
15105 range at its end.  This is because @code{cons} attaches new elements
15106 of the list to the beginning of the list, and since the two loops are
15107 working their way through the lengths' list from the lower end first,
15108 the @code{defuns-per-range-list} will end up largest number first.
15109 But we will want to print our graph with smallest values first and the
15110 larger later.  The solution is to reverse the order of the
15111 @code{defuns-per-range-list}.  We can do this using the
15112 @code{nreverse} function, which reverses the order of a list.
15113 @findex nreverse
15115 @need 800
15116 For example,
15118 @smallexample
15119 (nreverse '(1 2 3 4))
15120 @end smallexample
15122 @need 800
15123 @noindent
15124 produces:
15126 @smallexample
15127 (4 3 2 1)
15128 @end smallexample
15130 Note that the @code{nreverse} function is ``destructive''---that is,
15131 it changes the list to which it is applied; this contrasts with the
15132 @code{car} and @code{cdr} functions, which are non-destructive.  In
15133 this case, we do not want the original @code{defuns-per-range-list},
15134 so it does not matter that it is destroyed.  (The @code{reverse}
15135 function provides a reversed copy of a list, leaving the original list
15136 as is.)
15137 @findex reverse
15139 @need 1250
15140 Put all together, the @code{defuns-per-range} looks like this:
15142 @smallexample
15143 @group
15144 (defun defuns-per-range (sorted-lengths top-of-ranges)
15145   "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
15146   (let ((top-of-range (car top-of-ranges))
15147         (number-within-range 0)
15148         defuns-per-range-list)
15149 @end group
15151 @group
15152     ;; @r{Outer loop.}
15153     (while top-of-ranges
15154 @end group
15156 @group
15157       ;; @r{Inner loop.}
15158       (while (and
15159               ;; @r{Need number for numeric test.}
15160               (car sorted-lengths)
15161               (< (car sorted-lengths) top-of-range))
15162 @end group
15164 @group
15165         ;; @r{Count number of definitions within current range.}
15166         (setq number-within-range (1+ number-within-range))
15167         (setq sorted-lengths (cdr sorted-lengths)))
15169       ;; @r{Exit inner loop but remain within outer loop.}
15170 @end group
15172 @group
15173       (setq defuns-per-range-list
15174             (cons number-within-range defuns-per-range-list))
15175       (setq number-within-range 0)      ; @r{Reset count to zero.}
15176 @end group
15178 @group
15179       ;; @r{Move to next range.}
15180       (setq top-of-ranges (cdr top-of-ranges))
15181       ;; @r{Specify next top of range value.}
15182       (setq top-of-range (car top-of-ranges)))
15183 @end group
15185 @group
15186     ;; @r{Exit outer loop and count the number of defuns larger than}
15187     ;; @r{  the largest top-of-range value.}
15188     (setq defuns-per-range-list
15189           (cons
15190            (length sorted-lengths)
15191            defuns-per-range-list))
15192 @end group
15194 @group
15195     ;; @r{Return a list of the number of definitions within each range,}
15196     ;; @r{  smallest to largest.}
15197     (nreverse defuns-per-range-list)))
15198 @end group
15199 @end smallexample
15201 @need 1200
15202 @noindent
15203 The function is straightforward except for one subtle feature.  The
15204 true-or-false test of the inner loop looks like this:
15206 @smallexample
15207 @group
15208 (and (car sorted-lengths)
15209      (< (car sorted-lengths) top-of-range))
15210 @end group
15211 @end smallexample
15213 @need 800
15214 @noindent
15215 instead of like this:
15217 @smallexample
15218 (< (car sorted-lengths) top-of-range)
15219 @end smallexample
15221 The purpose of the test is to determine whether the first item in the
15222 @code{sorted-lengths} list is less than the value of the top of the
15223 range.
15225 The simple version of the test works fine unless the
15226 @code{sorted-lengths} list has a @code{nil} value.  In that case, the
15227 @code{(car sorted-lengths)} expression function returns
15228 @code{nil}.  The @code{<} function cannot compare a number to
15229 @code{nil}, which is an empty list, so Emacs signals an error and
15230 stops the function from attempting to continue to execute.
15232 The @code{sorted-lengths} list always becomes @code{nil} when the
15233 counter reaches the end of the list.  This means that any attempt to
15234 use the @code{defuns-per-range} function with the simple version of
15235 the test will fail.
15237 We solve the problem by using the @code{(car sorted-lengths)}
15238 expression in conjunction with the @code{and} expression.  The
15239 @code{(car sorted-lengths)} expression returns a non-@code{nil}
15240 value so long as the list has at least one number within it, but
15241 returns @code{nil} if the list is empty.  The @code{and} expression
15242 first evaluates the @code{(car sorted-lengths)} expression, and
15243 if it is @code{nil}, returns false @emph{without} evaluating the
15244 @code{<} expression.  But if the @code{(car sorted-lengths)}
15245 expression returns a non-@code{nil} value, the @code{and} expression
15246 evaluates the @code{<} expression, and returns that value as the value
15247 of the @code{and} expression.
15249 @c colon in printed section title causes problem in Info cross reference
15250 This way, we avoid an error.
15251 @iftex
15252 @xref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
15253 Functions}, for more information about @code{and}.
15254 @end iftex
15255 @ifinfo
15256 @xref{forward-paragraph}, for more information about @code{and}.
15257 @end ifinfo
15259 Here is a short test of the @code{defuns-per-range} function.  First,
15260 evaluate the expression that binds (a shortened)
15261 @code{top-of-ranges} list to the list of values, then evaluate the
15262 expression for binding the @code{sorted-lengths} list, and then
15263 evaluate the @code{defuns-per-range} function.
15265 @smallexample
15266 @group
15267 ;; @r{(Shorter list than we will use later.)}
15268 (setq top-of-ranges
15269  '(110 120 130 140 150
15270    160 170 180 190 200))
15272 (setq sorted-lengths
15273       '(85 86 110 116 122 129 154 176 179 200 265 300 300))
15275 (defuns-per-range sorted-lengths top-of-ranges)
15276 @end group
15277 @end smallexample
15279 @need 800
15280 @noindent
15281 The list returned looks like this:
15283 @smallexample
15284 (2 2 2 0 0 1 0 2 0 0 4)
15285 @end smallexample
15287 @noindent
15288 Indeed, there are two elements of the @code{sorted-lengths} list
15289 smaller than 110, two elements between 110 and 119, two elements
15290 between 120 and 129, and so on.  There are four elements with a value
15291 of 200 or larger.
15293 @c The next step is to turn this numbers' list into a graph.
15295 @node Readying a Graph, Emacs Initialization, Words in a defun, Top
15296 @chapter Readying a Graph
15297 @cindex Readying a graph
15298 @cindex Graph prototype
15299 @cindex Prototype graph
15300 @cindex Body of graph
15302 Our goal is to construct a graph showing the numbers of function
15303 definitions of various lengths in the Emacs lisp sources.
15305 As a practical matter, if you were creating a graph, you would
15306 probably use a program such as @code{gnuplot} to do the job.
15307 (@code{gnuplot} is nicely integrated into GNU Emacs.)  In this case,
15308 however, we create one from scratch, and in the process we will
15309 re-acquaint ourselves with some of what we learned before and learn
15310 more.
15312 In this chapter, we will first write a simple graph printing function.
15313 This first definition will be a @dfn{prototype}, a rapidly written
15314 function that enables us to reconnoiter this unknown graph-making
15315 territory.  We will discover dragons, or find that they are myth.
15316 After scouting the terrain, we will feel more confident and enhance
15317 the function to label the axes automatically.
15319 @menu
15320 * Columns of a graph::
15321 * graph-body-print::            How to print the body of a graph.
15322 * recursive-graph-body-print::
15323 * Printed Axes::
15324 * Line Graph Exercise::
15325 @end menu
15327 @node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph
15328 @ifnottex
15329 @unnumberedsec Printing the Columns of a Graph
15330 @end ifnottex
15332 Since Emacs is designed to be flexible and work with all kinds of
15333 terminals, including character-only terminals, the graph will need to
15334 be made from one of the `typewriter' symbols.  An asterisk will do; as
15335 we enhance the graph-printing function, we can make the choice of
15336 symbol a user option.
15338 We can call this function @code{graph-body-print}; it will take a
15339 @code{numbers-list} as its only argument.  At this stage, we will not
15340 label the graph, but only print its body.
15342 The @code{graph-body-print} function inserts a vertical column of
15343 asterisks for each element in the @code{numbers-list}.  The height of
15344 each line is determined by the value of that element of the
15345 @code{numbers-list}.
15347 Inserting columns is a repetitive act; that means that this function can
15348 be written either with a @code{while} loop or recursively.
15350 Our first challenge is to discover how to print a column of asterisks.
15351 Usually, in Emacs, we print characters onto a screen horizontally,
15352 line by line, by typing.  We have two routes we can follow: write our
15353 own column-insertion function or discover whether one exists in Emacs.
15355 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
15356 command.  This command is like the @kbd{C-h a} (command-apropos)
15357 command, except that the latter finds only those functions that are
15358 commands.  The @kbd{M-x apropos} command lists all symbols that match
15359 a regular expression, including functions that are not interactive.
15360 @findex apropos
15362 What we want to look for is some command that prints or inserts
15363 columns.  Very likely, the name of the function will contain either
15364 the word `print' or the word `insert' or the word `column'.
15365 Therefore, we can simply type @kbd{M-x apropos RET
15366 print\|insert\|column RET} and look at the result.  On my system, this
15367 command takes quite some time, and then produces a list of 79
15368 functions and variables.  Scanning down the list, the only function
15369 that looks as if it might do the job is @code{insert-rectangle}.
15371 @need 1200
15372 Indeed, this is the function we want; its documentation says:
15374 @smallexample
15375 @group
15376 insert-rectangle:
15377 Insert text of RECTANGLE with upper left corner at point.
15378 RECTANGLE's first line is inserted at point,
15379 its second line is inserted at a point vertically under point, etc.
15380 RECTANGLE should be a list of strings.
15381 @end group
15382 @end smallexample
15384 We can run a quick test, to make sure it does what we expect of it.
15386 Here is the result of placing the cursor after the
15387 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
15388 (@code{eval-last-sexp}).  The function inserts the strings
15389 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
15390 point.  Also the function returns @code{nil}.
15392 @smallexample
15393 @group
15394 (insert-rectangle '("first" "second" "third"))first
15395                                               second
15396                                               third
15398 @end group
15399 @end smallexample
15401 @noindent
15402 Of course, we won't be inserting the text of the
15403 @code{insert-rectangle} expression itself into the buffer in which we
15404 are making the graph, but will call the function from our program.  We
15405 shall, however, have to make sure that point is in the buffer at the
15406 place where the @code{insert-rectangle} function will insert its
15407 column of strings.
15409 If you are reading this in Info, you can see how this works by
15410 switching to another buffer, such as the @file{*scratch*} buffer,
15411 placing point somewhere in the buffer, typing @kbd{M-:},
15412 typing the @code{insert-rectangle} expression into the minibuffer at
15413 the prompt, and then typing @key{RET}.  This causes Emacs to evaluate
15414 the expression in the minibuffer, but to use as the value of point the
15415 position of point in the @file{*scratch*} buffer.  (@kbd{M-:}
15416 is the keybinding for @code{eval-expression}.)
15418 We find when we do this that point ends up at the end of the last
15419 inserted line---that is to say, this function moves point as a
15420 side-effect.  If we were to repeat the command, with point at this
15421 position, the next insertion would be below and to the right of the
15422 previous insertion.  We don't want this!  If we are going to make a
15423 bar graph, the columns need to be beside each other.
15425 So we discover that each cycle of the column-inserting @code{while}
15426 loop must reposition point to the place we want it, and that place
15427 will be at the top, not the bottom, of the column.  Moreover, we
15428 remember that when we print a graph, we do not expect all the columns
15429 to be the same height.  This means that the top of each column may be
15430 at a different height from the previous one.  We cannot simply
15431 reposition point to the same line each time, but moved over to the
15432 right---or perhaps we can@dots{}
15434 We are planning to make the columns of the bar graph out of asterisks.
15435 The number of asterisks in the column is the number specified by the
15436 current element of the @code{numbers-list}.  We need to construct a
15437 list of asterisks of the right length for each call to
15438 @code{insert-rectangle}.  If this list consists solely of the requisite
15439 number of asterisks, then we will have position point the right number
15440 of lines above the base for the graph to print correctly.  This could
15441 be difficult.
15443 Alternatively, if we can figure out some way to pass
15444 @code{insert-rectangle} a list of the same length each time, then we
15445 can place point on the same line each time, but move it over one
15446 column to the right for each new column.  If we do this, however, some
15447 of the entries in the list passed to @code{insert-rectangle} must be
15448 blanks rather than asterisks.  For example, if the maximum height of
15449 the graph is 5, but the height of the column is 3, then
15450 @code{insert-rectangle} requires an argument that looks like this:
15452 @smallexample
15453 (" " " " "*" "*" "*")
15454 @end smallexample
15456 This last proposal is not so difficult, so long as we can determine
15457 the column height.  There are two ways for us to specify the column
15458 height: we can arbitrarily state what it will be, which would work
15459 fine for graphs of that height; or we can search through the list of
15460 numbers and use the maximum height of the list as the maximum height
15461 of the graph.  If the latter operation were difficult, then the former
15462 procedure would be easiest, but there is a function built into Emacs
15463 that determines the maximum of its arguments.  We can use that
15464 function.  The function is called @code{max} and it returns the
15465 largest of all its arguments, which must be numbers.  Thus, for
15466 example,
15468 @smallexample
15469 (max  3 4 6 5 7 3)
15470 @end smallexample
15472 @noindent
15473 returns 7.  (A corresponding function called @code{min} returns the
15474 smallest of all its arguments.)
15475 @findex max
15476 @findex min
15478 However, we cannot simply call @code{max} on the @code{numbers-list};
15479 the @code{max} function expects numbers as its argument, not a list of
15480 numbers.  Thus, the following expression,
15482 @smallexample
15483 (max  '(3 4 6 5 7 3))
15484 @end smallexample
15486 @need 800
15487 @noindent
15488 produces the following error message;
15490 @smallexample
15491 Wrong type of argument:  number-or-marker-p, (3 4 6 5 7 3)
15492 @end smallexample
15494 @findex apply
15495 We need a function that passes a list of arguments to a function.
15496 This function is @code{apply}.  This function `applies' its first
15497 argument (a function) to its remaining arguments, the last of which
15498 may be a list.
15500 @need 1250
15501 For example,
15503 @smallexample
15504 (apply 'max 3 4 7 3 '(4 8 5))
15505 @end smallexample
15507 @noindent
15508 returns 8.
15510 (Incidentally, I don't know how you would learn of this function
15511 without a book such as this.  It is possible to discover other
15512 functions, like @code{search-forward} or @code{insert-rectangle}, by
15513 guessing at a part of their names and then using @code{apropos}.  Even
15514 though its base in metaphor is clear---`apply' its first argument to
15515 the rest---I doubt a novice would come up with that particular word
15516 when using @code{apropos} or other aid.  Of course, I could be wrong;
15517 after all, the function was first named by someone who had to invent
15518 it.)
15520 The second and subsequent arguments to @code{apply} are optional, so
15521 we can use @code{apply} to call a function and pass the elements of a
15522 list to it, like this, which also returns 8:
15524 @smallexample
15525 (apply 'max '(4 8 5))
15526 @end smallexample
15528 This latter way is how we will use @code{apply}.  The
15529 @code{recursive-lengths-list-many-files} function returns a numbers'
15530 list to which we can apply @code{max} (we could also apply @code{max} to
15531 the sorted numbers' list; it does not matter whether the list is
15532 sorted or not.)
15534 @need 800
15535 Hence, the operation for finding the maximum height of the graph is this:
15537 @smallexample
15538 (setq max-graph-height (apply 'max numbers-list))
15539 @end smallexample
15541 Now we can return to the question of how to create a list of strings
15542 for a column of the graph.  Told the maximum height of the graph
15543 and the number of asterisks that should appear in the column, the
15544 function should return a list of strings for the
15545 @code{insert-rectangle} command to insert.
15547 Each column is made up of asterisks or blanks.  Since the function is
15548 passed the value of the height of the column and the number of
15549 asterisks in the column, the number of blanks can be found by
15550 subtracting the number of asterisks from the height of the column.
15551 Given the number of blanks and the number of asterisks, two
15552 @code{while} loops can be used to construct the list:
15554 @smallexample
15555 @group
15556 ;;; @r{First version.}
15557 (defun column-of-graph (max-graph-height actual-height)
15558   "Return list of strings that is one column of a graph."
15559   (let ((insert-list nil)
15560         (number-of-top-blanks
15561          (- max-graph-height actual-height)))
15562 @end group
15564 @group
15565     ;; @r{Fill in asterisks.}
15566     (while (> actual-height 0)
15567       (setq insert-list (cons "*" insert-list))
15568       (setq actual-height (1- actual-height)))
15569 @end group
15571 @group
15572     ;; @r{Fill in blanks.}
15573     (while (> number-of-top-blanks 0)
15574       (setq insert-list (cons " " insert-list))
15575       (setq number-of-top-blanks
15576             (1- number-of-top-blanks)))
15577 @end group
15579 @group
15580     ;; @r{Return whole list.}
15581     insert-list))
15582 @end group
15583 @end smallexample
15585 If you install this function and then evaluate the following
15586 expression you will see that it returns the list as desired:
15588 @smallexample
15589 (column-of-graph 5 3)
15590 @end smallexample
15592 @need 800
15593 @noindent
15594 returns
15596 @smallexample
15597 (" " " " "*" "*" "*")
15598 @end smallexample
15600 As written, @code{column-of-graph} contains a major flaw: the symbols
15601 used for the blank and for the marked entries in the column are
15602 `hard-coded' as a space and asterisk.  This is fine for a prototype,
15603 but you, or another user, may wish to use other symbols.  For example,
15604 in testing the graph function, you many want to use a period in place
15605 of the space, to make sure the point is being repositioned properly
15606 each time the @code{insert-rectangle} function is called; or you might
15607 want to substitute a @samp{+} sign or other symbol for the asterisk.
15608 You might even want to make a graph-column that is more than one
15609 display column wide.  The program should be more flexible.  The way to
15610 do that is to replace the blank and the asterisk with two variables
15611 that we can call @code{graph-blank} and @code{graph-symbol} and define
15612 those variables separately.
15614 Also, the documentation is not well written.  These considerations
15615 lead us to the second version of the function:
15617 @smallexample
15618 @group
15619 (defvar graph-symbol "*"
15620   "String used as symbol in graph, usually an asterisk.")
15621 @end group
15623 @group
15624 (defvar graph-blank " "
15625   "String used as blank in graph, usually a blank space.
15626 graph-blank must be the same number of columns wide
15627 as graph-symbol.")
15628 @end group
15629 @end smallexample
15631 @noindent
15632 (For an explanation of @code{defvar}, see
15633 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
15635 @smallexample
15636 @group
15637 ;;; @r{Second version.}
15638 (defun column-of-graph (max-graph-height actual-height)
15639   "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
15641 @end group
15642 @group
15643 The graph-symbols are contiguous entries at the end
15644 of the list.
15645 The list will be inserted as one column of a graph.
15646 The strings are either graph-blank or graph-symbol."
15647 @end group
15649 @group
15650   (let ((insert-list nil)
15651         (number-of-top-blanks
15652          (- max-graph-height actual-height)))
15653 @end group
15655 @group
15656     ;; @r{Fill in @code{graph-symbols}.}
15657     (while (> actual-height 0)
15658       (setq insert-list (cons graph-symbol insert-list))
15659       (setq actual-height (1- actual-height)))
15660 @end group
15662 @group
15663     ;; @r{Fill in @code{graph-blanks}.}
15664     (while (> number-of-top-blanks 0)
15665       (setq insert-list (cons graph-blank insert-list))
15666       (setq number-of-top-blanks
15667             (1- number-of-top-blanks)))
15669     ;; @r{Return whole list.}
15670     insert-list))
15671 @end group
15672 @end smallexample
15674 If we wished, we could rewrite @code{column-of-graph} a third time to
15675 provide optionally for a line graph as well as for a bar graph.  This
15676 would not be hard to do.  One way to think of a line graph is that it
15677 is no more than a bar graph in which the part of each bar that is
15678 below the top is blank.  To construct a column for a line graph, the
15679 function first constructs a list of blanks that is one shorter than
15680 the value, then it uses @code{cons} to attach a graph symbol to the
15681 list; then it uses @code{cons} again to attach the `top blanks' to
15682 the list.
15684 It is easy to see how to write such a function, but since we don't
15685 need it, we will not do it.  But the job could be done, and if it were
15686 done, it would be done with @code{column-of-graph}.  Even more
15687 important, it is worth noting that few changes would have to be made
15688 anywhere else.  The enhancement, if we ever wish to make it, is
15689 simple.
15691 Now, finally, we come to our first actual graph printing function.
15692 This prints the body of a graph, not the labels for the vertical and
15693 horizontal axes, so we can call this @code{graph-body-print}.
15695 @node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph
15696 @section The @code{graph-body-print} Function
15697 @findex graph-body-print
15699 After our preparation in the preceding section, the
15700 @code{graph-body-print} function is straightforward.  The function
15701 will print column after column of asterisks and blanks, using the
15702 elements of a numbers' list to specify the number of asterisks in each
15703 column.  This is a repetitive act, which means we can use a
15704 decrementing @code{while} loop or recursive function for the job.  In
15705 this section, we will write the definition using a @code{while} loop.
15707 The @code{column-of-graph} function requires the height of the graph
15708 as an argument, so we should determine and record that as a local variable.
15710 This leads us to the following template for the @code{while} loop
15711 version of this function:
15713 @smallexample
15714 @group
15715 (defun graph-body-print (numbers-list)
15716   "@var{documentation}@dots{}"
15717   (let ((height  @dots{}
15718          @dots{}))
15719 @end group
15721 @group
15722     (while numbers-list
15723       @var{insert-columns-and-reposition-point}
15724       (setq numbers-list (cdr numbers-list)))))
15725 @end group
15726 @end smallexample
15728 @noindent
15729 We need to fill in the slots of the template.
15731 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
15732 determine the height of the graph.
15734 The @code{while} loop will cycle through the @code{numbers-list} one
15735 element at a time.  As it is shortened by the @code{(setq numbers-list
15736 (cdr numbers-list))} expression, the @sc{car} of each instance of the
15737 list is the value of the argument for @code{column-of-graph}.
15739 At each cycle of the @code{while} loop, the @code{insert-rectangle}
15740 function inserts the list returned by @code{column-of-graph}.  Since
15741 the @code{insert-rectangle} function moves point to the lower right of
15742 the inserted rectangle, we need to save the location of point at the
15743 time the rectangle is inserted, move back to that position after the
15744 rectangle is inserted, and then move horizontally to the next place
15745 from which @code{insert-rectangle} is called.
15747 If the inserted columns are one character wide, as they will be if
15748 single blanks and asterisks are used, the repositioning command is
15749 simply @code{(forward-char 1)}; however, the width of a column may be
15750 greater than one.  This means that the repositioning command should be
15751 written @code{(forward-char symbol-width)}.  The @code{symbol-width}
15752 itself is the length of a @code{graph-blank} and can be found using
15753 the expression @code{(length graph-blank)}.  The best place to bind
15754 the @code{symbol-width} variable to the value of the width of graph
15755 column is in the varlist of the @code{let} expression.
15757 @need 1250
15758 These considerations lead to the following function definition:
15760 @smallexample
15761 @group
15762 (defun graph-body-print (numbers-list)
15763   "Print a bar graph of the NUMBERS-LIST.
15764 The numbers-list consists of the Y-axis values."
15766   (let ((height (apply 'max numbers-list))
15767         (symbol-width (length graph-blank))
15768         from-position)
15769 @end group
15771 @group
15772     (while numbers-list
15773       (setq from-position (point))
15774       (insert-rectangle
15775        (column-of-graph height (car numbers-list)))
15776       (goto-char from-position)
15777       (forward-char symbol-width)
15778 @end group
15779 @group
15780       ;; @r{Draw graph column by column.}
15781       (sit-for 0)
15782       (setq numbers-list (cdr numbers-list)))
15783 @end group
15784 @group
15785     ;; @r{Place point for X axis labels.}
15786     (forward-line height)
15787     (insert "\n")
15789 @end group
15790 @end smallexample
15792 @noindent
15793 The one unexpected expression in this function is the
15794 @w{@code{(sit-for 0)}} expression in the @code{while} loop.  This
15795 expression makes the graph printing operation more interesting to
15796 watch than it would be otherwise.  The expression causes Emacs to
15797 `sit' or do nothing for a zero length of time and then redraw the
15798 screen.  Placed here, it causes Emacs to redraw the screen column by
15799 column.  Without it, Emacs would not redraw the screen until the
15800 function exits.
15802 We can test @code{graph-body-print} with a short list of numbers.
15804 @enumerate
15805 @item
15806 Install @code{graph-symbol}, @code{graph-blank},
15807 @code{column-of-graph}, which are in
15808 @iftex
15809 @ref{Readying a Graph, , Readying a Graph},
15810 @end iftex
15811 @ifinfo
15812 @ref{Columns of a graph},
15813 @end ifinfo
15814 and @code{graph-body-print}.
15816 @need 800
15817 @item
15818 Copy the following expression:
15820 @smallexample
15821 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
15822 @end smallexample
15824 @item
15825 Switch to the @file{*scratch*} buffer and place the cursor where you
15826 want the graph to start.
15828 @item
15829 Type @kbd{M-:} (@code{eval-expression}).
15831 @item
15832 Yank the @code{graph-body-print} expression into the minibuffer
15833 with @kbd{C-y} (@code{yank)}.
15835 @item
15836 Press @key{RET} to evaluate the @code{graph-body-print} expression.
15837 @end enumerate
15839 @need 800
15840 Emacs will print a graph like this:
15842 @smallexample
15843 @group
15844                     *
15845                 *   **
15846                 *  ****
15847                *** ****
15848               ********* *
15849              ************
15850             *************
15851 @end group
15852 @end smallexample
15854 @node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph
15855 @section The @code{recursive-graph-body-print} Function
15856 @findex recursive-graph-body-print
15858 The @code{graph-body-print} function may also be written recursively.
15859 The recursive solution is divided into two parts: an outside `wrapper'
15860 that uses a @code{let} expression to determine the values of several
15861 variables that need only be found once, such as the maximum height of
15862 the graph, and an inside function that is called recursively to print
15863 the graph.
15865 @need 1250
15866 The `wrapper' is uncomplicated:
15868 @smallexample
15869 @group
15870 (defun recursive-graph-body-print (numbers-list)
15871   "Print a bar graph of the NUMBERS-LIST.
15872 The numbers-list consists of the Y-axis values."
15873   (let ((height (apply 'max numbers-list))
15874         (symbol-width (length graph-blank))
15875         from-position)
15876     (recursive-graph-body-print-internal
15877      numbers-list
15878      height
15879      symbol-width)))
15880 @end group
15881 @end smallexample
15883 The recursive function is a little more difficult.  It has four parts:
15884 the `do-again-test', the printing code, the recursive call, and the
15885 `next-step-expression'.  The `do-again-test' is an @code{if}
15886 expression that determines whether the @code{numbers-list} contains
15887 any remaining elements; if it does, the function prints one column of
15888 the graph using the printing code and calls itself again.  The
15889 function calls itself again according to the value produced by the
15890 `next-step-expression' which causes the call to act on a shorter
15891 version of the @code{numbers-list}.
15893 @smallexample
15894 @group
15895 (defun recursive-graph-body-print-internal
15896   (numbers-list height symbol-width)
15897   "Print a bar graph.
15898 Used within recursive-graph-body-print function."
15899 @end group
15901 @group
15902   (if numbers-list
15903       (progn
15904         (setq from-position (point))
15905         (insert-rectangle
15906          (column-of-graph height (car numbers-list)))
15907 @end group
15908 @group
15909         (goto-char from-position)
15910         (forward-char symbol-width)
15911         (sit-for 0)     ; @r{Draw graph column by column.}
15912         (recursive-graph-body-print-internal
15913          (cdr numbers-list) height symbol-width))))
15914 @end group
15915 @end smallexample
15917 @need 1250
15918 After installation, this expression can be tested; here is a sample:
15920 @smallexample
15921 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
15922 @end smallexample
15924 @need 800
15925 Here is what @code{recursive-graph-body-print} produces:
15927 @smallexample
15928 @group
15929                 *
15930                **   *
15931               ****  *
15932               **** ***
15933             * *********
15934             ************
15935             *************
15936 @end group
15937 @end smallexample
15939 Either of these two functions, @code{graph-body-print} or
15940 @code{recursive-graph-body-print}, create the body of a graph.
15942 @node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph
15943 @section Need for Printed Axes
15945 A graph needs printed axes, so you can orient yourself.  For a do-once
15946 project, it may be reasonable to draw the axes by hand using Emacs'
15947 Picture mode; but a graph drawing function may be used more than once.
15949 For this reason, I have written enhancements to the basic
15950 @code{print-graph-body} function that automatically print labels for
15951 the horizontal and vertical axes.  Since the label printing functions
15952 do not contain much new material, I have placed their description in
15953 an appendix.  @xref{Full Graph, , A Graph with Labelled Axes}.
15955 @node Line Graph Exercise,  , Printed Axes, Readying a Graph
15956 @section Exercise
15958 Write a line graph version of the graph printing functions.
15960 @node Emacs Initialization, Debugging, Readying a Graph, Top
15961 @chapter Your @file{.emacs} File
15962 @cindex @file{.emacs} file
15963 @cindex Customizing your @file{.emacs} file
15964 @cindex Initialization file
15966 ``You don't have to like Emacs to like it'' -- this seemingly
15967 paradoxical statement is the secret of GNU Emacs.  The plain, `out of
15968 the box' Emacs is a generic tool.  Most people who use it, customize
15969 it to suit themselves.
15971 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
15972 expressions in Emacs Lisp you can change or extend Emacs.
15974 @menu
15975 * Default Configuration::
15976 * Site-wide Init::              You can write site-wide init files.
15977 * defcustom::                   Emacs will write code for you.
15978 * Beginning a .emacs File::     How to write a @code{.emacs file}.
15979 * Text and Auto-fill::          Automatically wrap lines.
15980 * Mail Aliases::                Use abbreviations for email addresses.
15981 * Indent Tabs Mode::            Don't use tabs with @TeX{}
15982 * Keybindings::                 Create some personal keybindings.
15983 * Keymaps::                     More about key binding.
15984 * Loading Files::               Load (i.e., evaluate) files automatically.
15985 * Autoload::                    Make functions available.
15986 * Simple Extension::            Define a function; bind it to a key.
15987 * X11 Colors::                  Colors in version 19 in X.
15988 * Miscellaneous::
15989 * Mode Line::                   How to customize your mode line.
15990 @end menu
15992 @node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
15993 @ifnottex
15994 @unnumberedsec Emacs' Default Configuration
15995 @end ifnottex
15997 There are those who appreciate Emacs' default configuration.  After
15998 all, Emacs starts you in C mode when you edit a C file, starts you in
15999 Fortran mode when you edit a Fortran file, and starts you in
16000 Fundamental mode when you edit an unadorned file.  This all makes
16001 sense, if you do not know who is going to use Emacs.  Who knows what a
16002 person hopes to do with an unadorned file?  Fundamental mode is the
16003 right default for such a file, just as C mode is the right default for
16004 editing C code.  But when you do know who is going to use Emacs---you,
16005 yourself---then it makes sense to customize Emacs.
16007 For example, I seldom want Fundamental mode when I edit an
16008 otherwise undistinguished file; I want Text mode.  This is why I
16009 customize Emacs: so it suits me.
16011 You can customize and extend Emacs by writing or adapting a
16012 @file{~/.emacs} file.  This is your personal initialization file; its
16013 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
16014 may also add @file{.el} to @file{~/.emacs} and call it a
16015 @file{~/.emacs.el} file.  In the past, you were forbidden to type the
16016 extra keystrokes that the name @file{~/.emacs.el} requires, but now
16017 you may.  The new format is consistent with the Emacs Lisp file
16018 naming conventions; the old format saves typing.}
16020 A @file{~/.emacs} file contains Emacs Lisp code.  You can write this
16021 code yourself; or you can use Emacs' @code{customize} feature to write
16022 the code for you.  You can combine your own expressions and
16023 auto-written Customize expressions in your @file{.emacs} file.
16025 (I myself prefer to write my own expressions, except for those,
16026 particularly fonts, that I find easier to manipulate using the
16027 @code{customize} command.  I combine the two methods.)
16029 Most of this chapter is about writing expressions yourself.  It
16030 describes a simple @file{.emacs} file; for more information, see
16031 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
16032 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
16033 Manual}.
16035 @node Site-wide Init, defcustom, Default Configuration, Emacs Initialization
16036 @section Site-wide Initialization Files
16038 @cindex @file{default.el} init file
16039 @cindex @file{site-init.el} init file
16040 @cindex @file{site-load.el} init file
16041 In addition to your personal initialization file, Emacs automatically
16042 loads various site-wide initialization files, if they exist.  These
16043 have the same form as your @file{.emacs} file, but are loaded by
16044 everyone.
16046 Two site-wide initialization files, @file{site-load.el} and
16047 @file{site-init.el}, are loaded into Emacs and then `dumped' if a
16048 `dumped' version of Emacs is created, as is most common.  (Dumped
16049 copies of Emacs load more quickly.  However, once a file is loaded and
16050 dumped, a change to it does not lead to a change in Emacs unless you
16051 load it yourself or re-dump Emacs.  @xref{Building Emacs, , Building
16052 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
16053 @file{INSTALL} file.)
16055 Three other site-wide initialization files are loaded automatically
16056 each time you start Emacs, if they exist.  These are
16057 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
16058 file, and @file{default.el}, and the terminal type file, which are both
16059 loaded @emph{after} your @file{.emacs} file.
16061 Settings and definitions in your @file{.emacs} file will overwrite
16062 conflicting settings and definitions in a @file{site-start.el} file,
16063 if it exists; but the settings and definitions in a @file{default.el}
16064 or terminal type file will overwrite those in your @file{.emacs} file.
16065 (You can prevent interference from a terminal type file by setting
16066 @code{term-file-prefix} to @code{nil}.  @xref{Simple Extension, , A
16067 Simple Extension}.)
16069 @c Rewritten to avoid overfull hbox.
16070 The @file{INSTALL} file that comes in the distribution contains
16071 descriptions of the @file{site-init.el} and @file{site-load.el} files.
16073 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
16074 control loading.  These files are in the @file{lisp} directory of the
16075 Emacs distribution and are worth perusing.
16077 The @file{loaddefs.el} file contains a good many suggestions as to
16078 what to put into your own @file{.emacs} file, or into a site-wide
16079 initialization file.
16081 @node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization
16082 @section Specifying Variables using @code{defcustom}
16083 @findex defcustom
16085 You can specify variables using @code{defcustom} so that you and
16086 others can then use Emacs' @code{customize} feature to set their
16087 values.  (You cannot use @code{customize} to write function
16088 definitions; but you can write @code{defuns} in your @file{.emacs}
16089 file.  Indeed, you can write any Lisp expression in your @file{.emacs}
16090 file.)
16092 The @code{customize} feature depends on the @code{defcustom} special
16093 form.  Although you can use @code{defvar} or @code{setq} for variables
16094 that users set, the @code{defcustom} special form is designed for the
16095 job.
16097 You can use your knowledge of @code{defvar} for writing the
16098 first three arguments for @code{defcustom}.  The first argument to
16099 @code{defcustom} is the name of the variable.  The second argument is
16100 the variable's initial value, if any; and this value is set only if
16101 the value has not already been set.  The third argument is the
16102 documentation.
16104 The fourth and subsequent arguments to @code{defcustom} specify types
16105 and options; these are not featured in @code{defvar}.  (These
16106 arguments are optional.)
16108 Each of these arguments consists of a keyword followed by a value.
16109 Each keyword starts with the colon character @samp{:}.
16111 @need 1250
16112 For example, the customizable user option variable
16113 @code{text-mode-hook} looks like this:
16115 @smallexample
16116 @group
16117 (defcustom text-mode-hook nil
16118   "Normal hook run when entering Text mode and many related modes."
16119   :type 'hook
16120   :options '(turn-on-auto-fill flyspell-mode)
16121   :group 'data)
16122 @end group
16123 @end smallexample
16125 @noindent
16126 The name of the variable is @code{text-mode-hook}; it has no default
16127 value; and its documentation string tells you what it does.
16129 The @code{:type} keyword tells Emacs the kind of data to which
16130 @code{text-mode-hook} should be set and how to display the value in a
16131 Customization buffer.
16133 The @code{:options} keyword specifies a suggested list of values for
16134 the variable.  Currently, you can use @code{:options} only for a hook.
16135 The list is only a suggestion; it is not exclusive; a person who sets
16136 the variable may set it to other values; the list shown following the
16137 @code{:options} keyword is intended to offer convenient choices to a
16138 user.
16140 Finally, the @code{:group} keyword tells the Emacs Customization
16141 command in which group the variable is located.  This tells where to
16142 find it.
16144 For more information, see @ref{Customization, , Writing Customization
16145 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
16147 Consider @code{text-mode-hook} as an example.
16149 There are two ways to customize this variable.  You can use the
16150 customization command or write the appropriate expressions yourself.
16152 @need 800
16153 Using the customization command,  you can type:
16155 @smallexample
16156 M-x customize
16157 @end smallexample
16159 @noindent
16160 and find that the group for editing files of data is called `data'.
16161 Enter that group.  Text Mode Hook is the first member.  You can click
16162 on its various options to set the values.  After you click on the
16163 button to
16165 @smallexample
16166 Save for Future Sessions
16167 @end smallexample
16169 @noindent
16170 Emacs will write an expression into your @file{.emacs} file.
16171 It will look like this:
16173 @smallexample
16174 @group
16175 (custom-set-variables
16176   ;; custom-set-variables was added by Custom --
16177   ;;                           don't edit or cut/paste it!
16178   ;; Your init file should contain only one such instance.
16179  '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
16180 @end group
16181 @end smallexample
16183 @noindent
16184 (The @code{text-mode-hook-identify} function tells
16185 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.)
16187 In spite of the warning, you certainly may edit, cut, and paste the
16188 expression!  I do all time.  The purpose of the warning is to scare
16189 those who do not know what they are doing, so they do not
16190 inadvertently generate an error.
16192 The @code{custom-set-variables} function works somewhat differently
16193 than a @code{setq}.  While I have never learned the differences, I do
16194 modify the @code{custom-set-variables} expressions in my @file{.emacs}
16195 file by hand:  I make the changes in what appears to me to be a
16196 reasonable manner and have not had any problems.  Others prefer to use
16197 the Customization command and let Emacs do the work for them.
16199 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
16200 This function sets the various font faces.  Over time, I have set a
16201 considerable number of faces.  Some of the time, I re-set them using
16202 @code{customize}; other times, I simply edit the
16203 @code{custom-set-faces} expression in my @file{.emacs} file itself.
16205 The second way to customize your @code{text-mode-hook} is to set it
16206 yourself in your @file{.emacs} file using code that has nothing to do
16207 with the @code{custom-set-@dots{}} functions.
16209 @need 800
16210 When you do this, and later use @code{customize}, you will see a
16211 message that says
16213 @smallexample
16214 this option has been changed outside the customize buffer.
16215 @end smallexample
16217 @need 800
16218 This message is only a warning.  If you click on the button to
16220 @smallexample
16221 Save for Future Sessions
16222 @end smallexample
16224 @noindent
16225 Emacs will write a @code{custom-set-@dots{}} expression near the end
16226 of your @file{.emacs} file that will be evaluated after your
16227 hand-written expression.  It will, therefore, overrule your
16228 hand-written expression.  No harm will be done.  When you do this,
16229 however, be careful to remember which expression is active; if you
16230 forget, you may confuse yourself.
16232 So long as you remember where the values are set, you will have no
16233 trouble.  In any event, the values are always set in your
16234 initialization file, which is usually called @file{.emacs}.
16236 I myself use @code{customize} for hardly anything.  Mostly, I write
16237 expressions myself.
16239 @node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization
16240 @section Beginning a @file{.emacs} File
16241 @cindex @file{.emacs} file, beginning of
16243 When you start Emacs, it loads your @file{.emacs} file unless you tell
16244 it not to by specifying @samp{-q} on the command line.  (The
16245 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
16247 A @file{.emacs} file contains Lisp expressions.  Often, these are no
16248 more than expressions to set values; sometimes they are function
16249 definitions.
16251 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
16252 Manual}, for a short description of initialization files.
16254 This chapter goes over some of the same ground, but is a walk among
16255 extracts from a complete, long-used @file{.emacs} file---my own.
16257 The first part of the file consists of comments: reminders to myself.
16258 By now, of course, I remember these things, but when I started, I did
16259 not.
16261 @need 1200
16262 @smallexample
16263 @group
16264 ;;;; Bob's .emacs file
16265 ; Robert J. Chassell
16266 ; 26 September 1985
16267 @end group
16268 @end smallexample
16270 @noindent
16271 Look at that date!  I started this file a long time ago.  I have been
16272 adding to it ever since.
16274 @smallexample
16275 @group
16276 ; Each section in this file is introduced by a
16277 ; line beginning with four semicolons; and each
16278 ; entry is introduced by a line beginning with
16279 ; three semicolons.
16280 @end group
16281 @end smallexample
16283 @noindent
16284 This describes the usual conventions for comments in Emacs Lisp.
16285 Everything on a line that follows a semicolon is a comment.  Two,
16286 three, and four semicolons are used as section and subsection
16287 markers.  (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference
16288 Manual}, for more about comments.)
16290 @smallexample
16291 @group
16292 ;;;; The Help Key
16293 ; Control-h is the help key;
16294 ; after typing control-h, type a letter to
16295 ; indicate the subject about which you want help.
16296 ; For an explanation of the help facility,
16297 ; type control-h two times in a row.
16298 @end group
16299 @end smallexample
16301 @noindent
16302 Just remember: type @kbd{C-h} two times for help.
16304 @smallexample
16305 @group
16306 ; To find out about any mode, type control-h m
16307 ; while in that mode.  For example, to find out
16308 ; about mail mode, enter mail mode and then type
16309 ; control-h m.
16310 @end group
16311 @end smallexample
16313 @noindent
16314 `Mode help', as I call this, is very helpful.  Usually, it tells you
16315 all you need to know.
16317 Of course, you don't need to include comments like these in your
16318 @file{.emacs} file.  I included them in mine because I kept forgetting
16319 about Mode help or the conventions for comments---but I was able to
16320 remember to look here to remind myself.
16322 @node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization
16323 @section Text and Auto Fill Mode
16325 Now we come to the part that `turns on' Text mode and
16326 Auto Fill mode.
16328 @smallexample
16329 @group
16330 ;;; Text mode and Auto Fill mode
16331 ; The next three lines put Emacs into Text mode
16332 ; and Auto Fill mode, and are for writers who
16333 ; want to start writing prose rather than code.
16335 (setq default-major-mode 'text-mode)
16336 (add-hook 'text-mode-hook 'text-mode-hook-identify)
16337 (add-hook 'text-mode-hook 'turn-on-auto-fill)
16338 @end group
16339 @end smallexample
16341 Here is the first part of this @file{.emacs} file that does something
16342 besides remind a forgetful human!
16344 The first of the two lines in parentheses tells Emacs to turn on Text
16345 mode when you find a file, @emph{unless} that file should go into some
16346 other mode, such as C mode.
16348 @cindex Per-buffer, local variables list
16349 @cindex Local variables list, per-buffer,
16350 @cindex Automatic mode selection
16351 @cindex Mode selection, automatic
16352 When Emacs reads a file, it looks at the extension to the file name,
16353 if any.  (The extension is the part that comes after a @samp{.}.)  If
16354 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
16355 on C mode.  Also, Emacs looks at first nonblank line of the file; if
16356 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode.  Emacs
16357 possesses a list of extensions and specifications that it uses
16358 automatically.  In addition, Emacs looks near the last page for a
16359 per-buffer, ``local variables list'', if any.
16361 @ifinfo
16362 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
16363 Emacs Manual}.
16365 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
16366 Manual}.
16367 @end ifinfo
16368 @iftex
16369 See sections ``How Major Modes are Chosen'' and ``Local Variables in
16370 Files'' in @cite{The GNU Emacs Manual}.
16371 @end iftex
16373 Now, back to the @file{.emacs} file.
16375 @need 800
16376 Here is the line again; how does it work?
16378 @cindex Text Mode turned on
16379 @smallexample
16380 (setq default-major-mode 'text-mode)
16381 @end smallexample
16383 @noindent
16384 This line is a short, but complete Emacs Lisp expression.
16386 We are already familiar with @code{setq}.  It sets the following variable,
16387 @code{default-major-mode}, to the subsequent value, which is
16388 @code{text-mode}.  The single quote mark before @code{text-mode} tells
16389 Emacs to deal directly with the @code{text-mode} variable, not with
16390 whatever it might stand for.  @xref{set & setq, , Setting the Value of
16391 a Variable}, for a reminder of how @code{setq} works.  The main point
16392 is that there is no difference between the procedure you use to set
16393 a value in your @file{.emacs} file and the procedure you use anywhere
16394 else in Emacs.
16396 @need 800
16397 Here are the next two lines:
16399 @cindex Auto Fill mode turned on
16400 @findex add-hook
16401 @smallexample
16402 (add-hook 'text-mode-hook 'text-mode-hook-identify)
16403 (add-hook 'text-mode-hook 'turn-on-auto-fill)
16404 @end smallexample
16406 @noindent
16407 In these two lines, the @code{add-hook} command first adds
16408 @code{text-mode-hook-identify} to the variable called
16409 @code{text-mode-hook} and then adds @code{turn-on-auto-fill} to the
16410 variable.
16412 @code{turn-on-auto-fill} is the name of a program, that, you guessed
16413 it!, turns on Auto Fill mode.  @code{text-mode-hook-identify} is a
16414 function that tells @code{toggle-text-mode-auto-fill} which buffers
16415 are in Text mode.
16417 Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
16418 onto Text mode.  So every time Emacs turns on Text mode, Emacs also
16419 turns on Auto Fill mode.
16421 In brief, the first line causes Emacs to enter Text mode when you edit
16422 a file, unless the file name extension, first non-blank line, or local
16423 variables tell Emacs otherwise.
16425 Text mode among other actions, sets the syntax table to work
16426 conveniently for writers.  In Text mode, Emacs considers an apostrophe
16427 as part of a word like a letter; but Emacs does not consider a period
16428 or a space as part of a word.  Thus, @kbd{M-f} moves you over
16429 @samp{it's}.  On the other hand, in C mode, @kbd{M-f} stops just after
16430 the @samp{t} of @samp{it's}.
16432 The second and third lines causes Emacs to turn on Auto Fill mode when
16433 it turns on Text mode.  In Auto Fill mode, Emacs automatically breaks
16434 a line that is too wide and brings the excessively wide part of the
16435 line down to the next line.  Emacs breaks lines between words, not
16436 within them.
16438 When Auto Fill mode is turned off, lines continue to the right as you
16439 type them.  Depending on how you set the value of
16440 @code{truncate-lines}, the words you type either disappear off the
16441 right side of the screen, or else are shown, in a rather ugly and
16442 unreadable manner, as a continuation line on the screen.
16444 @need 1250
16445 In addition, in this part of my @file{.emacs} file, I tell the Emacs
16446 fill commands to insert two spaces after a colon:
16448 @smallexample
16449 (setq colon-double-space t)
16450 @end smallexample
16452 @node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization
16453 @section Mail Aliases
16455 Here is a @code{setq} that `turns on' mail aliases, along with more
16456 reminders.
16458 @smallexample
16459 @group
16460 ;;; Mail mode
16461 ; To enter mail mode, type `C-x m'
16462 ; To enter RMAIL (for reading mail),
16463 ; type `M-x rmail'
16465 (setq mail-aliases t)
16466 @end group
16467 @end smallexample
16469 @cindex Mail aliases
16470 @noindent
16471 This @code{setq} command sets the value of the variable
16472 @code{mail-aliases} to @code{t}.  Since @code{t} means true, the line
16473 says, in effect, ``Yes, use mail aliases.''
16475 Mail aliases are convenient short names for long email addresses or
16476 for lists of email addresses.  The file where you keep your `aliases'
16477 is @file{~/.mailrc}.  You write an alias like this:
16479 @smallexample
16480 alias geo george@@foobar.wiz.edu
16481 @end smallexample
16483 @noindent
16484 When you write a message to George, address it to @samp{geo}; the
16485 mailer will automatically expand @samp{geo} to the full address.
16487 @node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization
16488 @section Indent Tabs Mode
16489 @cindex Tabs, preventing
16490 @findex indent-tabs-mode
16492 By default, Emacs inserts tabs in place of multiple spaces when it
16493 formats a region.  (For example, you might indent many lines of text
16494 all at once with the @code{indent-region} command.)  Tabs look fine on
16495 a terminal or with ordinary printing, but they produce badly indented
16496 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
16498 @need 1250
16499 The following turns off Indent Tabs mode:
16501 @smallexample
16502 @group
16503 ;;; Prevent Extraneous Tabs
16504 (setq-default indent-tabs-mode nil)
16505 @end group
16506 @end smallexample
16508 Note that this line uses @code{setq-default} rather than the
16509 @code{setq} command that we have seen before.  The @code{setq-default}
16510 command sets values only in buffers that do not have their own local
16511 values for the variable.
16513 @ifinfo
16514 @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}.
16516 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
16517 Manual}.
16518 @end ifinfo
16519 @iftex
16520 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
16521 Files'' in @cite{The GNU Emacs Manual}.
16522 @end iftex
16524 @node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization
16525 @section Some Keybindings
16527 Now for some personal keybindings:
16529 @smallexample
16530 @group
16531 ;;; Compare windows
16532 (global-set-key "\C-cw" 'compare-windows)
16533 @end group
16534 @end smallexample
16536 @findex compare-windows
16537 @code{compare-windows} is a nifty command that compares the text in
16538 your current window with text in the next window.  It makes the
16539 comparison by starting at point in each window, moving over text in
16540 each window as far as they match.  I use this command all the time.
16542 This also shows how to set a key globally, for all modes.
16544 @cindex Setting a key globally
16545 @cindex Global set key
16546 @cindex Key setting globally
16547 @findex global-set-key
16548 The command is @code{global-set-key}.  It is followed by the
16549 keybinding.  In a @file{.emacs} file, the keybinding is written as
16550 shown: @code{\C-c} stands for `control-c', which means `press the
16551 control key and the @kbd{c} key at the same time'.  The @code{w} means
16552 `press the @kbd{w} key'.  The keybinding is surrounded by double
16553 quotation marks.  In documentation, you would write this as @kbd{C-c
16554 w}.  (If you were binding a @key{META} key, such as @kbd{M-c}, rather
16555 than a @key{CTL} key, you would write @code{\M-c}.  @xref{Init
16556 Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU Emacs
16557 Manual}, for details.)
16559 The command invoked by the keys is @code{compare-windows}.  Note that
16560 @code{compare-windows} is preceded by a single quote; otherwise, Emacs
16561 would first try to evaluate the symbol to determine its value.
16563 These three things, the double quotation marks, the backslash before
16564 the @samp{C}, and the single quote mark are necessary parts of
16565 keybinding that I tend to forget.  Fortunately, I have come to
16566 remember that I should look at my existing @file{.emacs} file, and
16567 adapt what is there.
16569 As for the keybinding itself: @kbd{C-c w}.  This combines the prefix
16570 key, @kbd{C-c}, with a single character, in this case, @kbd{w}.  This
16571 set of keys, @kbd{C-c} followed by a single character, is strictly
16572 reserved for individuals' own use.  (I call these `own' keys, since
16573 these are for my own use.)  You should always be able to create such a
16574 keybinding for your own use without stomping on someone else's
16575 keybinding.  If you ever write an extension to Emacs, please avoid
16576 taking any of these keys for public use.  Create a key like @kbd{C-c
16577 C-w} instead.  Otherwise, we will run out of `own' keys.
16579 @need 1250
16580 Here is another keybinding, with a comment:
16582 @smallexample
16583 @group
16584 ;;; Keybinding for `occur'
16585 ; I use occur a lot, so let's bind it to a key:
16586 (global-set-key "\C-co" 'occur)
16587 @end group
16588 @end smallexample
16590 @findex occur
16591 The @code{occur} command shows all the lines in the current buffer
16592 that contain a match for a regular expression.  Matching lines are
16593 shown in a buffer called @file{*Occur*}.  That buffer serves as a menu
16594 to jump to occurrences.
16596 @findex global-unset-key
16597 @cindex Unbinding key
16598 @cindex Key unbinding
16599 @need 1250
16600 Here is how to unbind a key, so it does not
16601 work:
16603 @smallexample
16604 @group
16605 ;;; Unbind `C-x f'
16606 (global-unset-key "\C-xf")
16607 @end group
16608 @end smallexample
16610 There is a reason for this unbinding: I found I inadvertently typed
16611 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}.  Rather than find a
16612 file, as I intended, I accidentally set the width for filled text,
16613 almost always to a width I did not want.  Since I hardly ever reset my
16614 default width, I simply unbound the key.
16616 @findex list-buffers, @r{rebound}
16617 @findex buffer-menu, @r{bound to key}
16618 @need 1250
16619 The following rebinds an existing key:
16621 @smallexample
16622 @group
16623 ;;; Rebind `C-x C-b' for `buffer-menu'
16624 (global-set-key "\C-x\C-b" 'buffer-menu)
16625 @end group
16626 @end smallexample
16628 By default, @kbd{C-x C-b} runs the
16629 @code{list-buffers} command.  This command lists
16630 your buffers in @emph{another} window.  Since I
16631 almost always want to do something in that
16632 window, I prefer the  @code{buffer-menu}
16633 command, which not only lists the buffers,
16634 but moves point into that window.
16636 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
16637 @section Keymaps
16638 @cindex Keymaps
16639 @cindex Rebinding keys
16641 Emacs uses @dfn{keymaps} to record which keys call which commands.
16642 When you use @code{global-set-key} to set the keybinding for a single
16643 command in all parts of Emacs, you are specifying the keybinding in
16644 @code{current-global-map}.
16646 Specific modes, such as C mode or Text mode, have their own keymaps;
16647 the mode-specific keymaps override the global map that is shared by
16648 all buffers.
16650 The @code{global-set-key} function binds, or rebinds, the global
16651 keymap.  For example, the following binds the key @kbd{C-x C-b} to the
16652 function @code{buffer-menu}:
16654 @smallexample
16655 (global-set-key "\C-x\C-b" 'buffer-menu)
16656 @end smallexample
16658 Mode-specific keymaps are bound using the @code{define-key} function,
16659 which takes a specific keymap as an argument, as well as the key and
16660 the command.  For example, my @file{.emacs} file contains the
16661 following expression to bind the @code{texinfo-insert-@@group} command
16662 to @kbd{C-c C-c g}:
16664 @smallexample
16665 @group
16666 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
16667 @end group
16668 @end smallexample
16670 @noindent
16671 The @code{texinfo-insert-@@group} function itself is a little extension
16672 to Texinfo mode that inserts @samp{@@group} into a Texinfo file.  I
16673 use this command all the time and prefer to type the three strokes
16674 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
16675 (@samp{@@group} and its matching @samp{@@end group} are commands that
16676 keep all enclosed text together on one page; many multi-line examples
16677 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
16679 @need 1250
16680 Here is the @code{texinfo-insert-@@group} function definition:
16682 @smallexample
16683 @group
16684 (defun texinfo-insert-@@group ()
16685   "Insert the string @@group in a Texinfo buffer."
16686   (interactive)
16687   (beginning-of-line)
16688   (insert "@@group\n"))
16689 @end group
16690 @end smallexample
16692 (Of course, I could have used Abbrev mode to save typing, rather than
16693 write a function to insert a word; but I prefer key strokes consistent
16694 with other Texinfo mode key bindings.)
16696 You will see numerous @code{define-key} expressions in
16697 @file{loaddefs.el} as well as in the various mode libraries, such as
16698 @file{cc-mode.el} and @file{lisp-mode.el}.
16700 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
16701 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
16702 Reference Manual}, for more information about keymaps.
16704 @node Loading Files, Autoload, Keymaps, Emacs Initialization
16705 @section Loading Files
16706 @cindex Loading files
16707 @c findex load
16709 Many people in the GNU Emacs community have written extensions to
16710 Emacs.  As time goes by, these extensions are often included in new
16711 releases.  For example, the Calendar and Diary packages are now part
16712 of the standard GNU Emacs, as is Calc.
16714 You can use a @code{load} command to evaluate a complete file and
16715 thereby install all the functions and variables in the file into Emacs.
16716 For example:
16718 @c (auto-compression-mode t)
16720 @smallexample
16721 (load "~/emacs/slowsplit")
16722 @end smallexample
16724 This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it
16725 exists, the faster, byte compiled @file{slowsplit.elc} file from the
16726 @file{emacs} sub-directory of your home directory.  The file contains
16727 the function @code{split-window-quietly}, which John Robinson wrote in
16728 1989.
16730 The @code{split-window-quietly} function splits a window with the
16731 minimum of redisplay.  I installed it in 1989 because it worked well
16732 with the slow 1200 baud terminals I was then using.  Nowadays, I only
16733 occasionally come across such a slow connection, but I continue to use
16734 the function because I like the way it leaves the bottom half of a
16735 buffer in the lower of the new windows and the top half in the upper
16736 window.
16738 @need 1250
16739 To replace the key binding for the default
16740 @code{split-window-vertically}, you must also unset that key and bind
16741 the keys to @code{split-window-quietly}, like this:
16743 @smallexample
16744 @group
16745 (global-unset-key "\C-x2")
16746 (global-set-key "\C-x2" 'split-window-quietly)
16747 @end group
16748 @end smallexample
16750 @vindex load-path
16751 If you load many extensions, as I do, then instead of specifying the
16752 exact location of the extension file, as shown above, you can specify
16753 that directory as part of Emacs' @code{load-path}.  Then, when Emacs
16754 loads a file, it will search that directory as well as its default
16755 list of directories.  (The default list is specified in @file{paths.h}
16756 when Emacs is built.)
16758 @need 1250
16759 The following command adds your @file{~/emacs} directory to the
16760 existing load path:
16762 @smallexample
16763 @group
16764 ;;; Emacs Load Path
16765 (setq load-path (cons "~/emacs" load-path))
16766 @end group
16767 @end smallexample
16769 Incidentally, @code{load-library} is an interactive interface to the
16770 @code{load} function.  The complete function looks like this:
16772 @findex load-library
16773 @smallexample
16774 @group
16775 (defun load-library (library)
16776   "Load the library named LIBRARY.
16777 This is an interface to the function `load'."
16778   (interactive "sLoad library: ")
16779   (load library))
16780 @end group
16781 @end smallexample
16783 The name of the function, @code{load-library}, comes from the use of
16784 `library' as a conventional synonym for `file'.  The source for the
16785 @code{load-library} command is in the @file{files.el} library.
16787 Another interactive command that does a slightly different job is
16788 @code{load-file}.  @xref{Lisp Libraries, , Libraries of Lisp Code for
16789 Emacs, emacs, The GNU Emacs Manual}, for information on the
16790 distinction between @code{load-library} and this command.
16792 @node Autoload, Simple Extension, Loading Files, Emacs Initialization
16793 @section Autoloading
16794 @findex autoload
16796 Instead of installing a function by loading the file that contains it,
16797 or by evaluating the function definition, you can make the function
16798 available but not actually install it until it is first called.  This
16799 is called @dfn{autoloading}.
16801 When you execute an autoloaded function, Emacs automatically evaluates
16802 the file that contains the definition, and then calls the function.
16804 Emacs starts quicker with autoloaded functions, since their libraries
16805 are not loaded right away; but you need to wait a moment when you
16806 first use such a function, while its containing file is evaluated.
16808 Rarely used functions are frequently autoloaded.  The
16809 @file{loaddefs.el} library contains hundreds of autoloaded functions,
16810 from @code{bookmark-set} to @code{wordstar-mode}.  Of course, you may
16811 come to use a `rare' function frequently.  When you do, you should
16812 load that function's file with a @code{load} expression in your
16813 @file{.emacs} file.
16815 In my @file{.emacs} file for Emacs version 21, I load 12 libraries
16816 that contain functions that would otherwise be autoloaded.  (Actually,
16817 it would have been better to include these files in my `dumped' Emacs
16818 when I built it, but I forgot.  @xref{Building Emacs, , Building
16819 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the @file{INSTALL}
16820 file for more about dumping.)
16822 You may also want to include autoloaded expressions in your @file{.emacs}
16823 file.  @code{autoload} is a built-in function that takes up to five
16824 arguments, the final three of which are optional.  The first argument
16825 is the name of the function to be autoloaded; the second is the name
16826 of the file to be loaded.  The third argument is documentation for the
16827 function, and the fourth tells whether the function can be called
16828 interactively.  The fifth argument tells what type of
16829 object---@code{autoload} can handle a keymap or macro as well as a
16830 function (the default is a function).
16832 @need 800
16833 Here is a typical example:
16835 @smallexample
16836 @group
16837 (autoload 'html-helper-mode
16838   "html-helper-mode" "Edit HTML documents" t)
16839 @end group
16840 @end smallexample
16842 @noindent
16843 (@code{html-helper-mode} is an alternative to @code{html-mode}, which
16844 is a standard part of the distribution).
16846 @noindent
16847 This expression autoloads the @code{html-helper-mode} function.  It
16848 takes it from the @file{html-helper-mode.el} file (or from the byte
16849 compiled file @file{html-helper-mode.elc}, if it exists.)  The file
16850 must be located in a directory specified by @code{load-path}.  The
16851 documentation says that this is a mode to help you edit documents
16852 written in the HyperText Markup Language.  You can call this mode
16853 interactively by typing @kbd{M-x html-helper-mode}.  (You need to
16854 duplicate the function's regular documentation in the autoload
16855 expression because the regular function is not yet loaded, so its
16856 documentation is not available.)
16858 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
16859 Manual}, for more information.
16861 @node Simple Extension, X11 Colors, Autoload, Emacs Initialization
16862 @section A Simple Extension: @code{line-to-top-of-window}
16863 @findex line-to-top-of-window
16864 @cindex Simple extension in @file{.emacs} file
16866 Here is a simple extension to Emacs that moves the line point is on to
16867 the top of the window.  I use this all the time, to make text easier
16868 to read.
16870 You can put the following code into a separate file and then load it
16871 from your @file{.emacs} file, or you can include it within your
16872 @file{.emacs} file.
16874 @need 1250
16875 Here is the definition:
16877 @smallexample
16878 @group
16879 ;;; Line to top of window;
16880 ;;; replace three keystroke sequence  C-u 0 C-l
16881 (defun line-to-top-of-window ()
16882   "Move the line point is on to top of window."
16883   (interactive)
16884   (recenter 0))
16885 @end group
16886 @end smallexample
16888 @need 1250
16889 Now for the keybinding.
16891 Nowadays, function keys as well as mouse button events and
16892 non-@sc{ascii} characters are written within square brackets, without
16893 quotation marks.  (In Emacs version 18 and before, you had to write
16894 different function key bindings for each different make of terminal.)
16896 I bind @code{line-to-top-of-window} to my @key{F6} function key like
16897 this:
16899 @smallexample
16900 (global-set-key [f6] 'line-to-top-of-window)
16901 @end smallexample
16903 For more information, see @ref{Init Rebinding, , Rebinding Keys in
16904 Your Init File, emacs, The GNU Emacs Manual}.
16906 @cindex Conditional 'twixt two versions of Emacs
16907 @cindex Version of Emacs, choosing
16908 @cindex Emacs version, choosing
16909 If you run two versions of GNU Emacs, such as versions 20 and 21, and
16910 use one @file{.emacs} file, you can select which code to evaluate with
16911 the following conditional:
16913 @smallexample
16914 @group
16915 (cond
16916  ((string-equal (number-to-string 20) (substring (emacs-version) 10 12))
16917   ;; evaluate version 20 code
16918   ( @dots{} ))
16919  ((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
16920   ;; evaluate version 21 code
16921   ( @dots{} )))
16922 @end group
16923 @end smallexample
16925 For example, in contrast to version 20, version 21 blinks its cursor
16926 by default.  I hate such blinking, as well as some other features in
16927 version 21, so I placed the following in my @file{.emacs}
16928 file@footnote{When I start instances of Emacs that do not load my
16929 @file{.emacs} file or any site file, I also turn off blinking:
16931 @smallexample
16932 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
16933 @end smallexample
16936 @smallexample
16937 @group
16938 (if (string-equal "21" (substring (emacs-version) 10 12))
16939     (progn
16940       (blink-cursor-mode 0)
16941       ;; Insert newline when you press `C-n' (next-line)
16942       ;; at the end of the buffer
16943       (setq next-line-add-newlines t)
16944 @end group
16945 @group
16946       ;; Turn on image viewing
16947       (auto-image-file-mode t)
16948 @end group
16949 @group
16950       ;; Turn on menu bar (this bar has text)
16951       ;; (Use numeric argument to turn on)
16952       (menu-bar-mode 1)
16953 @end group
16954 @group
16955       ;; Turn off tool bar (this bar has icons)
16956       ;; (Use numeric argument to turn on)
16957       (tool-bar-mode nil)
16958 @end group
16959 @group
16960       ;; Turn off tooltip mode for tool bar
16961       ;; (This mode causes icon explanations to pop up)
16962       ;; (Use numeric argument to turn on)
16963       (tooltip-mode nil)
16964       ;; If tooltips turned on, make tips appear promptly
16965       (setq tooltip-delay 0.1)  ; default is one second
16966        ))
16967 @end group
16968 @end smallexample
16970 @noindent
16971 (You will note that instead of typing @code{(number-to-string 21)}, I
16972 decided to save typing and wrote `21' as a string, @code{"21"}, rather
16973 than convert it from an integer to a string.  In this instance, this
16974 expression is better than the longer, but more general
16975 @code{(number-to-string 21)}.  However, if you do not know ahead of
16976 time what type of information will be returned, then the
16977 @code{number-to-string} function will be needed.)
16979 @node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
16980 @section X11 Colors
16982 You can specify colors when you use Emacs with the MIT X Windowing
16983 system.
16985 I dislike the default colors and specify my own.
16987 @need 1250
16988 Here are the expressions in my @file{.emacs}
16989 file that set values:
16991 @smallexample
16992 @group
16993 ;; Set cursor color
16994 (set-cursor-color "white")
16996 ;; Set mouse color
16997 (set-mouse-color "white")
16999 ;; Set foreground and background
17000 (set-foreground-color "white")
17001 (set-background-color "darkblue")
17002 @end group
17004 @group
17005 ;;; Set highlighting colors for isearch and drag
17006 (set-face-foreground 'highlight "white")
17007 (set-face-background 'highlight "blue")
17008 @end group
17010 @group
17011 (set-face-foreground 'region "cyan")
17012 (set-face-background 'region "blue")
17013 @end group
17015 @group
17016 (set-face-foreground 'secondary-selection "skyblue")
17017 (set-face-background 'secondary-selection "darkblue")
17018 @end group
17020 @group
17021 ;; Set calendar highlighting colors
17022 (setq calendar-load-hook
17023       '(lambda ()
17024          (set-face-foreground 'diary-face   "skyblue")
17025          (set-face-background 'holiday-face "slate blue")
17026          (set-face-foreground 'holiday-face "white")))
17027 @end group
17028 @end smallexample
17030 The various shades of blue soothe my eye and prevent me from seeing
17031 the screen flicker.
17033 Alternatively, I could have set my specifications in various X
17034 initialization files.  For example, I could set the foreground,
17035 background, cursor, and pointer (i.e., mouse) colors in my
17036 @file{~/.Xresources} file like this:
17038 @smallexample
17039 @group
17040 Emacs*foreground:   white
17041 Emacs*background:   darkblue
17042 Emacs*cursorColor:  white
17043 Emacs*pointerColor: white
17044 @end group
17045 @end smallexample
17047 In any event, since it is not part of Emacs, I set the root color of
17048 my X window in my @file{~/.xinitrc} file, like this@footnote{I
17049 occasionally run more modern window managers, such as Sawfish with
17050 GNOME, Enlightenment, SCWM, or KDE; in those cases, I often specify an
17051 image rather than a plain color.}:
17053 @smallexample
17054 @group
17055 # I use TWM for window manager.
17056 xsetroot -solid Navy -fg white &
17057 @end group
17058 @end smallexample
17060 @node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
17061 @section Miscellaneous Settings for a @file{.emacs} File
17063 Here are a few miscellaneous settings:
17064 @sp 1
17066 @itemize @minus
17067 @item
17068 Set the shape and color of the mouse cursor:
17069 @smallexample
17070 @group
17071 ; Cursor shapes are defined in
17072 ; `/usr/include/X11/cursorfont.h';
17073 ; for example, the `target' cursor is number 128;
17074 ; the `top_left_arrow' cursor is number 132.
17075 @end group
17077 @group
17078 (let ((mpointer (x-get-resource "*mpointer"
17079                                 "*emacs*mpointer")))
17080   ;; If you have not set your mouse pointer
17081   ;;     then set it, otherwise leave as is:
17082   (if (eq mpointer nil)
17083       (setq mpointer "132")) ; top_left_arrow
17084 @end group
17085 @group
17086   (setq x-pointer-shape (string-to-int mpointer))
17087   (set-mouse-color "white"))
17088 @end group
17089 @end smallexample
17091 @item
17092 Convert @kbd{@key{CTL}-h} into @key{DEL} and @key{DEL}
17093 into @kbd{@key{CTL}-h}.@*
17094 (Some olders keyboards needed this, although I have not seen the
17095 problem recently.)
17097 @smallexample
17098 @group
17099 ;; Translate `C-h' to <DEL>.
17100 ; (keyboard-translate ?\C-h ?\C-?)
17102 ;; Translate <DEL> to `C-h'.
17103 (keyboard-translate ?\C-? ?\C-h)
17104 @end group
17105 @end smallexample
17107 @item Turn off a blinking cursor!
17109 @smallexample
17110 @group
17111 (if (fboundp 'blink-cursor-mode)
17112     (blink-cursor-mode -1))
17113 @end group
17114 @end smallexample
17116 @item  Ignore case when using `grep'@*
17117 @samp{-n}@w{  }   Prefix each line of output with line number@*
17118 @samp{-i}@w{  }   Ignore case distinctions@*
17119 @samp{-e}@w{  }   Protect patterns beginning with a hyphen character, @samp{-} 
17121 @smallexample
17122 (setq grep-command "grep  -n -i -e ")
17123 @end smallexample
17125 @item Automatically uncompress compressed files when visiting them
17127 @smallexample
17128 (load "uncompress")
17129 @end smallexample
17131 @item Find an existing buffer, even if it has a different name@*
17132 This avoids problems with symbolic links.
17134 @smallexample
17135 (setq find-file-existing-other-name t)
17136 @end smallexample
17138 @item Set your language environment and default input method
17140 @smallexample
17141 @group
17142 (set-language-environment "latin-1")
17143 ;; Remember you can enable or disable multilingual text input
17144 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
17145 (setq default-input-method "latin-1-prefix")
17146 @end group
17147 @end smallexample
17149 If you want to write with Chinese `GB' characters, set this instead:
17151 @smallexample
17152 @group
17153 (set-language-environment "Chinese-GB")
17154 (setq default-input-method "chinese-tonepy")
17155 @end group
17156 @end smallexample
17157 @end itemize
17159 @subsubheading Fixing Unpleasant Key Bindings
17160 @cindex Key bindings, fixing 
17161 @cindex Bindings, key, fixing unpleasant
17163 Some systems bind keys unpleasantly.  Sometimes, for example, the
17164 @key{CTL} key appears in an awkward spot rather than at the far left
17165 of the home row.
17167 Usually, when people fix these sorts of keybindings, they do not
17168 change their @file{~/.emacs} file.  Instead, they bind the proper keys
17169 on their consoles with the @code{loadkeys} or @code{install-keymap}
17170 commands in their boot script and then include @code{xmodmap} commands
17171 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
17173 @need 1250
17174 @noindent
17175 For a boot script:
17177 @smallexample
17178 @group
17179 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
17181 @exdent or
17183 install-keymap emacs2
17184 @end group
17185 @end smallexample
17187 @need 1250
17188 @noindent
17189 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
17190 Lock} key is at the far left of the home row:
17192 @smallexample
17193 @group
17194 # Bind the key labeled `Caps Lock' to `Control'
17195 # (Such a broken user interface suggests that keyboard manufacturers
17196 # think that computers are typewriters from 1885.)
17198 xmodmap -e "clear Lock"
17199 xmodmap -e "add Control = Caps_Lock"
17200 @end group
17201 @end smallexample
17203 @need 1250
17204 @noindent
17205 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
17206 key to a @key{META} key:
17208 @smallexample
17209 @group
17210 # Some ill designed keyboards have a key labeled ALT and no Meta
17211 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
17212 @end group
17213 @end smallexample
17215 @node Mode Line,  , Miscellaneous, Emacs Initialization
17216 @section A Modified Mode Line
17217 @vindex default-mode-line-format
17218 @cindex Mode line format
17220 Finally, a feature I really like: a modified mode line.
17222 When I work over a network, I forget which machine I am using.  Also,
17223 I tend to I lose track of where I am, and which line point is on.
17225 So I reset my mode line to look like this:
17227 @smallexample
17228 -:-- foo.texi   rattlesnake:/home/bob/  Line 1  (Texinfo Fill) Top
17229 @end smallexample
17231 I am visiting a file called @file{foo.texi}, on my machine
17232 @file{rattlesnake} in my @file{/home/bob} buffer.  I am on line 1, in
17233 Texinfo mode, and am at the top of the buffer.
17235 @need 1200
17236 My @file{.emacs} file has a section that looks like this:
17238 @smallexample
17239 @group
17240 ;; Set a Mode Line that tells me which machine, which directory,
17241 ;; and which line I am on, plus the other customary information.
17242 (setq default-mode-line-format
17243  (quote
17244   (#("-" 0 1
17245      (help-echo
17246       "mouse-1: select window, mouse-2: delete others ..."))
17247    mode-line-mule-info
17248    mode-line-modified
17249    mode-line-frame-identification
17250    "    "
17251 @end group
17252 @group
17253    mode-line-buffer-identification
17254    "    "
17255    (:eval (substring
17256            (system-name) 0 (string-match "\\..+" (system-name))))
17257    ":"
17258    default-directory
17259    #(" " 0 1
17260      (help-echo
17261       "mouse-1: select window, mouse-2: delete others ..."))
17262    (line-number-mode " Line %l ")
17263    global-mode-string
17264 @end group
17265 @group
17266    #("   %[(" 0 6
17267      (help-echo
17268       "mouse-1: select window, mouse-2: delete others ..."))
17269    (:eval (mode-line-mode-name))
17270    mode-line-process
17271    minor-mode-alist
17272    #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
17273    ")%] "
17274    (-3 . "%P")
17275    ;;   "-%-"
17276    )))
17277 @end group
17278 @end smallexample
17280 @noindent
17281 Here, I redefine the default mode line.  Most of the parts are from
17282 the original; but I make a few changes.  I set the @emph{default} mode
17283 line format so as to permit various modes, such as Info, to override
17286 Many elements in the list are self-explanatory:
17287 @code{mode-line-modified} is a variable that tells whether the buffer
17288 has been modified, @code{mode-name} tells the name of the mode, and so
17289 on.  However, the format looks complicated because of two features we
17290 have not discussed.
17292 @cindex Properties, in mode line example
17293 The first string in the mode line is a dash or hyphen, @samp{-}.  In
17294 the old days, it would have been specified simply as @code{"-"}.  But
17295 nowadays, Emacs can add properties to a string, such as highlighting
17296 or, as in this case, a help feature.  If you place your mouse cursor
17297 over the hyphen, some help information appears (By default, you must
17298 wait one second before the information appears.  You can change that
17299 timing by changing the value of @code{tooltip-delay}.)
17301 @need 1000
17302 The new string format has a special syntax:
17304 @smallexample
17305 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
17306 @end smallexample
17308 @noindent
17309 The @code{#(} begins a list.  The first element of the list is the
17310 string itself, just one @samp{-}.  The second and third
17311 elements specify the range over which the fourth element applies.  A
17312 range starts @emph{after} a character, so a zero means the range
17313 starts just before the first character; a 1 means that the range ends
17314 just after the first character.  The third element is the property for
17315 the range.  It consists of a property list,  a
17316 property name, in this case, @samp{help-echo}, followed by a value, in this
17317 case, a string.  The second, third, and fourth elements of this new
17318 string format can be repeated.
17320 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
17321 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
17322 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
17324 @code{mode-line-buffer-identification}
17325 displays the current buffer name.  It is a list
17326 beginning @code{(#("%12b" 0 4 @dots{}}.
17327 The @code{#(} begins the list.
17329 The @samp{"%12b"} displays the current buffer name, using the
17330 @code{buffer-name} function with which we are familiar; the `12'
17331 specifies the maximum number of characters that will be displayed.
17332 When a name has fewer characters, whitespace is added to fill out to
17333 this number.  (Buffer names can and often should be longer than 12
17334 characters; this length works well in a typical 80 column wide
17335 window.)
17337 @code{:eval} is a new feature in GNU Emacs version 21.  It says to
17338 evaluate the following form and use the result as a string to display.
17339 In this case, the expression displays the first component of the full
17340 system name.  The end of the first component is a @samp{.} (`period'),
17341 so I use the @code{string-match} function to tell me the length of the
17342 first component.  The substring from the zeroth character to that
17343 length is the name of the machine.
17345 @need 1250
17346 This is the expression:
17348 @smallexample
17349 @group
17350 (:eval (substring
17351         (system-name) 0 (string-match "\\..+" (system-name))))
17352 @end group
17353 @end smallexample
17355 @samp{%[} and @samp{%]} cause a pair of square brackets
17356 to appear for each recursive editing level.  @samp{%n} says `Narrow'
17357 when narrowing is in effect.  @samp{%P} tells you the percentage of
17358 the buffer that is above the bottom of the window, or `Top', `Bottom',
17359 or `All'.  (A lower case @samp{p} tell you the percentage above the
17360 @emph{top} of the window.)  @samp{%-} inserts enough dashes to fill
17361 out the line.
17363 Remember, ``You don't have to like Emacs to like it'' --- your own
17364 Emacs can have different colors, different commands, and different
17365 keys than a default Emacs.
17367 On the other hand, if you want to bring up a plain `out of the box'
17368 Emacs, with no customization, type:
17370 @smallexample
17371 emacs -q
17372 @end smallexample
17374 @noindent
17375 This will start an Emacs that does @emph{not} load your
17376 @file{~/.emacs} initialization file.  A plain, default Emacs.  Nothing
17377 more.
17379 @node Debugging, Conclusion, Emacs Initialization, Top
17380 @chapter Debugging
17381 @cindex debugging
17383 GNU Emacs has two debuggers, @code{debug} and @code{edebug}.  The
17384 first is built into the internals of Emacs and is always with you;
17385 the second requires that you instrument a function before you can use it.
17387 Both debuggers are described extensively in @ref{Debugging, ,
17388 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
17389 In this chapter, I will walk through a short example of each.
17391 @menu
17392 * debug::                       How to use the built-in debugger.
17393 * debug-on-entry::              Start debugging when you call a function.
17394 * debug-on-quit::               Start debugging when you quit with @kbd{C-g}.
17395 * edebug::                      How to use Edebug, a source level debugger.
17396 * Debugging Exercises::
17397 @end menu
17399 @node debug, debug-on-entry, Debugging, Debugging
17400 @section @code{debug}
17401 @findex debug
17403 Suppose you have written a function definition that is intended to
17404 return the sum of the numbers 1 through a given number.  (This is the
17405 @code{triangle} function discussed earlier.  @xref{Decrementing
17406 Example, , Example with Decrementing Counter}, for a discussion.)
17407 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
17409 However, your function definition has a bug.  You have mistyped
17410 @samp{1=} for @samp{1-}.  Here is the broken definition:
17412 @findex triangle-bugged
17413 @smallexample
17414 @group
17415 (defun triangle-bugged (number)
17416   "Return sum of numbers 1 through NUMBER inclusive."
17417   (let ((total 0))
17418     (while (> number 0)
17419       (setq total (+ total number))
17420       (setq number (1= number)))      ; @r{Error here.}
17421     total))
17422 @end group
17423 @end smallexample
17425 If you are reading this in Info, you can evaluate this definition in
17426 the normal fashion.  You will see @code{triangle-bugged} appear in the
17427 echo area.
17429 @need 1250
17430 Now evaluate the @code{triangle-bugged} function with an
17431 argument of 4:
17433 @smallexample
17434 (triangle-bugged 4)
17435 @end smallexample
17437 @noindent
17438 In GNU Emacs version 21, you will create and enter a
17439 @file{*Backtrace*} buffer that says:
17441 @noindent
17442 @smallexample
17443 @group
17444 ---------- Buffer: *Backtrace* ----------
17445 Debugger entered--Lisp error: (void-function 1=)
17446   (1= number)
17447   (setq number (1= number))
17448   (while (> number 0) (setq total (+ total number))
17449         (setq number (1= number)))
17450   (let ((total 0)) (while (> number 0) (setq total ...)
17451     (setq number ...)) total)
17452   triangle-bugged(4)
17453 @end group
17454 @group
17455   eval((triangle-bugged 4))
17456   eval-last-sexp-1(nil)
17457   eval-last-sexp(nil)
17458   call-interactively(eval-last-sexp)
17459 ---------- Buffer: *Backtrace* ----------
17460 @end group
17461 @end smallexample
17463 @noindent
17464 (I have reformatted this example slightly; the debugger does not fold
17465 long lines.  As usual, you can quit the debugger by typing @kbd{q} in
17466 the @file{*Backtrace*} buffer.)
17468 In practice, for a bug as simple as this, the `Lisp error' line will
17469 tell you what you need to know to correct the definition.  The
17470 function @code{1=} is `void'.
17472 @need 800
17473 In GNU Emacs 20 and before, you will see:
17475 @smallexample
17476 Symbol's function definition is void:@: 1=
17477 @end smallexample
17479 @noindent
17480 which has the same meaning as the @file{*Backtrace*} buffer line in
17481 version 21.
17483 However, suppose you are not quite certain what is going on?
17484 You can read the complete backtrace.
17486 In this case, you need to run GNU Emacs 21, which automatically starts
17487 the debugger that puts you in the @file{*Backtrace*} buffer; or else,
17488 you need to start the debugger manually as described below.
17490 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
17491 what Emacs did that led to the error.  Emacs made an interactive call
17492 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
17493 of the @code{triangle-bugged} expression.  Each line above tells you
17494 what the Lisp interpreter evaluated next.
17496 @need 1250
17497 The third line from the top of the buffer is
17499 @smallexample
17500 (setq number (1= number))
17501 @end smallexample
17503 @noindent
17504 Emacs tried to evaluate this expression; in order to do so, it tried
17505 to evaluate the inner expression shown on the second line from the
17506 top:
17508 @smallexample
17509 (1= number)
17510 @end smallexample
17512 @need 1250
17513 @noindent
17514 This is where the error occurred; as the top line says:
17516 @smallexample
17517 Debugger entered--Lisp error: (void-function 1=)
17518 @end smallexample
17520 @noindent
17521 You can correct the mistake, re-evaluate the function definition, and
17522 then run your test again.
17524 @node debug-on-entry, debug-on-quit, debug, Debugging
17525 @section @code{debug-on-entry}
17526 @findex debug-on-entry
17528 GNU Emacs 21 starts the debugger automatically when your function has
17529 an error.  GNU Emacs version 20 and before did not; it simply
17530 presented you with an error message.  You had to start the debugger
17531 manually.
17533 You can start the debugger manually for all versions of Emacs; the
17534 advantage is that the debugger runs even if you do not have a bug in
17535 your code.  Sometimes your code will be free of bugs!
17537 You can enter the debugger when you call the function by calling
17538 @code{debug-on-entry}.
17540 @need 1250
17541 @noindent
17542 Type:
17544 @smallexample
17545 M-x debug-on-entry RET triangle-bugged RET
17546 @end smallexample
17548 @need 1250
17549 @noindent
17550 Now, evaluate the following:
17552 @smallexample
17553 (triangle-bugged 5)
17554 @end smallexample
17556 @noindent
17557 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
17558 you that it is beginning to evaluate the @code{triangle-bugged}
17559 function:
17561 @smallexample
17562 @group
17563 ---------- Buffer: *Backtrace* ----------
17564 Debugger entered--entering a function:
17565 * triangle-bugged(5)
17566   eval((triangle-bugged 5))
17567 @end group
17568 @group
17569   eval-last-sexp-1(nil)
17570   eval-last-sexp(nil)
17571   call-interactively(eval-last-sexp)
17572 ---------- Buffer: *Backtrace* ----------
17573 @end group
17574 @end smallexample
17576 In the @file{*Backtrace*} buffer, type @kbd{d}.  Emacs will evaluate
17577 the first expression in @code{triangle-bugged}; the buffer will look
17578 like this:
17580 @smallexample
17581 @group
17582 ---------- Buffer: *Backtrace* ----------
17583 Debugger entered--beginning evaluation of function call form:
17584 * (let ((total 0)) (while (> number 0) (setq total ...)
17585         (setq number ...)) total)
17586 * triangle-bugged(5)
17587   eval((triangle-bugged 5))
17588 @end group
17589 @group
17590   eval-last-sexp-1(nil)
17591   eval-last-sexp(nil)
17592   call-interactively(eval-last-sexp)
17593 ---------- Buffer: *Backtrace* ----------
17594 @end group
17595 @end smallexample
17597 @noindent
17598 Now, type @kbd{d} again, eight times, slowly.  Each time you type
17599 @kbd{d}, Emacs will evaluate another expression in the function
17600 definition.
17602 @need 1750
17603 Eventually, the buffer will look like this:
17605 @smallexample
17606 @group
17607 ---------- Buffer: *Backtrace* ----------
17608 Debugger entered--beginning evaluation of function call form:
17609 * (setq number (1= number))
17610 * (while (> number 0) (setq total (+ total number))
17611         (setq number (1= number)))
17612 @group
17613 @end group
17614 * (let ((total 0)) (while (> number 0) (setq total ...)
17615         (setq number ...)) total)
17616 * triangle-bugged(5)
17617   eval((triangle-bugged 5))
17618 @group
17619 @end group
17620   eval-last-sexp-1(nil)
17621   eval-last-sexp(nil)
17622   call-interactively(eval-last-sexp)
17623 ---------- Buffer: *Backtrace* ----------
17624 @end group
17625 @end smallexample
17627 @need 1500
17628 @noindent
17629 Finally, after you type @kbd{d} two more times, Emacs will reach the
17630 error, and the top two lines of the @file{*Backtrace*} buffer will look
17631 like this:
17633 @smallexample
17634 @group
17635 ---------- Buffer: *Backtrace* ----------
17636 Debugger entered--Lisp error: (void-function 1=)
17637 * (1= number)
17638 @dots{}
17639 ---------- Buffer: *Backtrace* ----------
17640 @end group
17641 @end smallexample
17643 By typing @kbd{d}, you were able to step through the function.
17645 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
17646 quits the trace, but does not cancel @code{debug-on-entry}.
17648 @findex cancel-debug-on-entry
17649 To cancel the effect of @code{debug-on-entry}, call
17650 @code{cancel-debug-on-entry} and the name of the function, like this:
17652 @smallexample
17653 M-x cancel-debug-on-entry RET triangle-bugged RET
17654 @end smallexample
17656 @noindent
17657 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
17659 @node debug-on-quit, edebug, debug-on-entry, Debugging
17660 @section @code{debug-on-quit} and @code{(debug)}
17662 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
17663 there are two other ways to start @code{debug}.
17665 @findex debug-on-quit
17666 You can start @code{debug} whenever you type @kbd{C-g}
17667 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
17668 @code{t}.  This is useful for debugging infinite loops.
17670 @need 1500
17671 @cindex @code{(debug)} in code
17672 Or, you can insert a line that says @code{(debug)} into your code
17673 where you want the debugger to start, like this:
17675 @smallexample
17676 @group
17677 (defun triangle-bugged (number)
17678   "Return sum of numbers 1 through NUMBER inclusive."
17679   (let ((total 0))
17680     (while (> number 0)
17681       (setq total (+ total number))
17682       (debug)                         ; @r{Start debugger.}
17683       (setq number (1= number)))      ; @r{Error here.}
17684     total))
17685 @end group
17686 @end smallexample
17688 The @code{debug} function is described in detail in @ref{Debugger, ,
17689 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
17691 @node edebug, Debugging Exercises, debug-on-quit, Debugging
17692 @section The @code{edebug} Source Level Debugger
17693 @cindex Source level debugger
17694 @findex edebug
17696 Edebug is a source level debugger.  Edebug normally displays the
17697 source of the code you are debugging, with an arrow at the left that
17698 shows which line you are currently executing.
17700 You can walk through the execution of a function, line by line, or run
17701 quickly until reaching a @dfn{breakpoint} where execution stops.
17703 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
17704 Lisp Reference Manual}.
17706 @need 1250
17707 Here is a bugged function definition for @code{triangle-recursively}.
17708 @xref{Recursive triangle function, , Recursion in place of a counter},
17709 for a review of it.
17711 @smallexample
17712 @group
17713 (defun triangle-recursively-bugged (number)
17714   "Return sum of numbers 1 through NUMBER inclusive.
17715 Uses recursion."
17716   (if (= number 1)
17717       1
17718     (+ number
17719        (triangle-recursively-bugged
17720         (1= number)))))               ; @r{Error here.}
17721 @end group
17722 @end smallexample
17724 @noindent
17725 Normally, you would install this definition by positioning your cursor
17726 after the function's closing parenthesis and typing @kbd{C-x C-e}
17727 (@code{eval-last-sexp}) or else by positioning your cursor within the
17728 definition and typing @kbd{C-M-x} (@code{eval-defun}).  (By default,
17729 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
17730 Interactive mode.)
17732 @need 1500
17733 However, to prepare this function definition for Edebug, you must
17734 first @dfn{instrument} the code using a different command.  You can do
17735 this by positioning your cursor within the definition and typing
17737 @smallexample
17738 M-x edebug-defun RET
17739 @end smallexample
17741 @noindent
17742 This will cause Emacs to load Edebug automatically if it is not
17743 already loaded, and properly instrument the function.
17745 After instrumenting the function, place your cursor after the
17746 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
17748 @smallexample
17749 (triangle-recursively-bugged 3)
17750 @end smallexample
17752 @noindent
17753 You will be jumped back to the source for
17754 @code{triangle-recursively-bugged} and the cursor positioned at the
17755 beginning of the @code{if} line of the function.  Also, you will see
17756 an arrowhead at the left hand side of that line.  The arrowhead marks
17757 the line where the function is executing.  (In the following examples,
17758 we show the arrowhead with @samp{=>}; in a windowing system, you may
17759 see the arrowhead as a solid triangle in the window `fringe'.)
17761 @smallexample
17762 =>@point{}(if (= number 1)
17763 @end smallexample
17765 @noindent
17766 @iftex
17767 In the example, the location of point is displayed with a star,
17768 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
17769 @end iftex
17770 @ifnottex
17771 In the example, the location of point is displayed as @samp{@point{}}
17772 (in a printed book, it is displayed with a five pointed star).
17773 @end ifnottex
17775 If you now press @key{SPC}, point will move to the next expression to
17776 be executed; the line will look like this:
17778 @smallexample
17779 =>(if @point{}(= number 1)
17780 @end smallexample
17782 @noindent
17783 As you continue to press @key{SPC}, point will move from expression to
17784 expression.  At the same time, whenever an expression returns a value,
17785 that value will be displayed in the echo area.  For example, after you
17786 move point past @code{number}, you will see the following:
17788 @smallexample
17789 Result: 3 = C-c
17790 @end smallexample
17792 @noindent
17793 This means the value of @code{number} is 3, which is @sc{ascii}
17794 `control-c' (the third letter of the alphabet, in case you need to
17795 know this information).
17797 You can continue moving through the code until you reach the line with
17798 the error.  Before evaluation, that line looks like this:
17800 @smallexample
17801 =>        @point{}(1= number)))))               ; @r{Error here.}
17802 @end smallexample
17804 @need 1250
17805 @noindent
17806 When you press @key{SPC} once again, you will produce an error message
17807 that says:
17809 @smallexample
17810 Symbol's function definition is void:@: 1=
17811 @end smallexample
17813 @noindent
17814 This is the bug.
17816 Press @kbd{q} to quit Edebug.
17818 To remove instrumentation from a function definition, simply
17819 re-evaluate it with a command that does not instrument it.
17820 For example, you could place your cursor after the definition's
17821 closing parenthesis and type @kbd{C-x C-e}.
17823 Edebug does a great deal more than walk with you through a function.
17824 You can set it so it races through on its own, stopping only at an
17825 error or at specified stopping points; you can cause it to display the
17826 changing values of various expressions; you can find out how many
17827 times a function is called, and more.
17829 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
17830 Lisp Reference Manual}.
17832 @need 1500
17833 @node Debugging Exercises,  , edebug, Debugging
17834 @section Debugging Exercises
17836 @itemize @bullet
17837 @item
17838 Install the @code{count-words-region} function and then cause it to
17839 enter the built-in debugger when you call it.  Run the command on a
17840 region containing two words.  You will need to press @kbd{d} a
17841 remarkable number of times.  On your system, is a `hook' called after
17842 the command finishes?  (For information on hooks, see @ref{Command
17843 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
17844 Manual}.)
17846 @item
17847 Copy @code{count-words-region} into the @file{*scratch*} buffer,
17848 instrument the function for Edebug, and walk through its execution.
17849 The function does not need to have a bug, although you can introduce
17850 one if you wish.  If the function lacks a bug, the walk-through
17851 completes without problems.
17853 @item
17854 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
17855 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
17856 @kbd{@key{CTL}-x} followed by an upper case @kbd{X}; use this prefix
17857 for commands made outside of the Edebug debugging buffer.)
17859 @item
17860 In the Edebug debugging buffer, use the @kbd{p}
17861 (@code{edebug-bounce-point}) command to see where in the region the
17862 @code{count-words-region} is working.
17864 @item
17865 Move point to some spot further down function and then type the
17866 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
17868 @item
17869 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
17870 walk through the function on its own; use an upper case @kbd{T} for
17871 @code{edebug-Trace-fast-mode}.
17873 @item
17874 Set a breakpoint, then run Edebug in Trace mode until it reaches the
17875 stopping point.
17876 @end itemize
17878 @node Conclusion, the-the, Debugging, Top
17879 @chapter Conclusion
17881 We have now reached the end of this Introduction.  You have now
17882 learned enough about programming in Emacs Lisp to set values, to write
17883 simple @file{.emacs} files for yourself and your friends, and write
17884 simple customizations and extensions to Emacs.
17886 This is a place to stop.  Or, if you wish, you can now go onward, and
17887 teach yourself.
17889 You have learned some of the basic nuts and bolts of programming.  But
17890 only some.  There are a great many more brackets and hinges that are
17891 easy to use that we have not touched.
17893 A path you can follow right now lies among the sources to GNU Emacs
17894 and in
17895 @ifnotinfo
17896 @cite{The GNU Emacs Lisp Reference Manual}.
17897 @end ifnotinfo
17898 @ifinfo
17899 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
17900 Emacs Lisp Reference Manual}.
17901 @end ifinfo
17903 The Emacs Lisp sources are an adventure.  When you read the sources and
17904 come across a function or expression that is unfamiliar, you need to
17905 figure out or find out what it does.
17907 Go to the Reference Manual.  It is a thorough, complete, and fairly
17908 easy-to-read description of Emacs Lisp.  It is written not only for
17909 experts, but for people who know what you know.  (The @cite{Reference
17910 Manual} comes with the standard GNU Emacs distribution.  Like this
17911 introduction, it comes as a Texinfo source file, so you can read it
17912 on-line and as a typeset, printed book.)
17914 Go to the other on-line help that is part of GNU Emacs: the on-line
17915 documentation for all functions, and @code{find-tags}, the program
17916 that takes you to sources.
17918 Here is an example of how I explore the sources.  Because of its name,
17919 @file{simple.el} is the file I looked at first, a long time ago.  As
17920 it happens some of the functions in @file{simple.el} are complicated,
17921 or at least look complicated at first sight.  The @code{open-line}
17922 function, for example, looks complicated.
17924 You may want to walk through this function slowly, as we did with the
17925 @code{forward-sentence} function.
17926 @ifnottex
17927 (@xref{forward-sentence}.)
17928 @end ifnottex
17929 @iftex
17930 (@xref{forward-sentence, , @code{forward-sentence}}.)
17931 @end iftex
17932 Or you may want to skip that function and look at another, such as
17933 @code{split-line}.  You don't need to read all the functions.
17934 According to @code{count-words-in-defun}, the @code{split-line}
17935 function contains 27 words and symbols.
17937 Even though it is short, @code{split-line} contains four expressions
17938 we have not studied: @code{skip-chars-forward}, @code{indent-to},
17939 @code{current-column} and @samp{?\n}.
17941 Consider the @code{skip-chars-forward} function.  (It is part of the
17942 function definition for @code{back-to-indentation}, which is shown in
17943 @ref{Review, , Review}.)
17945 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
17946 typing @kbd{C-h f} (@code{describe-function}) and the name of the
17947 function.  This gives you the function documentation.
17949 You may be able to guess what is done by a well named function such as
17950 @code{indent-to}; or you can look it up, too.  Incidentally, the
17951 @code{describe-function} function itself is in @file{help.el}; it is
17952 one of those long, but decipherable functions.  You can look up
17953 @code{describe-function} using the @kbd{C-h f} command!
17955 In this instance, since the code is Lisp, the @file{*Help*} buffer
17956 contains the name of the library containing the function's source.
17957 You can put point over the name of the library and press the RET key,
17958 which in this situation is bound to @code{help-follow}, and be taken
17959 directly to the source, in the same way as @kbd{M-.}
17960 (@code{find-tag}).
17962 The definition for @code{describe-function} illustrates how to
17963 customize the @code{interactive} expression without using the standard
17964 character codes; and it shows how to create a temporary buffer.
17966 (The @code{indent-to} function is written in C rather than Emacs Lisp;
17967 it is a `built-in' function.  @code{help-follow} only provides you
17968 with the documentation of a built-in function; it does not take you to
17969 the source.  But @code{find-tag} will take you to the source, if
17970 properly set up.)
17972 You can look at a function's source using @code{find-tag}, which is
17973 bound to @kbd{M-.}  Finally, you can find out what the Reference
17974 Manual has to say by visiting the manual in Info, and typing @kbd{i}
17975 (@code{Info-index}) and the name of the function, or by looking up
17976 @code{skip-chars-forward} in the index to a printed copy of the
17977 manual.
17979 Similarly, you can find out what is meant by @samp{?\n}.  You can try
17980 using @code{Info-index} with @samp{?\n}.  It turns out that this
17981 action won't help; but don't give up.  If you search the index for
17982 @samp{\n} without the @samp{?}, you will be taken directly to the
17983 relevant section of the manual.  (@xref{Character Type, , Character
17984 Type, elisp, The GNU Emacs Lisp Reference Manual}.  @samp{?\n} stands
17985 for the newline character.)
17987 Other interesting source files include @file{paragraphs.el},
17988 @file{loaddefs.el}, and @file{loadup.el}.  The @file{paragraphs.el}
17989 file includes short, easily understood functions as well as longer
17990 ones.  The @file{loaddefs.el} file contains the many standard
17991 autoloads and many keymaps.  I have never looked at it all; only at
17992 parts.  @file{loadup.el} is the file that loads the standard parts of
17993 Emacs; it tells you a great deal about how Emacs is built.
17994 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
17995 Reference Manual}, for more about building.)
17997 As I said, you have learned some nuts and bolts; however, and very
17998 importantly, we have hardly touched major aspects of programming; I
17999 have said nothing about how to sort information, except to use the
18000 predefined @code{sort} function; I have said nothing about how to store
18001 information, except to use variables and lists; I have said nothing
18002 about how to write programs that write programs.  These are topics for
18003 another, and different kind of book, a different kind of learning.
18005 What you have done is learn enough for much practical work with GNU
18006 Emacs.  What you have done is get started.  This is the end of a
18007 beginning.
18009 @c ================ Appendix ================
18011 @node the-the, Kill Ring, Conclusion, Top
18012 @appendix The @code{the-the} Function
18013 @findex the-the
18014 @cindex Duplicated words function
18015 @cindex Words, duplicated
18017 Sometimes when you you write text, you duplicate words---as with ``you
18018 you'' near the beginning of this sentence.  I find that most
18019 frequently, I duplicate ``the'; hence, I call the function for
18020 detecting duplicated words, @code{the-the}.
18022 @need 1250
18023 As a first step, you could use the following regular expression to
18024 search for duplicates:
18026 @smallexample
18027 \\(\\w+[ \t\n]+\\)\\1
18028 @end smallexample
18030 @noindent
18031 This regexp matches one or more word-constituent characters followed
18032 by one or more spaces, tabs, or newlines.  However, it does not detect
18033 duplicated words on different lines, since the ending of the first
18034 word, the end of the line, is different from the ending of the second
18035 word, a space.  (For more information about regular expressions, see
18036 @ref{Regexp Search, , Regular Expression Searches}, as well as
18037 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
18038 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
18039 The GNU Emacs Lisp Reference Manual}.)
18041 You might try searching just for duplicated word-constituent
18042 characters but that does not work since the pattern detects doubles
18043 such as the two occurrences of `th' in `with the'.
18045 Another possible regexp searches for word-constituent characters
18046 followed by non-word-constituent characters, reduplicated.  Here,
18047 @w{@samp{\\w+}} matches one or more word-constituent characters and
18048 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
18050 @smallexample
18051 \\(\\(\\w+\\)\\W*\\)\\1
18052 @end smallexample
18054 @noindent
18055 Again, not useful.
18057 Here is the pattern that I use.  It is not perfect, but good enough.
18058 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
18059 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
18060 any characters that are @emph{not} an @@-sign, space, newline, or tab.
18062 @smallexample
18063 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
18064 @end smallexample
18066 One can write more complicated expressions, but I found that this
18067 expression is good enough, so I use it.
18069 Here is the @code{the-the} function, as I include it in my
18070 @file{.emacs} file, along with a handy global key binding:
18072 @smallexample
18073 @group
18074 (defun the-the ()
18075   "Search forward for for a duplicated word."
18076   (interactive)
18077   (message "Searching for for duplicated words ...")
18078   (push-mark)
18079 @end group
18080 @group
18081   ;; This regexp is not perfect
18082   ;; but is fairly good over all:
18083   (if (re-search-forward
18084        "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
18085       (message "Found duplicated word.")
18086     (message "End of buffer")))
18087 @end group
18089 @group
18090 ;; Bind `the-the' to  C-c \
18091 (global-set-key "\C-c\\" 'the-the)
18092 @end group
18093 @end smallexample
18095 @sp 1
18096 Here is test text:
18098 @smallexample
18099 @group
18100 one two two three four five
18101 five six seven
18102 @end group
18103 @end smallexample
18105 You can substitute the other regular expressions shown above in the
18106 function definition and try each of them on this list.
18108 @node Kill Ring, Full Graph, the-the, Top
18109 @appendix Handling the Kill Ring
18110 @cindex Kill ring handling
18111 @cindex Handling the kill ring
18112 @cindex Ring, making a list like a
18114 The kill ring is a list that is transformed into a ring by the
18115 workings of the @code{rotate-yank-pointer} function.  The @code{yank}
18116 and @code{yank-pop} commands use the @code{rotate-yank-pointer}
18117 function.  This appendix describes the @code{rotate-yank-pointer}
18118 function as well as both the @code{yank} and the @code{yank-pop}
18119 commands.
18121 @menu
18122 * rotate-yank-pointer::         Move a pointer along a list and around.
18123 * yank::                        Paste a copy of a clipped element.
18124 * yank-pop::                    Insert first element pointed to.
18125 * ring file::
18126 @end menu
18128 @node rotate-yank-pointer, yank, Kill Ring, Kill Ring
18129 @comment  node-name,  next,  previous,  up
18130 @appendixsec The @code{rotate-yank-pointer} Function
18131 @findex rotate-yank-pointer
18133 The @code{rotate-yank-pointer} function changes the element in the kill
18134 ring to which @code{kill-ring-yank-pointer} points.  For example, it can
18135 change  @code{kill-ring-yank-pointer} from pointing to the second
18136 element to point to the third element.
18138 @need 800
18139 Here is the code for @code{rotate-yank-pointer}:
18141 @smallexample
18142 @group
18143 (defun rotate-yank-pointer (arg)
18144   "Rotate the yanking point in the kill ring."
18145   (interactive "p")
18146   (let ((length (length kill-ring)))
18147 @end group
18148 @group
18149     (if (zerop length)
18150         ;; @r{then-part}
18151         (error "Kill ring is empty")
18152 @end group
18153 @group
18154       ;; @r{else-part}
18155       (setq kill-ring-yank-pointer
18156             (nthcdr (% (+ arg
18157                           (- length
18158                              (length
18159                               kill-ring-yank-pointer)))
18160                        length)
18161                     kill-ring)))))
18162 @end group
18163 @end smallexample
18165 @menu
18166 * Understanding rotate-yk-ptr::
18167 * rotate-yk-ptr body::          The body of @code{rotate-yank-pointer}.
18168 @end menu
18170 @node Understanding rotate-yk-ptr, rotate-yk-ptr body, rotate-yank-pointer, rotate-yank-pointer
18171 @ifnottex
18172 @unnumberedsubsec @code{rotate-yank-pointer} in Outline
18173 @end ifnottex
18175 The @code{rotate-yank-pointer} function looks complex, but as usual,
18176 it can be understood by taking it apart piece by piece.  First look at
18177 it in skeletal form:
18179 @smallexample
18180 @group
18181 (defun rotate-yank-pointer (arg)
18182   "Rotate the yanking point in the kill ring."
18183   (interactive "p")
18184   (let @var{varlist}
18185     @var{body}@dots{})
18186 @end group
18187 @end smallexample
18189 This function takes one argument, called @code{arg}.  It has a brief
18190 documentation string; and it is interactive with a small @samp{p}, which
18191 means that the argument must be a processed prefix passed to the
18192 function as a number.
18194 The body of the function definition is a @code{let} expression, which
18195 itself has a body as well as a @var{varlist}.
18197 The @code{let} expression declares a variable that will be only usable
18198 within the bounds of this function.  This variable is called
18199 @code{length} and is bound to a value that is equal to the number of
18200 items in the kill ring.  This is done by using the function called
18201 @code{length}.  (Note that this function has the same name as the
18202 variable called @code{length}; but one use of the word is to name the
18203 function and the other is to name the variable.  The two are quite
18204 distinct.  Similarly, an English speaker will distinguish between the
18205 meanings of the word @samp{ship} when he says: "I must ship this package
18206 immediately." and "I must get aboard the ship immediately.")
18208 The function @code{length} tells the number of items there are in a list,
18209 so @code{(length kill-ring)} returns the number of items there are in the
18210 kill ring.
18212 @node rotate-yk-ptr body,  , Understanding rotate-yk-ptr, rotate-yank-pointer
18213 @comment  node-name,  next,  previous,  up
18214 @appendixsubsec The Body of @code{rotate-yank-pointer}
18216 The body of @code{rotate-yank-pointer} is a @code{let} expression and
18217 the body of the @code{let} expression is an @code{if} expression.
18219 The purpose of the @code{if} expression is to find out whether there is
18220 anything in the kill ring.  If the kill ring is empty, the @code{error}
18221 function stops evaluation of the function and prints a message in the
18222 echo area.  On the other hand, if the kill ring has something in it, the
18223 work of the function is done.
18225 Here is the if-part and then-part of the @code{if} expression:
18227 @findex zerop
18228 @findex error
18229 @smallexample
18230 @group
18231 (if (zerop length)                      ; @r{if-part}
18232     (error "Kill ring is empty")        ; @r{then-part}
18233   @dots{}
18234 @end group
18235 @end smallexample
18237 @noindent
18238 If there is not anything in the kill ring, its length must be zero and
18239 an error message sent to the user: @samp{Kill ring is empty}.  The
18240 @code{if} expression uses the function @code{zerop} which returns true
18241 if the value it is testing is zero.  When @code{zerop} tests true, the
18242 then-part of the @code{if} is evaluated.  The then-part is a list
18243 starting with the function @code{error}, which is a function that is
18244 similar to the @code{message} function (@pxref{message}), in that it
18245 prints a one-line message in the echo area.  However, in addition to
18246 printing a message, @code{error} also stops evaluation of the function
18247 within which it is embedded.  This means that the rest of the function
18248 will not be evaluated if the length of the kill ring is zero.
18250 @menu
18251 * Digression concerning error::  How to mislead humans, but not computers.
18252 * rotate-yk-ptr else-part::     The else-part of the @code{if} expression.
18253 * Remainder Function::          The remainder, @code{%}, function.
18254 * rotate-yk-ptr remainder::     Using @code{%} in @code{rotate-yank-pointer}.
18255 * kill-rng-yk-ptr last elt::    Pointing to the last element.
18256 @end menu
18258 @node Digression concerning error, rotate-yk-ptr else-part, rotate-yk-ptr body, rotate-yk-ptr body
18259 @ifnottex
18260 @unnumberedsubsubsec Digression about the word `error'
18261 @end ifnottex
18263 (In my opinion, it is slightly misleading, at least to humans, to use
18264 the term `error' as the name of the @code{error} function.  A better
18265 term would be `cancel'.  Strictly speaking, of course, you cannot
18266 point to, much less rotate a pointer to a list that has no length, so
18267 from the point of view of the computer, the word `error' is correct.
18268 But a human expects to attempt this sort of thing, if only to find out
18269 whether the kill ring is full or empty.  This is an act of
18270 exploration.
18272 (From the human point of view, the act of exploration and discovery is
18273 not necessarily an error, and therefore should not be labelled as one,
18274 even in the bowels of a computer.  As it is, the code in Emacs implies
18275 that a human who is acting virtuously, by exploring his or her
18276 environment, is making an error.  This is bad.  Even though the computer
18277 takes the same steps as it does when there is an `error', a term such as
18278 `cancel' would have a clearer connotation.)
18280 @node rotate-yk-ptr else-part, Remainder Function, Digression concerning error, rotate-yk-ptr body
18281 @unnumberedsubsubsec The else-part of the @code{if} expression
18283 The else-part of the @code{if} expression is dedicated to setting the
18284 value of @code{kill-ring-yank-pointer} when the kill ring has something
18285 in it.  The code looks like this:
18287 @smallexample
18288 @group
18289 (setq kill-ring-yank-pointer
18290       (nthcdr (% (+ arg
18291                     (- length
18292                        (length kill-ring-yank-pointer)))
18293                  length)
18294               kill-ring)))))
18295 @end group
18296 @end smallexample
18298 This needs some examination.  Clearly, @code{kill-ring-yank-pointer}
18299 is being set to be equal to some @sc{cdr} of the kill ring, using the
18300 @code{nthcdr} function that is described in an earlier section.
18301 (@xref{copy-region-as-kill}.)  But exactly how does it do this?
18303 Before looking at the details of the code let's first consider the
18304 purpose of the @code{rotate-yank-pointer} function.
18306 The @code{rotate-yank-pointer} function changes what
18307 @code{kill-ring-yank-pointer} points to.  If
18308 @code{kill-ring-yank-pointer} starts by pointing to the first element
18309 of a list, a call to @code{rotate-yank-pointer} causes it to point to
18310 the second element; and if @code{kill-ring-yank-pointer} points to the
18311 second element, a call to @code{rotate-yank-pointer} causes it to
18312 point to the third element.  (And if @code{rotate-yank-pointer} is
18313 given an argument greater than 1, it jumps the pointer that many
18314 elements.)
18316 The @code{rotate-yank-pointer} function uses @code{setq} to reset what
18317 the @code{kill-ring-yank-pointer} points to.  If
18318 @code{kill-ring-yank-pointer} points to the first element of the kill
18319 ring, then, in the simplest case, the @code{rotate-yank-pointer}
18320 function must cause it to point to the second element.  Put another
18321 way, @code{kill-ring-yank-pointer} must be reset to have a value equal
18322 to the @sc{cdr} of the kill ring.
18324 @need 1250
18325 That is, under these circumstances,
18327 @smallexample
18328 @group
18329 (setq kill-ring-yank-pointer
18330    ("some text" "a different piece of text" "yet more text"))
18332 (setq kill-ring
18333    ("some text" "a different piece of text" "yet more text"))
18334 @end group
18335 @end smallexample
18337 @need 800
18338 @noindent
18339 the code should do this:
18341 @smallexample
18342 (setq kill-ring-yank-pointer (cdr kill-ring))
18343 @end smallexample
18345 @need 1000
18346 @noindent
18347 As a result, the @code{kill-ring-yank-pointer} will look like this:
18349 @smallexample
18350 @group
18351 kill-ring-yank-pointer
18352      @result{} ("a different piece of text" "yet more text"))
18353 @end group
18354 @end smallexample
18356 The actual @code{setq} expression uses the @code{nthcdr} function to do
18357 the job.
18359 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
18360 works by repeatedly taking the @sc{cdr} of a list---it takes the
18361 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
18363 @need 800
18364 The two following expressions produce the same result:
18366 @smallexample
18367 @group
18368 (setq kill-ring-yank-pointer (cdr kill-ring))
18370 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
18371 @end group
18372 @end smallexample
18374 In the @code{rotate-yank-pointer} function, however, the first
18375 argument to @code{nthcdr} is a rather complex looking expression with
18376 lots of arithmetic inside of it:
18378 @smallexample
18379 @group
18380 (% (+ arg
18381       (- length
18382          (length kill-ring-yank-pointer)))
18383    length)
18384 @end group
18385 @end smallexample
18387 As usual, we need to look at the most deeply embedded expression first
18388 and then work our way towards the light.
18390 The most deeply embedded expression is @code{(length
18391 kill-ring-yank-pointer)}.  This finds the length of the current value of
18392 the @code{kill-ring-yank-pointer}.  (Remember that the
18393 @code{kill-ring-yank-pointer} is the name of a variable whose value is a
18394 list.)
18396 @need 800
18397 The measurement of the length is inside the expression:
18399 @smallexample
18400 (- length (length kill-ring-yank-pointer))
18401 @end smallexample
18403 @noindent
18404 In this expression, the first @code{length} is the variable that was
18405 assigned the length of the kill ring in the @code{let} statement at the
18406 beginning of the function.  (One might think this function would be
18407 clearer if the variable @code{length} were named
18408 @code{length-of-kill-ring} instead; but if you look at the text of the
18409 whole function, you will see that it is so short that naming this
18410 variable @code{length} is not a bother, unless you are pulling the
18411 function apart into very tiny pieces as we are doing here.)
18413 So the line @code{(- length (length kill-ring-yank-pointer))} tells the
18414 difference between the length of the kill ring and the length of the list
18415 whose name is @code{kill-ring-yank-pointer}.
18417 To see how all this fits into the @code{rotate-yank-pointer}
18418 function, let's begin by analyzing the case where
18419 @code{kill-ring-yank-pointer} points to the first element of the kill
18420 ring, just as @code{kill-ring} does, and see what happens when
18421 @code{rotate-yank-pointer} is called with an argument of 1.
18423 The variable @code{length} and the value of the expression
18424 @code{(length kill-ring-yank-pointer)} will be the same since the
18425 variable @code{length} is the length of the kill ring and the
18426 @code{kill-ring-yank-pointer} is pointing to the whole kill ring.
18427 Consequently, the value of
18429 @smallexample
18430 (- length (length kill-ring-yank-pointer))
18431 @end smallexample
18433 @noindent
18434 will be zero.  Since the value of @code{arg} will be 1, this will mean
18435 that the value of the whole expression
18437 @smallexample
18438 (+ arg (- length (length kill-ring-yank-pointer)))
18439 @end smallexample
18441 @noindent
18442 will be 1.
18444 @need 1200
18445 Consequently, the argument to @code{nthcdr} will be found as the result of
18446 the expression
18448 @smallexample
18449 (% 1 length)
18450 @end smallexample
18452 @node Remainder Function, rotate-yk-ptr remainder, rotate-yk-ptr else-part, rotate-yk-ptr body
18453 @unnumberedsubsubsec The @code{%} remainder function
18455 To understand @code{(% 1 length)}, we need to understand @code{%}.
18456 According to its documentation (which I just found by typing @kbd{C-h
18457 f @kbd{%} @key{RET}}), the @code{%} function returns the remainder of
18458 its first argument divided by its second argument.  For example, the
18459 remainder of 5 divided by 2 is 1.  (2 goes into 5 twice with a
18460 remainder of 1.)
18462 What surprises people who don't often do arithmetic is that a smaller
18463 number can be divided by a larger number and have a remainder.  In the
18464 example we just used, 5 was divided by 2.  We can reverse that and ask,
18465 what is the result of dividing 2 by 5?  If you can use fractions, the
18466 answer is obviously 2/5 or .4; but if, as here, you can only use whole
18467 numbers, the result has to be something different.  Clearly, 5 can go into
18468 2 zero times, but what of the remainder?  To see what the answer is,
18469 consider a case that has to be familiar from childhood:
18471 @itemize @bullet
18472 @item
18473 5 divided by 5 is 1 with a remainder of 0;
18475 @item
18476 6 divided by 5 is 1 with a remainder of 1;
18478 @item
18479 7 divided by 5 is 1 with a remainder of 2.
18481 @item
18482 Similarly, 10 divided by 5 is 2 with a remainder of 0;
18484 @item
18485 11 divided by 5 is 2 with a remainder of 1;
18487 @item
18488 12 divided by 5 is 1 with a remainder of 2.
18489 @end itemize
18491 @need 1250
18492 @noindent
18493 By considering the cases as parallel, we can see that
18495 @itemize @bullet
18496 @item
18497 zero divided by 5 must be zero with a remainder of zero;
18499 @item
18500 1 divided by 5 must be zero with a remainder of 1;
18502 @item
18503 2 divided by 5 must be zero with a remainder of 2;
18504 @end itemize
18506 @noindent
18507 and so on.
18509 @need 1250
18510 So, in this code, if the value of @code{length} is 5, then the result of
18511 evaluating
18513 @smallexample
18514 (% 1 5)
18515 @end smallexample
18517 @noindent
18518 is 1.  (I just checked this by placing the cursor after the expression
18519 and typing @kbd{C-x C-e}.  Indeed, 1 is printed in the echo area.)
18521 @need 2000
18522 @node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body
18523 @unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer}
18525 When the @code{kill-ring-yank-pointer} points to the
18526 beginning of the kill ring, and the argument passed to
18527 @code{rotate-yank-pointer} is 1, the @code{%} expression returns 1:
18529 @smallexample
18530 @group
18531 (- length (length kill-ring-yank-pointer))
18532      @result{} 0
18533 @end group
18534 @end smallexample
18536 @need 1250
18537 @noindent
18538 therefore,
18540 @smallexample
18541 @group
18542 (+ arg (- length (length kill-ring-yank-pointer)))
18543      @result{} 1
18544 @end group
18545 @end smallexample
18547 @need 1250
18548 @noindent
18549 and consequently:
18551 @smallexample
18552 @group
18553 (% (+ arg (- length (length kill-ring-yank-pointer)))
18554    length)
18555      @result{} 1
18556 @end group
18557 @end smallexample
18559 @noindent
18560 regardless of the value of @code{length}.
18562 @need 1250
18563 @noindent
18564 As a result of this, the @code{setq kill-ring-yank-pointer} expression
18565 simplifies to:
18567 @smallexample
18568 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
18569 @end smallexample
18571 @noindent
18572 What it does is now easy to understand.  Instead of pointing as it did
18573 to the first element of the kill ring, the
18574 @code{kill-ring-yank-pointer} is set to point to the second element.
18576 Clearly, if the argument passed to @code{rotate-yank-pointer} is two, then
18577 the @code{kill-ring-yank-pointer} is set to @code{(nthcdr 2 kill-ring)};
18578 and so on for different values of the argument.
18580 Similarly, if the @code{kill-ring-yank-pointer} starts out pointing to
18581 the second element of the kill ring, its length is shorter than the
18582 length of the kill ring by 1, so the computation of the remainder is
18583 based on the expression @code{(% (+ arg 1) length)}.  This means that
18584 the @code{kill-ring-yank-pointer} is moved from the second element of
18585 the kill ring to the third element if the argument passed to
18586 @code{rotate-yank-pointer} is 1.
18588 @node kill-rng-yk-ptr last elt,  , rotate-yk-ptr remainder, rotate-yk-ptr body
18589 @unnumberedsubsubsec Pointing to the last element
18591 The final question is, what happens if the @code{kill-ring-yank-pointer}
18592 is set to the @emph{last} element of the kill ring?  Will a call to
18593 @code{rotate-yank-pointer} mean that nothing more can be taken from the
18594 kill ring?  The answer is no.  What happens is different and useful.
18595 The @code{kill-ring-yank-pointer} is set to point to the beginning of
18596 the kill ring instead.
18598 Let's see how this works by looking at the code, assuming the length of the
18599 kill ring is 5 and the argument passed to @code{rotate-yank-pointer} is 1.
18600 When the @code{kill-ring-yank-pointer} points to the last element of
18601 the kill ring, its length is 1.  The code looks like this:
18603 @smallexample
18604 (% (+ arg (- length (length kill-ring-yank-pointer))) length)
18605 @end smallexample
18607 @need 1250
18608 When the variables are replaced by their numeric values, the expression
18609 looks like this:
18611 @smallexample
18612 (% (+ 1 (- 5 1)) 5)
18613 @end smallexample
18615 @noindent
18616 This expression can be evaluated by looking at the most embedded inner
18617 expression first and working outwards:  The value of @code{(- 5 1)} is 4;
18618 the sum of @code{(+ 1 4)} is 5; and the remainder of dividing 5 by 5 is
18619 zero.  So what @code{rotate-yank-pointer} will do is
18621 @smallexample
18622 (setq kill-ring-yank-pointer (nthcdr 0 kill-ring))
18623 @end smallexample
18625 @noindent
18626 which will set the @code{kill-ring-yank-pointer} to point to the beginning
18627 of the kill ring.
18629 So what happens with successive calls to @code{rotate-yank-pointer} is that
18630 it moves the @code{kill-ring-yank-pointer} from element to element in the
18631 kill ring until it reaches the end; then it jumps back to the beginning.
18632 And this is why the kill ring is called a ring, since by jumping back to
18633 the beginning, it is as if the list has no end!  (And what is a ring, but
18634 an entity with no end?)
18636 @node yank, yank-pop, rotate-yank-pointer, Kill Ring
18637 @comment  node-name,  next,  previous,  up
18638 @appendixsec @code{yank}
18639 @findex yank
18641 After learning about @code{rotate-yank-pointer}, the code for the
18642 @code{yank} function is almost easy.  It has only one tricky part, which is
18643 the computation of the argument to be passed to @code{rotate-yank-pointer}.
18645 @need 1250
18646 The code looks like this:
18648 @smallexample
18649 @group
18650 (defun yank (&optional arg)
18651   "Reinsert the last stretch of killed text.
18652 More precisely, reinsert the stretch of killed text most
18653 recently killed OR yanked.
18654 With just C-U as argument, same but put point in front
18655 (and mark at end).  With argument n, reinsert the nth
18656 most recently killed stretch of killed text.
18657 See also the command \\[yank-pop]."
18658 @end group
18659 @group
18661   (interactive "*P")
18662   (rotate-yank-pointer (if (listp arg) 0
18663                          (if (eq arg '-) -1
18664                            (1- arg))))
18665   (push-mark (point))
18666   (insert (car kill-ring-yank-pointer))
18667   (if (consp arg)
18668       (exchange-point-and-mark)))
18669 @end group
18670 @end smallexample
18672 Glancing over this code, we can understand the last few lines readily
18673 enough.  The mark is pushed, that is, remembered; then the first element
18674 (the @sc{car}) of what the @code{kill-ring-yank-pointer} points to is
18675 inserted; and then, if the argument passed the function is a
18676 @code{cons}, point and mark are exchanged so the point is put in the
18677 front of the inserted text rather than at the end.  This option is
18678 explained in the documentation.  The function itself is interactive with
18679 @code{"*P"}.  This means it will not work on a read-only buffer, and that
18680 the unprocessed prefix argument is passed to the function.
18682 @menu
18683 * rotate-yk-ptr arg::           Pass the argument to @code{rotate-yank-pointer}.
18684 * rotate-yk-ptr negative arg::  Pass a negative argument.
18685 @end menu
18687 @node rotate-yk-ptr arg, rotate-yk-ptr negative arg, yank, yank
18688 @unnumberedsubsubsec Passing the argument
18690 The hard part of @code{yank} is understanding the computation that
18691 determines the value of the argument passed to
18692 @code{rotate-yank-pointer}.  Fortunately, it is not so difficult as it
18693 looks at first sight.
18695 What happens is that the result of evaluating one or both of the
18696 @code{if} expressions will be a number and that number will be the
18697 argument passed to @code{rotate-yank-pointer}.
18699 @need 1250
18700 Laid out with comments, the code looks like this:
18702 @smallexample
18703 @group
18704 (if (listp arg)                         ; @r{if-part}
18705     0                                   ; @r{then-part}
18706   (if (eq arg '-)                       ; @r{else-part, inner if}
18707       -1                                ; @r{inner if's then-part}
18708     (1- arg))))                         ; @r{inner if's else-part}
18709 @end group
18710 @end smallexample
18712 @noindent
18713 This code consists of two @code{if} expression, one the else-part of
18714 the other.
18716 The first or outer @code{if} expression tests whether the argument
18717 passed to @code{yank} is a list.  Oddly enough, this will be true if
18718 @code{yank} is called without an argument---because then it will be
18719 passed the value of @code{nil} for the optional argument and an
18720 evaluation of @code{(listp nil)} returns true!  So, if no argument is
18721 passed to @code{yank}, the argument passed to
18722 @code{rotate-yank-pointer} inside of @code{yank} is zero.  This means
18723 the pointer is not moved and the first element to which
18724 @code{kill-ring-yank-pointer} points is inserted, as we expect.
18725 Similarly, if the argument for @code{yank} is @kbd{C-u}, this will be
18726 read as a list, so again, a zero will be passed to
18727 @code{rotate-yank-pointer}.  (@kbd{C-u} produces an unprocessed prefix
18728 argument of @code{(4)}, which is a list of one element.)  At the same
18729 time, later in the function, this argument will be read as a
18730 @code{cons} so point will be put in the front and mark at the end of
18731 the insertion.  (The @code{P} argument to @code{interactive} is
18732 designed to provide these values for the case when an optional
18733 argument is not provided or when it is @kbd{C-u}.)
18735 The then-part of the outer @code{if} expression handles the case when
18736 there is no argument or when it is @kbd{C-u}.  The else-part handles the
18737 other situations.  The else-part is itself another @code{if} expression.
18739 The inner @code{if} expression tests whether the argument is a minus
18740 sign.  (This is done by pressing the @key{META} and @kbd{-} keys at the
18741 same time, or the @key{ESC} key and then the @kbd{-} key).  In this
18742 case, the @code{rotate-yank-pointer} function is passed @kbd{-1} as an
18743 argument.  This moves the @code{kill-ring-yank-pointer} backwards, which
18744 is what is desired.
18746 If the true-or-false-test of the inner @code{if} expression is false
18747 (that is, if the argument is not a minus sign), the else-part of the
18748 expression is evaluated.  This is the expression @code{(1- arg)}.
18749 Because of the two @code{if} expressions, it will only occur when the
18750 argument is a positive number or when it is a negative number (not
18751 just a minus sign on its own).  What @code{(1- arg)} does is decrement
18752 the number and return it.  (The @code{1-} function subtracts one from
18753 its argument.)  This means that if the argument to
18754 @code{rotate-yank-pointer} is 1, it is reduced to zero, which means
18755 the first element to which @code{kill-ring-yank-pointer} points is
18756 yanked back, as you would expect.
18758 @node rotate-yk-ptr negative arg,  , rotate-yk-ptr arg, yank
18759 @unnumberedsubsubsec Passing a negative argument
18761 Finally, the question arises, what happens if either the remainder
18762 function, @code{%}, or the @code{nthcdr} function is passed a negative
18763 argument, as they quite well may?
18765 The answers can be found by a quick test.  When @code{(% -1 5)} is
18766 evaluated, a negative number is returned; and if @code{nthcdr} is
18767 called with a negative number, it returns the same value as if it were
18768 called with a first argument of zero.  This can be seen by evaluating
18769 the following code.
18771 Here the @samp{@result{}} points to the result of evaluating the code
18772 preceding it.  This was done by positioning the cursor after the code
18773 and typing @kbd{C-x C-e} (@code{eval-last-sexp}) in the usual fashion.
18774 You can do this if you are reading this in Info inside of GNU Emacs.
18776 @smallexample
18777 @group
18778 (% -1 5)
18779      @result{} -1
18780 @end group
18782 @group
18783 (setq animals '(cats dogs elephants))
18784      @result{} (cats dogs elephants)
18785 @end group
18787 @group
18788 (nthcdr 1 animals)
18789      @result{} (dogs elephants)
18790 @end group
18792 @group
18793 (nthcdr 0 animals)
18794      @result{} (cats dogs elephants)
18795 @end group
18797 @group
18798 (nthcdr -1 animals)
18799      @result{} (cats dogs elephants)
18800 @end group
18801 @end smallexample
18803 So, if a minus sign or a negative number is passed to @code{yank}, the
18804 @code{kill-ring-yank-point} is rotated backwards until it reaches the
18805 beginning of the list.  Then it stays there.  Unlike the other case,
18806 when it jumps from the end of the list to the beginning of the list,
18807 making a ring, it stops.  This makes sense.  You often want to get back
18808 to the most recently clipped out piece of text, but you don't usually
18809 want to insert text from as many as thirty kill commands ago.  So you
18810 need to work through the ring to get to the end, but won't cycle around
18811 it inadvertently if you are trying to come back to the beginning.
18813 Incidentally, any number passed to @code{yank} with a minus sign
18814 preceding it will be treated as @minus{}1.  This is evidently a
18815 simplification for writing the program.  You don't need to jump back
18816 towards the beginning of the kill ring more than one place at a time
18817 and doing this is easier than writing a function to determine the
18818 magnitude of the number that follows the minus sign.
18820 @node yank-pop, ring file, yank, Kill Ring
18821 @comment  node-name,  next,  previous,  up
18822 @appendixsec @code{yank-pop}
18823 @findex yank-pop
18825 After understanding @code{yank}, the @code{yank-pop} function is easy.
18826 Leaving out the documentation to save space, it looks like this:
18828 @smallexample
18829 @group
18830 (defun yank-pop (arg)
18831   (interactive "*p")
18832   (if (not (eq last-command 'yank))
18833       (error "Previous command was not a yank"))
18834 @end group
18835 @group
18836   (setq this-command 'yank)
18837   (let ((before (< (point) (mark))))
18838     (delete-region (point) (mark))
18839     (rotate-yank-pointer arg)
18840 @end group
18841 @group
18842     (set-mark (point))
18843     (insert (car kill-ring-yank-pointer))
18844     (if before (exchange-point-and-mark))))
18845 @end group
18846 @end smallexample
18848 The function is interactive with a small @samp{p} so the prefix
18849 argument is processed and passed to the function.  The command can
18850 only be used after a previous yank; otherwise an error message is
18851 sent.  This check uses the variable @code{last-command} which is
18852 discussed elsewhere.  (@xref{copy-region-as-kill}.)
18854 The @code{let} clause sets the variable @code{before} to true or false
18855 depending whether point is before or after mark and then the region
18856 between point and mark is deleted.  This is the region that was just
18857 inserted by the previous yank and it is this text that will be
18858 replaced.  Next the @code{kill-ring-yank-pointer} is rotated so that
18859 the previously inserted text is not reinserted yet again.  Mark is set
18860 at the beginning of the place the new text will be inserted and then
18861 the first element to which @code{kill-ring-yank-pointer} points is
18862 inserted.  This leaves point after the new text.  If in the previous
18863 yank, point was left before the inserted text, point and mark are now
18864 exchanged so point is again left in front of the newly inserted text.
18865 That is all there is to it!
18867 @node ring file,  , yank-pop, Kill Ring
18868 @comment  node-name,  next,  previous,  up
18869 @appendixsec The @file{ring.el} File
18870 @cindex @file{ring.el} file
18872 Interestingly, GNU Emacs posses a file called @file{ring.el} that
18873 provides many of the features we just discussed.  But functions such
18874 as @code{kill-ring-yank-pointer} do not use this library, possibly
18875 because they were written earlier.
18877 @node Full Graph, Free Software and Free Manuals, Kill Ring, Top
18878 @appendix A Graph with Labelled Axes
18880 Printed axes help you understand a graph.  They convey scale.  In an
18881 earlier chapter (@pxref{Readying a Graph, ,  Readying a Graph}), we
18882 wrote the code to print the body of a graph.  Here we write the code
18883 for printing and labelling vertical and horizontal axes, along with the
18884 body itself.
18886 @menu
18887 * Labelled Example::
18888 * print-graph Varlist::         @code{let} expression in @code{print-graph}.
18889 * print-Y-axis::                Print a label for the vertical axis.
18890 * print-X-axis::                Print a horizontal label.
18891 * Print Whole Graph::           The function to print a complete graph.
18892 @end menu
18894 @node Labelled Example, print-graph Varlist, Full Graph, Full Graph
18895 @ifnottex
18896 @unnumberedsec Labelled Example Graph
18897 @end ifnottex
18899 Since insertions fill a buffer to the right and below point, the new
18900 graph printing function should first print the Y or vertical axis,
18901 then the body of the graph, and finally the X or horizontal axis.
18902 This sequence lays out for us the contents of the function:
18904 @enumerate
18905 @item
18906 Set up code.
18908 @item
18909 Print Y axis.
18911 @item
18912 Print body of graph.
18914 @item
18915 Print X axis.
18916 @end enumerate
18918 @need 800
18919 Here is an example of how a finished graph should look:
18921 @smallexample
18922 @group
18923     10 -
18924                   *
18925                   *  *
18926                   *  **
18927                   *  ***
18928      5 -      *   *******
18929             * *** *******
18930             *************
18931           ***************
18932      1 - ****************
18933          |   |    |    |
18934          1   5   10   15
18935 @end group
18936 @end smallexample
18938 @noindent
18939 In this graph, both the vertical and the horizontal axes are labelled
18940 with numbers.  However, in some graphs, the horizontal axis is time
18941 and would be better labelled with months, like this:
18943 @smallexample
18944 @group
18945      5 -      *
18946             * ** *
18947             *******
18948           ********** **
18949      1 - **************
18950          |    ^      |
18951          Jan  June   Jan
18952 @end group
18953 @end smallexample
18955 Indeed, with a little thought, we can easily come up with a variety of
18956 vertical and horizontal labelling schemes.  Our task could become
18957 complicated.  But complications breed confusion.  Rather than permit
18958 this, it is better choose a simple labelling scheme for our first
18959 effort, and to modify or replace it later.
18961 @need 1200
18962 These considerations suggest the following outline for the
18963 @code{print-graph} function:
18965 @smallexample
18966 @group
18967 (defun print-graph (numbers-list)
18968   "@var{documentation}@dots{}"
18969   (let ((height  @dots{}
18970         @dots{}))
18971 @end group
18972 @group
18973     (print-Y-axis height @dots{} )
18974     (graph-body-print numbers-list)
18975     (print-X-axis @dots{} )))
18976 @end group
18977 @end smallexample
18979 We can work on each part of the @code{print-graph} function definition
18980 in turn.
18982 @node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph
18983 @comment  node-name,  next,  previous,  up
18984 @appendixsec The @code{print-graph} Varlist
18985 @cindex @code{print-graph} varlist
18987 In writing the @code{print-graph} function, the first task is to write
18988 the varlist in the @code{let} expression.  (We will leave aside for the
18989 moment any thoughts about making the function interactive or about the
18990 contents of its documentation string.)
18992 The varlist should set several values.  Clearly, the top of the label
18993 for the vertical axis must be at least the height of the graph, which
18994 means that we must obtain this information here.  Note that the
18995 @code{print-graph-body} function also requires this information.  There
18996 is no reason to calculate the height of the graph in two different
18997 places, so we should change @code{print-graph-body} from the way we
18998 defined it earlier to take advantage of the calculation.
19000 Similarly, both the function for printing the X axis labels and the
19001 @code{print-graph-body} function need to learn the value of the width of
19002 each symbol.  We can perform the calculation here and change the
19003 definition for @code{print-graph-body} from the way we defined it in the
19004 previous chapter.
19006 The length of the label for the horizontal axis must be at least as long
19007 as the graph.  However, this information is used only in the function
19008 that prints the horizontal axis, so it does not need to be calculated here.
19010 These thoughts lead us directly to the following form for the varlist
19011 in the @code{let} for @code{print-graph}:
19013 @smallexample
19014 @group
19015 (let ((height (apply 'max numbers-list)) ; @r{First version.}
19016       (symbol-width (length graph-blank)))
19017 @end group
19018 @end smallexample
19020 @noindent
19021 As we shall see, this expression is not quite right.
19023 @need 2000
19024 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph
19025 @comment  node-name,  next,  previous,  up
19026 @appendixsec The @code{print-Y-axis} Function
19027 @cindex Axis, print vertical
19028 @cindex Y axis printing
19029 @cindex Vertical axis printing
19030 @cindex Print vertical axis
19032 The job of the @code{print-Y-axis} function is to print a label for
19033 the vertical axis that looks like this:
19035 @smallexample
19036 @group
19037     10 -
19042      5 -
19046      1 -
19047 @end group
19048 @end smallexample
19050 @noindent
19051 The function should be passed the height of the graph, and then should
19052 construct and insert the appropriate numbers and marks.
19054 It is easy enough to see in the figure what the Y axis label should
19055 look like; but to say in words, and then to write a function
19056 definition to do the job is another matter.  It is not quite true to
19057 say that we want a number and a tic every five lines: there are only
19058 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
19059 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
19060 and 9).  It is better to say that we want a number and a tic mark on
19061 the base line (number 1) and then that we want a number and a tic on
19062 the fifth line from the bottom and on every line that is a multiple of
19063 five.
19065 @menu
19066 * Height of label::             What height for the Y axis?
19067 * Compute a Remainder::         How to compute the remainder of a division.
19068 * Y Axis Element::              Construct a line for the Y axis.
19069 * Y-axis-column::               Generate a list of Y axis labels.
19070 * print-Y-axis Penultimate::    A not quite final version.
19071 @end menu
19073 @node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis
19074 @ifnottex
19075 @unnumberedsubsec What height should the label be?
19076 @end ifnottex
19078 The next issue is what height the label should be?  Suppose the maximum
19079 height of tallest column of the graph is seven.  Should the highest
19080 label on the Y axis be @samp{5 -}, and should the graph stick up above
19081 the label?  Or should the highest label be @samp{7 -}, and mark the peak
19082 of the graph?  Or should the highest label be @code{10 -}, which is a
19083 multiple of five, and be higher than the topmost value of the graph?
19085 The latter form is preferred.  Most graphs are drawn within rectangles
19086 whose sides are an integral number of steps long---5, 10, 15, and so
19087 on for a step distance of five.  But as soon as we decide to use a
19088 step height for the vertical axis, we discover that the simple
19089 expression in the varlist for computing the height is wrong.  The
19090 expression is @code{(apply 'max numbers-list)}.  This returns the
19091 precise height, not the maximum height plus whatever is necessary to
19092 round up to the nearest multiple of five.  A more complex expression
19093 is required.
19095 As usual in cases like this, a complex problem becomes simpler if it is
19096 divided into several smaller problems.
19098 First, consider the case when the highest value of the graph is an
19099 integral multiple of five---when it is 5, 10, 15, or some higher
19100 multiple of five.  We can use this value as the Y axis height.
19102 A fairly simply way to determine whether a number is a multiple of
19103 five is to divide it by five and see if the division results in a
19104 remainder.  If there is no remainder, the number is a multiple of
19105 five.  Thus, seven divided by five has a remainder of two, and seven
19106 is not an integral multiple of five.  Put in slightly different
19107 language, more reminiscent of the classroom, five goes into seven
19108 once, with a remainder of two.  However, five goes into ten twice,
19109 with no remainder: ten is an integral multiple of five.
19111 @node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis
19112 @appendixsubsec Side Trip: Compute a Remainder
19114 @findex % @r{(remainder function)}
19115 @cindex Remainder function, @code{%}
19116 In Lisp, the function for computing a remainder is @code{%}.  The
19117 function returns the remainder of its first argument divided by its
19118 second argument.  As it happens, @code{%} is a function in Emacs Lisp
19119 that you cannot discover using @code{apropos}: you find nothing if you
19120 type @kbd{M-x apropos @key{RET} remainder @key{RET}}.  The only way to
19121 learn of the existence of @code{%} is to read about it in a book such
19122 as this or in the Emacs Lisp sources.  The @code{%} function is used
19123 in the code for @code{rotate-yank-pointer}, which is described in an
19124 appendix.  (@xref{rotate-yk-ptr body, , The Body of
19125 @code{rotate-yank-pointer}}.)
19127 You can try the @code{%} function by evaluating the following two
19128 expressions:
19130 @smallexample
19131 @group
19132 (% 7 5)
19134 (% 10 5)
19135 @end group
19136 @end smallexample
19138 @noindent
19139 The first expression returns 2 and the second expression returns 0.
19141 To test whether the returned value is zero or some other number, we
19142 can use the @code{zerop} function.  This function returns @code{t} if
19143 its argument, which must be a number, is zero.
19145 @smallexample
19146 @group
19147 (zerop (% 7 5))
19148      @result{} nil
19150 (zerop (% 10 5))
19151      @result{} t
19152 @end group
19153 @end smallexample
19155 Thus, the following expression will return @code{t} if the height
19156 of the graph is evenly divisible by five:
19158 @smallexample
19159 (zerop (% height 5))
19160 @end smallexample
19162 @noindent
19163 (The value of @code{height}, of course, can be found from @code{(apply
19164 'max numbers-list)}.)
19166 On the other hand, if the value of @code{height} is not a multiple of
19167 five, we want to reset the value to the next higher multiple of five.
19168 This is straightforward arithmetic using functions with which we are
19169 already familiar.  First, we divide the value of @code{height} by five
19170 to determine how many times five goes into the number.  Thus, five
19171 goes into twelve twice.  If we add one to this quotient and multiply by
19172 five, we will obtain the value of the next multiple of five that is
19173 larger than the height.  Five goes into twelve twice.  Add one to two,
19174 and multiply by five; the result is fifteen, which is the next multiple
19175 of five that is higher than twelve.  The Lisp expression for this is:
19177 @smallexample
19178 (* (1+ (/ height 5)) 5)
19179 @end smallexample
19181 @noindent
19182 For example, if you evaluate the following, the result is 15:
19184 @smallexample
19185 (* (1+ (/ 12 5)) 5)
19186 @end smallexample
19188 All through this discussion, we have been using `five' as the value
19189 for spacing labels on the Y axis; but we may want to use some other
19190 value.  For generality, we should replace `five' with a variable to
19191 which we can assign a value.  The best name I can think of for this
19192 variable is @code{Y-axis-label-spacing}.
19194 @need 1250
19195 Using this term, and an @code{if} expression, we produce the
19196 following:
19198 @smallexample
19199 @group
19200 (if (zerop (% height Y-axis-label-spacing))
19201     height
19202   ;; @r{else}
19203   (* (1+ (/ height Y-axis-label-spacing))
19204      Y-axis-label-spacing))
19205 @end group
19206 @end smallexample
19208 @noindent
19209 This expression returns the value of @code{height} itself if the height
19210 is an even multiple of the value of the @code{Y-axis-label-spacing} or
19211 else it computes and returns a value of @code{height} that is equal to
19212 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
19214 We can now include this expression in the @code{let} expression of the
19215 @code{print-graph} function (after first setting the value of
19216 @code{Y-axis-label-spacing}):
19217 @vindex Y-axis-label-spacing
19219 @smallexample
19220 @group
19221 (defvar Y-axis-label-spacing 5
19222   "Number of lines from one Y axis label to next.")
19223 @end group
19225 @group
19226 @dots{}
19227 (let* ((height (apply 'max numbers-list))
19228        (height-of-top-line
19229         (if (zerop (% height Y-axis-label-spacing))
19230             height
19231 @end group
19232 @group
19233           ;; @r{else}
19234           (* (1+ (/ height Y-axis-label-spacing))
19235              Y-axis-label-spacing)))
19236        (symbol-width (length graph-blank))))
19237 @dots{}
19238 @end group
19239 @end smallexample
19241 @noindent
19242 (Note use of the  @code{let*} function: the initial value of height is
19243 computed once by the @code{(apply 'max numbers-list)} expression and
19244 then the resulting value of  @code{height} is used to compute its
19245 final value.  @xref{fwd-para let, , The @code{let*} expression}, for
19246 more about @code{let*}.)
19248 @node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis
19249 @appendixsubsec Construct a Y Axis Element
19251 When we print the vertical axis, we want to insert strings such as
19252 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
19253 Moreover, we want the numbers and dashes to line up, so shorter
19254 numbers must be padded with leading spaces.  If some of the strings
19255 use two digit numbers, the strings with single digit numbers must
19256 include a leading blank space before the number.
19258 @findex number-to-string
19259 To figure out the length of the number, the @code{length} function is
19260 used.  But the @code{length} function works only with a string, not with
19261 a number.  So the number has to be converted from being a number to
19262 being a string.  This is done with the @code{number-to-string} function.
19263 For example,
19265 @smallexample
19266 @group
19267 (length (number-to-string 35))
19268      @result{} 2
19270 (length (number-to-string 100))
19271      @result{} 3
19272 @end group
19273 @end smallexample
19275 @noindent
19276 (@code{number-to-string} is also called @code{int-to-string}; you will
19277 see this alternative name in various sources.)
19279 In addition, in each label, each number is followed by a string such
19280 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
19281 This variable is defined with @code{defvar}:
19283 @vindex Y-axis-tic
19284 @smallexample
19285 @group
19286 (defvar Y-axis-tic " - "
19287    "String that follows number in a Y axis label.")
19288 @end group
19289 @end smallexample
19291 The length of the Y label is the sum of the length of the Y axis tic
19292 mark and the length of the number of the top of the graph.
19294 @smallexample
19295 (length (concat (number-to-string height) Y-axis-tic)))
19296 @end smallexample
19298 This value will be calculated by the @code{print-graph} function in
19299 its varlist as @code{full-Y-label-width} and passed on.  (Note that we
19300 did not think to include this in the varlist when we first proposed it.)
19302 To make a complete vertical axis label, a tic mark is concatenated
19303 with a number; and the two together may be preceded by one or more
19304 spaces depending on how long the number is.  The label consists of
19305 three parts: the (optional) leading spaces, the number, and the tic
19306 mark.  The function is passed the value of the number for the specific
19307 row, and the value of the width of the top line, which is calculated
19308 (just once) by @code{print-graph}.
19310 @smallexample
19311 @group
19312 (defun Y-axis-element (number full-Y-label-width)
19313   "Construct a NUMBERed label element.
19314 A numbered element looks like this `  5 - ',
19315 and is padded as needed so all line up with
19316 the element for the largest number."
19317 @end group
19318 @group
19319   (let* ((leading-spaces
19320          (- full-Y-label-width
19321             (length
19322              (concat (number-to-string number)
19323                      Y-axis-tic)))))
19324 @end group
19325 @group
19326     (concat
19327      (make-string leading-spaces ? )
19328      (number-to-string number)
19329      Y-axis-tic)))
19330 @end group
19331 @end smallexample
19333 The @code{Y-axis-element} function concatenates together the leading
19334 spaces, if any; the number, as a string; and the tic mark.
19336 To figure out how many leading spaces the label will need, the
19337 function subtracts the actual length of the label---the length of the
19338 number plus the length of the tic mark---from the desired label width.
19340 @findex make-string
19341 Blank spaces are inserted using the @code{make-string} function.  This
19342 function takes two arguments: the first tells it how long the string
19343 will be and the second is a symbol for the character to insert, in a
19344 special format.  The format is a question mark followed by a blank
19345 space, like this, @samp{? }.  @xref{Character Type, , Character Type,
19346 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
19347 syntax for characters.
19349 The @code{number-to-string} function is used in the concatenation
19350 expression, to convert the number to a string that is concatenated
19351 with the leading spaces and the tic mark.
19353 @node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis
19354 @appendixsubsec Create a Y Axis Column
19356 The preceding functions provide all the tools needed to construct a
19357 function that generates a list of numbered and blank strings to insert
19358 as the label for the vertical axis:
19360 @findex Y-axis-column
19361 @smallexample
19362 @group
19363 (defun Y-axis-column (height width-of-label)
19364   "Construct list of Y axis labels and blank strings.
19365 For HEIGHT of line above base and WIDTH-OF-LABEL."
19366   (let (Y-axis)
19367 @group
19368 @end group
19369     (while (> height 1)
19370       (if (zerop (% height Y-axis-label-spacing))
19371           ;; @r{Insert label.}
19372           (setq Y-axis
19373                 (cons
19374                  (Y-axis-element height width-of-label)
19375                  Y-axis))
19376 @group
19377 @end group
19378         ;; @r{Else, insert blanks.}
19379         (setq Y-axis
19380               (cons
19381                (make-string width-of-label ? )
19382                Y-axis)))
19383       (setq height (1- height)))
19384     ;; @r{Insert base line.}
19385     (setq Y-axis
19386           (cons (Y-axis-element 1 width-of-label) Y-axis))
19387     (nreverse Y-axis)))
19388 @end group
19389 @end smallexample
19391 In this function, we start with the value of @code{height} and
19392 repetitively subtract one from its value.  After each subtraction, we
19393 test to see whether the value is an integral multiple of the
19394 @code{Y-axis-label-spacing}.  If it is, we construct a numbered label
19395 using the @code{Y-axis-element} function; if not, we construct a
19396 blank label using the @code{make-string} function.  The base line
19397 consists of the number one followed by a tic mark.
19399 @need 2000
19400 @node print-Y-axis Penultimate,  , Y-axis-column, print-Y-axis
19401 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
19403 The list constructed by the @code{Y-axis-column} function is passed to
19404 the @code{print-Y-axis} function, which inserts the list as a column.
19406 @findex print-Y-axis
19407 @smallexample
19408 @group
19409 (defun print-Y-axis (height full-Y-label-width)
19410   "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
19411 Height must be the maximum height of the graph.
19412 Full width is the width of the highest label element."
19413 ;; Value of height and full-Y-label-width
19414 ;; are passed by `print-graph'.
19415 @end group
19416 @group
19417   (let ((start (point)))
19418     (insert-rectangle
19419      (Y-axis-column height full-Y-label-width))
19420     ;; @r{Place point ready for inserting graph.}
19421     (goto-char start)
19422     ;; @r{Move point forward by value of} full-Y-label-width
19423     (forward-char full-Y-label-width)))
19424 @end group
19425 @end smallexample
19427 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
19428 insert the Y axis labels created by the @code{Y-axis-column} function.
19429 In addition, it places point at the correct position for printing the body of
19430 the graph.
19432 You can test @code{print-Y-axis}:
19434 @enumerate
19435 @item
19436 Install
19438 @smallexample
19439 @group
19440 Y-axis-label-spacing
19441 Y-axis-tic
19442 Y-axis-element
19443 Y-axis-column
19444 print-Y-axis
19445 @end group
19446 @end smallexample
19448 @item
19449 Copy the following expression:
19451 @smallexample
19452 (print-Y-axis 12 5)
19453 @end smallexample
19455 @item
19456 Switch to the @file{*scratch*} buffer and place the cursor where you
19457 want the axis labels to start.
19459 @item
19460 Type @kbd{M-:} (@code{eval-expression}).
19462 @item
19463 Yank the @code{graph-body-print} expression into the minibuffer
19464 with @kbd{C-y} (@code{yank)}.
19466 @item
19467 Press @key{RET} to evaluate the expression.
19468 @end enumerate
19470 Emacs will print labels vertically, the top one being
19471 @w{@samp{10 -@w{ }}}.  (The @code{print-graph} function
19472 will pass the value of @code{height-of-top-line}, which
19473 in this case would end up as 15.)
19475 @need 2000
19476 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph
19477 @appendixsec The @code{print-X-axis} Function
19478 @cindex Axis, print horizontal
19479 @cindex X axis printing
19480 @cindex Print horizontal axis
19481 @cindex Horizontal axis printing
19483 X axis labels are much like Y axis labels, except that the tics are on a
19484 line above the numbers.  Labels should look like this:
19486 @smallexample
19487 @group
19488     |   |    |    |
19489     1   5   10   15
19490 @end group
19491 @end smallexample
19493 The first tic is under the first column of the graph and is preceded by
19494 several blank spaces.  These spaces provide room in rows above for the Y
19495 axis labels.  The second, third, fourth, and subsequent tics are all
19496 spaced equally, according to the value of @code{X-axis-label-spacing}.
19498 The second row of the X axis consists of numbers, preceded by several
19499 blank spaces and also separated according to the value of the variable
19500 @code{X-axis-label-spacing}.
19502 The value of the variable @code{X-axis-label-spacing} should itself be
19503 measured in units of @code{symbol-width}, since you may want to change
19504 the width of the symbols that you are using to print the body of the
19505 graph without changing the ways the graph is labelled.
19507 @menu
19508 * Similarities differences::    Much like @code{print-Y-axis}, but not exactly.
19509 * X Axis Tic Marks::            Create tic marks for the horizontal axis.
19510 @end menu
19512 @node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
19513 @ifnottex
19514 @unnumberedsubsec Similarities and differences
19515 @end ifnottex
19517 The @code{print-X-axis} function is constructed in more or less the
19518 same fashion as the @code{print-Y-axis} function except that it has
19519 two lines: the line of tic marks and the numbers.  We will write a
19520 separate function to print each line and then combine them within the
19521 @code{print-X-axis} function.
19523 This is a three step process:
19525 @enumerate
19526 @item
19527 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
19529 @item
19530 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
19532 @item
19533 Write a function to print both lines, the @code{print-X-axis} function,
19534 using @code{print-X-axis-tic-line} and
19535 @code{print-X-axis-numbered-line}.
19536 @end enumerate
19538 @node X Axis Tic Marks,  , Similarities differences, print-X-axis
19539 @appendixsubsec X Axis Tic Marks
19541 The first function should print the X axis tic marks.  We must specify
19542 the tic marks themselves and their spacing:
19544 @smallexample
19545 @group
19546 (defvar X-axis-label-spacing
19547   (if (boundp 'graph-blank)
19548       (* 5 (length graph-blank)) 5)
19549   "Number of units from one X axis label to next.")
19550 @end group
19551 @end smallexample
19553 @noindent
19554 (Note that the value of @code{graph-blank} is set by another
19555 @code{defvar}.  The @code{boundp} predicate checks whether it has
19556 already been set; @code{boundp} returns @code{nil} if it has not.
19557 If @code{graph-blank} were unbound and we did not use this conditional
19558 construction, in GNU Emacs 21, we would enter the debugger and see an
19559 error message saying
19560 @samp{@w{Debugger entered--Lisp error:} @w{(void-variable graph-blank)}}.)
19562 @need 1200
19563 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
19565 @smallexample
19566 @group
19567 (defvar X-axis-tic-symbol "|"
19568   "String to insert to point to a column in X axis.")
19569 @end group
19570 @end smallexample
19572 @need 1250
19573 The goal is to make a line that looks like this:
19575 @smallexample
19576        |   |    |    |
19577 @end smallexample
19579 The first tic is indented so that it is under the first column, which is
19580 indented to provide space for the Y axis labels.
19582 A tic element consists of the blank spaces that stretch from one tic to
19583 the next plus a tic symbol.  The number of blanks is determined by the
19584 width of the tic symbol and the @code{X-axis-label-spacing}.
19586 @need 1250
19587 The code looks like this:
19589 @smallexample
19590 @group
19591 ;;; X-axis-tic-element
19592 @dots{}
19593 (concat
19594  (make-string
19595   ;; @r{Make a string of blanks.}
19596   (-  (* symbol-width X-axis-label-spacing)
19597       (length X-axis-tic-symbol))
19598   ? )
19599  ;; @r{Concatenate blanks with tic symbol.}
19600  X-axis-tic-symbol)
19601 @dots{}
19602 @end group
19603 @end smallexample
19605 Next, we determine how many blanks are needed to indent the first tic
19606 mark to the first column of the graph.  This uses the value of
19607 @code{full-Y-label-width} passed it by the @code{print-graph} function.
19609 @need 1250
19610 The code to make @code{X-axis-leading-spaces}
19611 looks like this:
19613 @smallexample
19614 @group
19615 ;; X-axis-leading-spaces
19616 @dots{}
19617 (make-string full-Y-label-width ? )
19618 @dots{}
19619 @end group
19620 @end smallexample
19622 We also need to determine the length of the horizontal axis, which is
19623 the length of the numbers list, and the number of tics in the horizontal
19624 axis:
19626 @smallexample
19627 @group
19628 ;; X-length
19629 @dots{}
19630 (length numbers-list)
19631 @end group
19633 @group
19634 ;; tic-width
19635 @dots{}
19636 (* symbol-width X-axis-label-spacing)
19637 @end group
19639 @group
19640 ;; number-of-X-tics
19641 (if (zerop (% (X-length tic-width)))
19642     (/ (X-length tic-width))
19643   (1+ (/ (X-length tic-width))))
19644 @end group
19645 @end smallexample
19647 @need 1250
19648 All this leads us directly to the function for printing the X axis tic line:
19650 @findex print-X-axis-tic-line
19651 @smallexample
19652 @group
19653 (defun print-X-axis-tic-line
19654   (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
19655   "Print tics for X axis."
19656     (insert X-axis-leading-spaces)
19657     (insert X-axis-tic-symbol)  ; @r{Under first column.}
19658 @end group
19659 @group
19660     ;; @r{Insert second tic in the right spot.}
19661     (insert (concat
19662              (make-string
19663               (-  (* symbol-width X-axis-label-spacing)
19664                   ;; @r{Insert white space up to second tic symbol.}
19665                   (* 2 (length X-axis-tic-symbol)))
19666               ? )
19667              X-axis-tic-symbol))
19668 @end group
19669 @group
19670     ;; @r{Insert remaining tics.}
19671     (while (> number-of-X-tics 1)
19672       (insert X-axis-tic-element)
19673       (setq number-of-X-tics (1- number-of-X-tics))))
19674 @end group
19675 @end smallexample
19677 The line of numbers is equally straightforward:
19679 @need 1250
19680 First, we create a numbered element with blank spaces before each number:
19682 @findex X-axis-element
19683 @smallexample
19684 @group
19685 (defun X-axis-element (number)
19686   "Construct a numbered X axis element."
19687   (let ((leading-spaces
19688          (-  (* symbol-width X-axis-label-spacing)
19689              (length (number-to-string number)))))
19690     (concat (make-string leading-spaces ? )
19691             (number-to-string number))))
19692 @end group
19693 @end smallexample
19695 Next, we create the function to print the numbered line, starting with
19696 the number ``1'' under the first column:
19698 @findex print-X-axis-numbered-line
19699 @smallexample
19700 @group
19701 (defun print-X-axis-numbered-line
19702   (number-of-X-tics X-axis-leading-spaces)
19703   "Print line of X-axis numbers"
19704   (let ((number X-axis-label-spacing))
19705     (insert X-axis-leading-spaces)
19706     (insert "1")
19707 @end group
19708 @group
19709     (insert (concat
19710              (make-string
19711               ;; @r{Insert white space up to next number.}
19712               (-  (* symbol-width X-axis-label-spacing) 2)
19713               ? )
19714              (number-to-string number)))
19715 @end group
19716 @group
19717     ;; @r{Insert remaining numbers.}
19718     (setq number (+ number X-axis-label-spacing))
19719     (while (> number-of-X-tics 1)
19720       (insert (X-axis-element number))
19721       (setq number (+ number X-axis-label-spacing))
19722       (setq number-of-X-tics (1- number-of-X-tics)))))
19723 @end group
19724 @end smallexample
19726 Finally, we need to write the @code{print-X-axis} that uses
19727 @code{print-X-axis-tic-line} and
19728 @code{print-X-axis-numbered-line}.
19730 The function must determine the local values of the variables used by both
19731 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
19732 then it must call them.  Also, it must print the carriage return that
19733 separates the two lines.
19735 The function consists of a varlist that specifies five local variables,
19736 and calls to each of the two line printing functions:
19738 @findex print-X-axis
19739 @smallexample
19740 @group
19741 (defun print-X-axis (numbers-list)
19742   "Print X axis labels to length of NUMBERS-LIST."
19743   (let* ((leading-spaces
19744           (make-string full-Y-label-width ? ))
19745 @end group
19746 @group
19747        ;; symbol-width @r{is provided by} graph-body-print
19748        (tic-width (* symbol-width X-axis-label-spacing))
19749        (X-length (length numbers-list))
19750 @end group
19751 @group
19752        (X-tic
19753         (concat
19754          (make-string
19755 @end group
19756 @group
19757           ;; @r{Make a string of blanks.}
19758           (-  (* symbol-width X-axis-label-spacing)
19759               (length X-axis-tic-symbol))
19760           ? )
19761 @end group
19762 @group
19763          ;; @r{Concatenate blanks with tic symbol.}
19764          X-axis-tic-symbol))
19765 @end group
19766 @group
19767        (tic-number
19768         (if (zerop (% X-length tic-width))
19769             (/ X-length tic-width)
19770           (1+ (/ X-length tic-width)))))
19771 @end group
19772 @group
19773     (print-X-axis-tic-line tic-number leading-spaces X-tic)
19774     (insert "\n")
19775     (print-X-axis-numbered-line tic-number leading-spaces)))
19776 @end group
19777 @end smallexample
19779 @need 1250
19780 You can test @code{print-X-axis}:
19782 @enumerate
19783 @item
19784 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
19785 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
19786 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
19788 @item
19789 Copy the following expression:
19791 @smallexample
19792 @group
19793 (progn
19794  (let ((full-Y-label-width 5)
19795        (symbol-width 1))
19796    (print-X-axis
19797     '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
19798 @end group
19799 @end smallexample
19801 @item
19802 Switch to the @file{*scratch*} buffer and place the cursor where you
19803 want the axis labels to start.
19805 @item
19806 Type @kbd{M-:} (@code{eval-expression}).
19808 @item
19809 Yank the test expression into the minibuffer
19810 with @kbd{C-y} (@code{yank)}.
19812 @item
19813 Press @key{RET} to evaluate the expression.
19814 @end enumerate
19816 @need 1250
19817 Emacs will print the horizontal axis like this:
19818 @sp 1
19820 @smallexample
19821 @group
19822      |   |    |    |    |
19823      1   5   10   15   20
19824 @end group
19825 @end smallexample
19827 @node Print Whole Graph,  , print-X-axis, Full Graph
19828 @appendixsec Printing the Whole Graph
19829 @cindex Printing the whole graph
19830 @cindex Whole graph printing
19831 @cindex Graph, printing all
19833 Now we are nearly ready to print the whole graph.
19835 The function to print the graph with the proper labels follows the
19836 outline we created earlier (@pxref{Full Graph, , A Graph with Labelled
19837 Axes}), but with additions.
19839 @need 1250
19840 Here is the outline:
19842 @smallexample
19843 @group
19844 (defun print-graph (numbers-list)
19845   "@var{documentation}@dots{}"
19846   (let ((height  @dots{}
19847         @dots{}))
19848 @end group
19849 @group
19850     (print-Y-axis height @dots{} )
19851     (graph-body-print numbers-list)
19852     (print-X-axis @dots{} )))
19853 @end group
19854 @end smallexample
19856 @menu
19857 * The final version::           A few changes.
19858 * Test print-graph::            Run a short test.
19859 * Graphing words in defuns::    Executing the final code.
19860 * lambda::                      How to write an anonymous function.
19861 * mapcar::                      Apply a function to elements of a list.
19862 * Another Bug::                 Yet another bug @dots{} most insidious.
19863 * Final printed graph::         The graph itself!
19864 @end menu
19866 @node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
19867 @ifnottex
19868 @unnumberedsubsec Changes for the Final Version
19869 @end ifnottex
19871 The final version is different from what we planned in two ways:
19872 first, it contains additional values calculated once in the varlist;
19873 second, it carries an option to specify the labels' increment per row.
19874 This latter feature turns out to be essential; otherwise, a graph may
19875 have more rows than fit on a display or on a sheet of paper.
19877 @need 1500
19878 This new feature requires a change to the @code{Y-axis-column}
19879 function, to add @code{vertical-step} to it.  The function looks like
19880 this:
19882 @findex Y-axis-column @r{Final version.}
19883 @smallexample
19884 @group
19885 ;;; @r{Final version.}
19886 (defun Y-axis-column
19887   (height width-of-label &optional vertical-step)
19888   "Construct list of labels for Y axis.
19889 HEIGHT is maximum height of graph.
19890 WIDTH-OF-LABEL is maximum width of label.
19891 VERTICAL-STEP, an option, is a positive integer
19892 that specifies how much a Y axis label increments
19893 for each line.  For example, a step of 5 means
19894 that each line is five units of the graph."
19895 @end group
19896 @group
19897   (let (Y-axis
19898         (number-per-line (or vertical-step 1)))
19899     (while (> height 1)
19900       (if (zerop (% height Y-axis-label-spacing))
19901 @end group
19902 @group
19903           ;; @r{Insert label.}
19904           (setq Y-axis
19905                 (cons
19906                  (Y-axis-element
19907                   (* height number-per-line)
19908                   width-of-label)
19909                  Y-axis))
19910 @end group
19911 @group
19912         ;; @r{Else, insert blanks.}
19913         (setq Y-axis
19914               (cons
19915                (make-string width-of-label ? )
19916                Y-axis)))
19917       (setq height (1- height)))
19918 @end group
19919 @group
19920     ;; @r{Insert base line.}
19921     (setq Y-axis (cons (Y-axis-element
19922                         (or vertical-step 1)
19923                         width-of-label)
19924                        Y-axis))
19925     (nreverse Y-axis)))
19926 @end group
19927 @end smallexample
19929 The values for the maximum height of graph and the width of a symbol
19930 are computed by @code{print-graph} in its @code{let} expression; so
19931 @code{graph-body-print} must be changed to accept them.
19933 @findex graph-body-print @r{Final version.}
19934 @smallexample
19935 @group
19936 ;;; @r{Final version.}
19937 (defun graph-body-print (numbers-list height symbol-width)
19938   "Print a bar graph of the NUMBERS-LIST.
19939 The numbers-list consists of the Y-axis values.
19940 HEIGHT is maximum height of graph.
19941 SYMBOL-WIDTH is number of each column."
19942 @end group
19943 @group
19944   (let (from-position)
19945     (while numbers-list
19946       (setq from-position (point))
19947       (insert-rectangle
19948        (column-of-graph height (car numbers-list)))
19949       (goto-char from-position)
19950       (forward-char symbol-width)
19951 @end group
19952 @group
19953       ;; @r{Draw graph column by column.}
19954       (sit-for 0)
19955       (setq numbers-list (cdr numbers-list)))
19956     ;; @r{Place point for X axis labels.}
19957     (forward-line height)
19958     (insert "\n")))
19959 @end group
19960 @end smallexample
19962 @need 1250
19963 Finally, the code for the @code{print-graph} function:
19965 @findex print-graph @r{Final version.}
19966 @smallexample
19967 @group
19968 ;;; @r{Final version.}
19969 (defun print-graph
19970   (numbers-list &optional vertical-step)
19971   "Print labelled bar graph of the NUMBERS-LIST.
19972 The numbers-list consists of the Y-axis values.
19973 @end group
19975 @group
19976 Optionally, VERTICAL-STEP, a positive integer,
19977 specifies how much a Y axis label increments for
19978 each line.  For example, a step of 5 means that
19979 each row is five units."
19980 @end group
19981 @group
19982   (let* ((symbol-width (length graph-blank))
19983          ;; @code{height} @r{is both the largest number}
19984          ;; @r{and the number with the most digits.}
19985          (height (apply 'max numbers-list))
19986 @end group
19987 @group
19988          (height-of-top-line
19989           (if (zerop (% height Y-axis-label-spacing))
19990               height
19991             ;; @r{else}
19992             (* (1+ (/ height Y-axis-label-spacing))
19993                Y-axis-label-spacing)))
19994 @end group
19995 @group
19996          (vertical-step (or vertical-step 1))
19997          (full-Y-label-width
19998           (length
19999 @end group
20000 @group
20001            (concat
20002             (number-to-string
20003              (* height-of-top-line vertical-step))
20004             Y-axis-tic))))
20005 @end group
20007 @group
20008     (print-Y-axis
20009      height-of-top-line full-Y-label-width vertical-step)
20010 @end group
20011 @group
20012     (graph-body-print
20013      numbers-list height-of-top-line symbol-width)
20014     (print-X-axis numbers-list)))
20015 @end group
20016 @end smallexample
20018 @node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph
20019 @appendixsubsec Testing @code{print-graph}
20021 @need 1250
20022 We can test the @code{print-graph} function with a short list of numbers:
20024 @enumerate
20025 @item
20026 Install the final versions of @code{Y-axis-column},
20027 @code{graph-body-print}, and @code{print-graph} (in addition to the
20028 rest of the code.)
20030 @item
20031 Copy the following expression:
20033 @smallexample
20034 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
20035 @end smallexample
20037 @item
20038 Switch to the @file{*scratch*} buffer and place the cursor where you
20039 want the axis labels to start.
20041 @item
20042 Type @kbd{M-:} (@code{eval-expression}).
20044 @item
20045 Yank the test expression into the minibuffer
20046 with @kbd{C-y} (@code{yank)}.
20048 @item
20049 Press @key{RET} to evaluate the expression.
20050 @end enumerate
20052 @need 1250
20053 Emacs will print a graph that looks like this:
20055 @smallexample
20056 @group
20057 10 -
20060          *
20061         **   *
20062  5 -   ****  *
20063        **** ***
20064      * *********
20065      ************
20066  1 - *************
20068      |   |    |    |
20069      1   5   10   15
20070 @end group
20071 @end smallexample
20073 @need 1200
20074 On the other hand, if you pass @code{print-graph} a
20075 @code{vertical-step} value of 2, by evaluating this expression:
20077 @smallexample
20078 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
20079 @end smallexample
20081 @need 1250
20082 @noindent
20083 The graph looks like this:
20085 @smallexample
20086 @group
20087 20 -
20090          *
20091         **   *
20092 10 -   ****  *
20093        **** ***
20094      * *********
20095      ************
20096  2 - *************
20098      |   |    |    |
20099      1   5   10   15
20100 @end group
20101 @end smallexample
20103 @noindent
20104 (A question: is the `2' on the bottom of the vertical axis a bug or a
20105 feature?  If you think it is a bug, and should be a `1' instead, (or
20106 even a `0'), you can modify the sources.)
20108 @node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph
20109 @appendixsubsec Graphing Numbers of Words and Symbols
20111 Now for the graph for which all this code was written: a graph that
20112 shows how many function definitions contain fewer than 10 words and
20113 symbols, how many contain between 10 and 19 words and symbols, how
20114 many contain between 20 and 29 words and symbols, and so on.
20116 This is a multi-step process.  First make sure you have loaded all the
20117 requisite code.
20119 @need 1500
20120 It is a good idea to reset the value of @code{top-of-ranges} in case
20121 you have set it to some different value.  You can evaluate the
20122 following:
20124 @smallexample
20125 @group
20126 (setq top-of-ranges
20127  '(10  20  30  40  50
20128    60  70  80  90 100
20129   110 120 130 140 150
20130   160 170 180 190 200
20131   210 220 230 240 250
20132   260 270 280 290 300)
20133 @end group
20134 @end smallexample
20136 @noindent
20137 Next create a list of the number of words and symbols in each range.
20139 @need 1500
20140 @noindent
20141 Evaluate the following:
20143 @smallexample
20144 @group
20145 (setq list-for-graph
20146        (defuns-per-range
20147          (sort
20148           (recursive-lengths-list-many-files
20149            (directory-files "/usr/local/emacs/lisp"
20150                             t ".+el$"))
20151           '<)
20152          top-of-ranges))
20153 @end group
20154 @end smallexample
20156 @noindent
20157 On my old machine, this took about an hour.  It looked though 303 Lisp
20158 files in my copy of Emacs version 19.23.  After all that computing,
20159 the @code{list-for-graph} had this value:
20161 @smallexample
20162 @group
20163 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
20164 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
20165 @end group
20166 @end smallexample
20168 @noindent
20169 This means that my copy of Emacs had 537 function definitions with
20170 fewer than 10 words or symbols in them, 1,027 function definitions
20171 with 10 to 19 words or symbols in them, 955 function definitions with
20172 20 to 29 words or symbols in them, and so on.
20174 Clearly, just by looking at this list we can see that most function
20175 definitions contain ten to thirty words and symbols.
20177 Now for printing.  We do @emph{not} want to print a graph that is
20178 1,030 lines high @dots{}  Instead, we should print a graph that is
20179 fewer than twenty-five lines high.  A graph that height can be
20180 displayed on almost any monitor, and easily printed on a sheet of paper.
20182 This means that each value in @code{list-for-graph} must be reduced to
20183 one-fiftieth its present value.
20185 Here is a short function to do just that, using two functions we have
20186 not yet seen, @code{mapcar} and @code{lambda}.
20188 @smallexample
20189 @group
20190 (defun one-fiftieth (full-range)
20191   "Return list, each number one-fiftieth of previous."
20192  (mapcar '(lambda (arg) (/ arg 50)) full-range))
20193 @end group
20194 @end smallexample
20196 @node lambda, mapcar, Graphing words in defuns, Print Whole Graph
20197 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
20198 @cindex Anonymous function
20199 @findex lambda
20201 @code{lambda} is the symbol for an anonymous function, a function
20202 without a name.  Every time you use an anonymous function, you need to
20203 include its whole body.
20205 @need 1250
20206 @noindent
20207 Thus,
20209 @smallexample
20210 (lambda (arg) (/ arg 50))
20211 @end smallexample
20213 @noindent
20214 is a function definition that says `return the value resulting from
20215 dividing whatever is passed to me as @code{arg} by 50'.
20217 @need 1200
20218 Earlier, for example, we had a function @code{multiply-by-seven}; it
20219 multiplied its argument by 7.  This function is similar, except it
20220 divides its argument by 50; and, it has no name.  The anonymous
20221 equivalent of @code{multiply-by-seven} is:
20223 @smallexample
20224 (lambda (number) (* 7 number))
20225 @end smallexample
20227 @noindent
20228 (@xref{defun, ,  The @code{defun} Special Form}.)
20230 @need 1250
20231 @noindent
20232 If we want to multiply 3 by 7, we can write:
20234 @c !!! Clear print-postscript-figures if the computer formatting this
20235 @c     document is too small and cannot handle all the diagrams and figures.
20236 @c clear print-postscript-figures
20237 @c set print-postscript-figures
20238 @c lambda example diagram #1
20239 @ifnottex
20240 @smallexample
20241 @group
20242 (multiply-by-seven 3)
20243  \_______________/ ^
20244          |         |
20245       function  argument
20246 @end group
20247 @end smallexample
20248 @end ifnottex
20249 @ifset print-postscript-figures
20250 @sp 1
20251 @tex
20252 @image{lambda-1}
20253 %%%% old method of including an image
20254 % \input /usr/local/lib/tex/inputs/psfig.tex
20255 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
20256 % \catcode`\@=0 %
20257 @end tex
20258 @sp 1
20259 @end ifset
20260 @ifclear print-postscript-figures
20261 @iftex
20262 @smallexample
20263 @group
20264 (multiply-by-seven 3)
20265  \_______________/ ^
20266          |         |
20267       function  argument
20268 @end group
20269 @end smallexample
20270 @end iftex
20271 @end ifclear
20273 @noindent
20274 This expression returns 21.
20276 @need 1250
20277 @noindent
20278 Similarly, we can write:
20280 @c lambda example diagram #2
20281 @ifnottex
20282 @smallexample
20283 @group
20284 ((lambda (number) (* 7 number)) 3)
20285  \____________________________/ ^
20286                |                |
20287       anonymous function     argument
20288 @end group
20289 @end smallexample
20290 @end ifnottex
20291 @ifset print-postscript-figures
20292 @sp 1
20293 @tex
20294 @image{lambda-2}
20295 %%%% old method of including an image
20296 % \input /usr/local/lib/tex/inputs/psfig.tex
20297 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
20298 % \catcode`\@=0 %
20299 @end tex
20300 @sp 1
20301 @end ifset
20302 @ifclear print-postscript-figures
20303 @iftex
20304 @smallexample
20305 @group
20306 ((lambda (number) (* 7 number)) 3)
20307  \____________________________/ ^
20308                |                |
20309       anonymous function     argument
20310 @end group
20311 @end smallexample
20312 @end iftex
20313 @end ifclear
20315 @need 1250
20316 @noindent
20317 If we want to divide 100 by 50, we can write:
20319 @c lambda example diagram #3
20320 @ifnottex
20321 @smallexample
20322 @group
20323 ((lambda (arg) (/ arg 50)) 100)
20324  \______________________/  \_/
20325              |              |
20326     anonymous function   argument
20327 @end group
20328 @end smallexample
20329 @end ifnottex
20330 @ifset print-postscript-figures
20331 @sp 1
20332 @tex
20333 @image{lambda-3}
20334 %%%% old method of including an image
20335 % \input /usr/local/lib/tex/inputs/psfig.tex
20336 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
20337 % \catcode`\@=0 %
20338 @end tex
20339 @sp 1
20340 @end ifset
20341 @ifclear print-postscript-figures
20342 @iftex
20343 @smallexample
20344 @group
20345 ((lambda (arg) (/ arg 50)) 100)
20346  \______________________/  \_/
20347              |              |
20348     anonymous function   argument
20349 @end group
20350 @end smallexample
20351 @end iftex
20352 @end ifclear
20354 @noindent
20355 This expression returns 2.  The 100 is passed to the function, which
20356 divides that number by 50.
20358 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
20359 Lisp Reference Manual}, for more about @code{lambda}.  Lisp and lambda
20360 expressions derive from the Lambda Calculus.
20362 @node mapcar, Another Bug, lambda, Print Whole Graph
20363 @appendixsubsec The @code{mapcar} Function
20364 @findex mapcar
20366 @code{mapcar} is a function that calls its first argument with each
20367 element of its second argument, in turn.  The second argument must be
20368 a sequence.
20370 The @samp{map} part of the name comes from the mathematical phrase,
20371 `mapping over a domain', meaning to apply a function to each of the
20372 elements in a domain.  The mathematical phrase is based on the
20373 metaphor of a surveyor walking, one step at a time, over an area he is
20374 mapping.  And @samp{car}, of course, comes from the Lisp notion of the
20375 first of a list.
20377 @need 1250
20378 @noindent
20379 For example,
20381 @smallexample
20382 @group
20383 (mapcar '1+ '(2 4 6))
20384      @result{} (3 5 7)
20385 @end group
20386 @end smallexample
20388 @noindent
20389 The function @code{1+} which adds one to its argument, is executed on
20390 @emph{each} element of the list, and a new list is returned.
20392 Contrast this with @code{apply}, which applies its first argument to
20393 all the remaining.
20394 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
20395 @code{apply}.)
20397 @need 1250
20398 In the definition of @code{one-fiftieth}, the first argument is the
20399 anonymous function:
20401 @smallexample
20402 (lambda (arg) (/ arg 50))
20403 @end smallexample
20405 @noindent
20406 and the second argument is @code{full-range}, which will be bound to
20407 @code{list-for-graph}.
20409 @need 1250
20410 The whole expression looks like this:
20412 @smallexample
20413 (mapcar '(lambda (arg) (/ arg 50)) full-range))
20414 @end smallexample
20416 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
20417 Lisp Reference Manual}, for more about @code{mapcar}.
20419 Using the @code{one-fiftieth} function, we can generate a list in
20420 which each element is one-fiftieth the size of the corresponding
20421 element in @code{list-for-graph}.
20423 @smallexample
20424 @group
20425 (setq fiftieth-list-for-graph
20426       (one-fiftieth list-for-graph))
20427 @end group
20428 @end smallexample
20430 @need 1250
20431 The resulting list looks like this:
20433 @smallexample
20434 @group
20435 (10 20 19 15 11 9 6 5 4 3 3 2 2
20436 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
20437 @end group
20438 @end smallexample
20440 @noindent
20441 This, we are almost ready to print!  (We also notice the loss of
20442 information: many of the higher ranges are 0, meaning that fewer than
20443 50 defuns had that many words or symbols---but not necessarily meaning
20444 that none had that many words or symbols.)
20446 @node Another Bug, Final printed graph, mapcar, Print Whole Graph
20447 @appendixsubsec Another Bug @dots{} Most Insidious
20448 @cindex Bug, most insidious type
20449 @cindex Insidious type of bug
20451 I said `almost ready to print'!  Of course, there is a bug in the
20452 @code{print-graph} function @dots{}  It has a @code{vertical-step}
20453 option, but not a @code{horizontal-step} option.  The
20454 @code{top-of-range} scale goes from 10 to 300 by tens.  But the
20455 @code{print-graph} function will print only by ones.
20457 This is a classic example of what some consider the most insidious
20458 type of bug, the bug of omission.  This is not the kind of bug you can
20459 find by studying the code, for it is not in the code; it is an omitted
20460 feature.  Your best actions are to try your program early and often;
20461 and try to arrange, as much as you can, to write code that is easy to
20462 understand and easy to change.  Try to be aware, whenever you can,
20463 that whatever you have written, @emph{will} be rewritten, if not soon,
20464 eventually.  A hard maxim to follow.
20466 It is the @code{print-X-axis-numbered-line} function that needs the
20467 work; and then the @code{print-X-axis} and the @code{print-graph}
20468 functions need to be adapted.  Not much needs to be done; there is one
20469 nicety: the numbers ought to line up under the tic marks.  This takes
20470 a little thought.
20472 @need 1250
20473 Here is the corrected @code{print-X-axis-numbered-line}:
20475 @smallexample
20476 @group
20477 (defun print-X-axis-numbered-line
20478   (number-of-X-tics X-axis-leading-spaces
20479    &optional horizontal-step)
20480   "Print line of X-axis numbers"
20481   (let ((number X-axis-label-spacing)
20482         (horizontal-step (or horizontal-step 1)))
20483 @end group
20484 @group
20485     (insert X-axis-leading-spaces)
20486     ;; @r{Delete extra leading spaces.}
20487     (delete-char
20488      (- (1-
20489          (length (number-to-string horizontal-step)))))
20490     (insert (concat
20491              (make-string
20492 @end group
20493 @group
20494               ;; @r{Insert white space.}
20495               (-  (* symbol-width
20496                      X-axis-label-spacing)
20497                   (1-
20498                    (length
20499                     (number-to-string horizontal-step)))
20500                   2)
20501               ? )
20502              (number-to-string
20503               (* number horizontal-step))))
20504 @end group
20505 @group
20506     ;; @r{Insert remaining numbers.}
20507     (setq number (+ number X-axis-label-spacing))
20508     (while (> number-of-X-tics 1)
20509       (insert (X-axis-element
20510                (* number horizontal-step)))
20511       (setq number (+ number X-axis-label-spacing))
20512       (setq number-of-X-tics (1- number-of-X-tics)))))
20513 @end group
20514 @end smallexample
20516 @need 1500
20517 If you are reading this in Info, you can see the new versions of
20518 @code{print-X-axis} @code{print-graph} and evaluate them.  If you are
20519 reading this in a printed book, you can see the changed lines here
20520 (the full text is too much to print).
20522 @iftex
20523 @smallexample
20524 @group
20525 (defun print-X-axis (numbers-list horizontal-step)
20526   @dots{}
20527     (print-X-axis-numbered-line
20528      tic-number leading-spaces horizontal-step))
20529 @end group
20530 @end smallexample
20532 @smallexample
20533 @group
20534 (defun print-graph
20535   (numbers-list
20536    &optional vertical-step horizontal-step)
20537   @dots{}
20538     (print-X-axis numbers-list horizontal-step))
20539 @end group
20540 @end smallexample
20541 @end iftex
20543 @ifnottex
20544 @smallexample
20545 @group
20546 (defun print-X-axis (numbers-list horizontal-step)
20547   "Print X axis labels to length of NUMBERS-LIST.
20548 Optionally, HORIZONTAL-STEP, a positive integer,
20549 specifies how much an X  axis label increments for
20550 each column."
20551 @end group
20552 @group
20553 ;; Value of symbol-width and full-Y-label-width
20554 ;; are passed by `print-graph'.
20555   (let* ((leading-spaces
20556           (make-string full-Y-label-width ? ))
20557        ;; symbol-width @r{is provided by} graph-body-print
20558        (tic-width (* symbol-width X-axis-label-spacing))
20559        (X-length (length numbers-list))
20560 @end group
20561 @group
20562        (X-tic
20563         (concat
20564          (make-string
20565           ;; @r{Make a string of blanks.}
20566           (-  (* symbol-width X-axis-label-spacing)
20567               (length X-axis-tic-symbol))
20568           ? )
20569 @end group
20570 @group
20571          ;; @r{Concatenate blanks with tic symbol.}
20572          X-axis-tic-symbol))
20573        (tic-number
20574         (if (zerop (% X-length tic-width))
20575             (/ X-length tic-width)
20576           (1+ (/ X-length tic-width)))))
20577 @end group
20579 @group
20580     (print-X-axis-tic-line
20581      tic-number leading-spaces X-tic)
20582     (insert "\n")
20583     (print-X-axis-numbered-line
20584      tic-number leading-spaces horizontal-step)))
20585 @end group
20586 @end smallexample
20588 @smallexample
20589 @group
20590 (defun print-graph
20591   (numbers-list &optional vertical-step horizontal-step)
20592   "Print labelled bar graph of the NUMBERS-LIST.
20593 The numbers-list consists of the Y-axis values.
20594 @end group
20596 @group
20597 Optionally, VERTICAL-STEP, a positive integer,
20598 specifies how much a Y axis label increments for
20599 each line.  For example, a step of 5 means that
20600 each row is five units.
20601 @end group
20603 @group
20604 Optionally, HORIZONTAL-STEP, a positive integer,
20605 specifies how much an X  axis label increments for
20606 each column."
20607   (let* ((symbol-width (length graph-blank))
20608          ;; @code{height} @r{is both the largest number}
20609          ;; @r{and the number with the most digits.}
20610          (height (apply 'max numbers-list))
20611 @end group
20612 @group
20613          (height-of-top-line
20614           (if (zerop (% height Y-axis-label-spacing))
20615               height
20616             ;; @r{else}
20617             (* (1+ (/ height Y-axis-label-spacing))
20618                Y-axis-label-spacing)))
20619 @end group
20620 @group
20621          (vertical-step (or vertical-step 1))
20622          (full-Y-label-width
20623           (length
20624            (concat
20625             (number-to-string
20626              (* height-of-top-line vertical-step))
20627             Y-axis-tic))))
20628 @end group
20629 @group
20630     (print-Y-axis
20631      height-of-top-line full-Y-label-width vertical-step)
20632     (graph-body-print
20633         numbers-list height-of-top-line symbol-width)
20634     (print-X-axis numbers-list horizontal-step)))
20635 @end group
20636 @end smallexample
20637 @end ifnottex
20639 @ignore
20640 Graphing Definitions Re-listed
20642 @need 1250
20643 Here are all the graphing definitions in their final form:
20645 @smallexample
20646 @group
20647 (defvar top-of-ranges
20648  '(10  20  30  40  50
20649    60  70  80  90 100
20650   110 120 130 140 150
20651   160 170 180 190 200
20652   210 220 230 240 250)
20653  "List specifying ranges for `defuns-per-range'.")
20654 @end group
20656 @group
20657 (defvar graph-symbol "*"
20658   "String used as symbol in graph, usually an asterisk.")
20659 @end group
20661 @group
20662 (defvar graph-blank " "
20663   "String used as blank in graph, usually a blank space.
20664 graph-blank must be the same number of columns wide
20665 as graph-symbol.")
20666 @end group
20668 @group
20669 (defvar Y-axis-tic " - "
20670    "String that follows number in a Y axis label.")
20671 @end group
20673 @group
20674 (defvar Y-axis-label-spacing 5
20675   "Number of lines from one Y axis label to next.")
20676 @end group
20678 @group
20679 (defvar X-axis-tic-symbol "|"
20680   "String to insert to point to a column in X axis.")
20681 @end group
20683 @group
20684 (defvar X-axis-label-spacing
20685   (if (boundp 'graph-blank)
20686       (* 5 (length graph-blank)) 5)
20687   "Number of units from one X axis label to next.")
20688 @end group
20689 @end smallexample
20691 @smallexample
20692 @group
20693 (defun count-words-in-defun ()
20694   "Return the number of words and symbols in a defun."
20695   (beginning-of-defun)
20696   (let ((count 0)
20697         (end (save-excursion (end-of-defun) (point))))
20698 @end group
20700 @group
20701     (while
20702         (and (< (point) end)
20703              (re-search-forward
20704               "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
20705               end t))
20706       (setq count (1+ count)))
20707     count))
20708 @end group
20709 @end smallexample
20711 @smallexample
20712 @group
20713 (defun lengths-list-file (filename)
20714   "Return list of definitions' lengths within FILE.
20715 The returned list is a list of numbers.
20716 Each number is the number of words or
20717 symbols in one function definition."
20718 @end group
20720 @group
20721   (message "Working on `%s' ... " filename)
20722   (save-excursion
20723     (let ((buffer (find-file-noselect filename))
20724           (lengths-list))
20725       (set-buffer buffer)
20726       (setq buffer-read-only t)
20727       (widen)
20728       (goto-char (point-min))
20729 @end group
20731 @group
20732       (while (re-search-forward "^(defun" nil t)
20733         (setq lengths-list
20734               (cons (count-words-in-defun) lengths-list)))
20735       (kill-buffer buffer)
20736       lengths-list)))
20737 @end group
20738 @end smallexample
20740 @smallexample
20741 @group
20742 (defun lengths-list-many-files (list-of-files)
20743   "Return list of lengths of defuns in LIST-OF-FILES."
20744   (let (lengths-list)
20745 ;;; @r{true-or-false-test}
20746     (while list-of-files
20747       (setq lengths-list
20748             (append
20749              lengths-list
20750 @end group
20751 @group
20752 ;;; @r{Generate a lengths' list.}
20753              (lengths-list-file
20754               (expand-file-name (car list-of-files)))))
20755 ;;; @r{Make files' list shorter.}
20756       (setq list-of-files (cdr list-of-files)))
20757 ;;; @r{Return final value of lengths' list.}
20758     lengths-list))
20759 @end group
20760 @end smallexample
20762 @smallexample
20763 @group
20764 (defun defuns-per-range (sorted-lengths top-of-ranges)
20765   "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
20766   (let ((top-of-range (car top-of-ranges))
20767         (number-within-range 0)
20768         defuns-per-range-list)
20769 @end group
20771 @group
20772     ;; @r{Outer loop.}
20773     (while top-of-ranges
20775       ;; @r{Inner loop.}
20776       (while (and
20777               ;; @r{Need number for numeric test.}
20778               (car sorted-lengths)
20779               (< (car sorted-lengths) top-of-range))
20781         ;; @r{Count number of definitions within current range.}
20782         (setq number-within-range (1+ number-within-range))
20783         (setq sorted-lengths (cdr sorted-lengths)))
20784 @end group
20786 @group
20787       ;; @r{Exit inner loop but remain within outer loop.}
20789       (setq defuns-per-range-list
20790             (cons number-within-range defuns-per-range-list))
20791       (setq number-within-range 0)      ; @r{Reset count to zero.}
20793       ;; @r{Move to next range.}
20794       (setq top-of-ranges (cdr top-of-ranges))
20795       ;; @r{Specify next top of range value.}
20796       (setq top-of-range (car top-of-ranges)))
20797 @end group
20799 @group
20800     ;; @r{Exit outer loop and count the number of defuns larger than}
20801     ;; @r{  the largest top-of-range value.}
20802     (setq defuns-per-range-list
20803           (cons
20804            (length sorted-lengths)
20805            defuns-per-range-list))
20807     ;; @r{Return a list of the number of definitions within each range,}
20808     ;; @r{  smallest to largest.}
20809     (nreverse defuns-per-range-list)))
20810 @end group
20811 @end smallexample
20813 @smallexample
20814 @group
20815 (defun column-of-graph (max-graph-height actual-height)
20816   "Return list of MAX-GRAPH-HEIGHT strings;
20817 ACTUAL-HEIGHT are graph-symbols.
20818 The graph-symbols are contiguous entries at the end
20819 of the list.
20820 The list will be inserted as one column of a graph.
20821 The strings are either graph-blank or graph-symbol."
20822 @end group
20824 @group
20825   (let ((insert-list nil)
20826         (number-of-top-blanks
20827          (- max-graph-height actual-height)))
20829     ;; @r{Fill in @code{graph-symbols}.}
20830     (while (> actual-height 0)
20831       (setq insert-list (cons graph-symbol insert-list))
20832       (setq actual-height (1- actual-height)))
20833 @end group
20835 @group
20836     ;; @r{Fill in @code{graph-blanks}.}
20837     (while (> number-of-top-blanks 0)
20838       (setq insert-list (cons graph-blank insert-list))
20839       (setq number-of-top-blanks
20840             (1- number-of-top-blanks)))
20842     ;; @r{Return whole list.}
20843     insert-list))
20844 @end group
20845 @end smallexample
20847 @smallexample
20848 @group
20849 (defun Y-axis-element (number full-Y-label-width)
20850   "Construct a NUMBERed label element.
20851 A numbered element looks like this `  5 - ',
20852 and is padded as needed so all line up with
20853 the element for the largest number."
20854 @end group
20855 @group
20856   (let* ((leading-spaces
20857          (- full-Y-label-width
20858             (length
20859              (concat (number-to-string number)
20860                      Y-axis-tic)))))
20861 @end group
20862 @group
20863     (concat
20864      (make-string leading-spaces ? )
20865      (number-to-string number)
20866      Y-axis-tic)))
20867 @end group
20868 @end smallexample
20870 @smallexample
20871 @group
20872 (defun print-Y-axis
20873   (height full-Y-label-width &optional vertical-step)
20874   "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
20875 Height must be the  maximum height of the graph.
20876 Full width is the width of the highest label element.
20877 Optionally, print according to VERTICAL-STEP."
20878 @end group
20879 @group
20880 ;; Value of height and full-Y-label-width
20881 ;; are passed by `print-graph'.
20882   (let ((start (point)))
20883     (insert-rectangle
20884      (Y-axis-column height full-Y-label-width vertical-step))
20885 @end group
20886 @group
20887     ;; @r{Place point ready for inserting graph.}
20888     (goto-char start)
20889     ;; @r{Move point forward by value of} full-Y-label-width
20890     (forward-char full-Y-label-width)))
20891 @end group
20892 @end smallexample
20894 @smallexample
20895 @group
20896 (defun print-X-axis-tic-line
20897   (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
20898   "Print tics for X axis."
20899     (insert X-axis-leading-spaces)
20900     (insert X-axis-tic-symbol)  ; @r{Under first column.}
20901 @end group
20902 @group
20903     ;; @r{Insert second tic in the right spot.}
20904     (insert (concat
20905              (make-string
20906               (-  (* symbol-width X-axis-label-spacing)
20907                   ;; @r{Insert white space up to second tic symbol.}
20908                   (* 2 (length X-axis-tic-symbol)))
20909               ? )
20910              X-axis-tic-symbol))
20911 @end group
20912 @group
20913     ;; @r{Insert remaining tics.}
20914     (while (> number-of-X-tics 1)
20915       (insert X-axis-tic-element)
20916       (setq number-of-X-tics (1- number-of-X-tics))))
20917 @end group
20918 @end smallexample
20920 @smallexample
20921 @group
20922 (defun X-axis-element (number)
20923   "Construct a numbered X axis element."
20924   (let ((leading-spaces
20925          (-  (* symbol-width X-axis-label-spacing)
20926              (length (number-to-string number)))))
20927     (concat (make-string leading-spaces ? )
20928             (number-to-string number))))
20929 @end group
20930 @end smallexample
20932 @smallexample
20933 @group
20934 (defun graph-body-print (numbers-list height symbol-width)
20935   "Print a bar graph of the NUMBERS-LIST.
20936 The numbers-list consists of the Y-axis values.
20937 HEIGHT is maximum height of graph.
20938 SYMBOL-WIDTH is number of each column."
20939 @end group
20940 @group
20941   (let (from-position)
20942     (while numbers-list
20943       (setq from-position (point))
20944       (insert-rectangle
20945        (column-of-graph height (car numbers-list)))
20946       (goto-char from-position)
20947       (forward-char symbol-width)
20948 @end group
20949 @group
20950       ;; @r{Draw graph column by column.}
20951       (sit-for 0)
20952       (setq numbers-list (cdr numbers-list)))
20953     ;; @r{Place point for X axis labels.}
20954     (forward-line height)
20955     (insert "\n")))
20956 @end group
20957 @end smallexample
20959 @smallexample
20960 @group
20961 (defun Y-axis-column
20962   (height width-of-label &optional vertical-step)
20963   "Construct list of labels for Y axis.
20964 HEIGHT is maximum height of graph.
20965 WIDTH-OF-LABEL is maximum width of label.
20966 @end group
20967 @group
20968 VERTICAL-STEP, an option, is a positive integer
20969 that specifies how much a Y axis label increments
20970 for each line.  For example, a step of 5 means
20971 that each line is five units of the graph."
20972   (let (Y-axis
20973         (number-per-line (or vertical-step 1)))
20974 @end group
20975 @group
20976     (while (> height 1)
20977       (if (zerop (% height Y-axis-label-spacing))
20978           ;; @r{Insert label.}
20979           (setq Y-axis
20980                 (cons
20981                  (Y-axis-element
20982                   (* height number-per-line)
20983                   width-of-label)
20984                  Y-axis))
20985 @end group
20986 @group
20987         ;; @r{Else, insert blanks.}
20988         (setq Y-axis
20989               (cons
20990                (make-string width-of-label ? )
20991                Y-axis)))
20992       (setq height (1- height)))
20993 @end group
20994 @group
20995     ;; @r{Insert base line.}
20996     (setq Y-axis (cons (Y-axis-element
20997                         (or vertical-step 1)
20998                         width-of-label)
20999                        Y-axis))
21000     (nreverse Y-axis)))
21001 @end group
21002 @end smallexample
21004 @smallexample
21005 @group
21006 (defun print-X-axis-numbered-line
21007   (number-of-X-tics X-axis-leading-spaces
21008    &optional horizontal-step)
21009   "Print line of X-axis numbers"
21010   (let ((number X-axis-label-spacing)
21011         (horizontal-step (or horizontal-step 1)))
21012 @end group
21013 @group
21014     (insert X-axis-leading-spaces)
21015     ;; line up number
21016     (delete-char (- (1- (length (number-to-string horizontal-step)))))
21017     (insert (concat
21018              (make-string
21019               ;; @r{Insert white space up to next number.}
21020               (-  (* symbol-width X-axis-label-spacing)
21021                   (1- (length (number-to-string horizontal-step)))
21022                   2)
21023               ? )
21024              (number-to-string (* number horizontal-step))))
21025 @end group
21026 @group
21027     ;; @r{Insert remaining numbers.}
21028     (setq number (+ number X-axis-label-spacing))
21029     (while (> number-of-X-tics 1)
21030       (insert (X-axis-element (* number horizontal-step)))
21031       (setq number (+ number X-axis-label-spacing))
21032       (setq number-of-X-tics (1- number-of-X-tics)))))
21033 @end group
21034 @end smallexample
21036 @smallexample
21037 @group
21038 (defun print-X-axis (numbers-list horizontal-step)
21039   "Print X axis labels to length of NUMBERS-LIST.
21040 Optionally, HORIZONTAL-STEP, a positive integer,
21041 specifies how much an X  axis label increments for
21042 each column."
21043 @end group
21044 @group
21045 ;; Value of symbol-width and full-Y-label-width
21046 ;; are passed by `print-graph'.
21047   (let* ((leading-spaces
21048           (make-string full-Y-label-width ? ))
21049        ;; symbol-width @r{is provided by} graph-body-print
21050        (tic-width (* symbol-width X-axis-label-spacing))
21051        (X-length (length numbers-list))
21052 @end group
21053 @group
21054        (X-tic
21055         (concat
21056          (make-string
21057           ;; @r{Make a string of blanks.}
21058           (-  (* symbol-width X-axis-label-spacing)
21059               (length X-axis-tic-symbol))
21060           ? )
21061 @end group
21062 @group
21063          ;; @r{Concatenate blanks with tic symbol.}
21064          X-axis-tic-symbol))
21065        (tic-number
21066         (if (zerop (% X-length tic-width))
21067             (/ X-length tic-width)
21068           (1+ (/ X-length tic-width)))))
21069 @end group
21071 @group
21072     (print-X-axis-tic-line
21073      tic-number leading-spaces X-tic)
21074     (insert "\n")
21075     (print-X-axis-numbered-line
21076      tic-number leading-spaces horizontal-step)))
21077 @end group
21078 @end smallexample
21080 @smallexample
21081 @group
21082 (defun one-fiftieth (full-range)
21083   "Return list, each number of which is 1/50th previous."
21084  (mapcar '(lambda (arg) (/ arg 50)) full-range))
21085 @end group
21086 @end smallexample
21088 @smallexample
21089 @group
21090 (defun print-graph
21091   (numbers-list &optional vertical-step horizontal-step)
21092   "Print labelled bar graph of the NUMBERS-LIST.
21093 The numbers-list consists of the Y-axis values.
21094 @end group
21096 @group
21097 Optionally, VERTICAL-STEP, a positive integer,
21098 specifies how much a Y axis label increments for
21099 each line.  For example, a step of 5 means that
21100 each row is five units.
21101 @end group
21103 @group
21104 Optionally, HORIZONTAL-STEP, a positive integer,
21105 specifies how much an X  axis label increments for
21106 each column."
21107   (let* ((symbol-width (length graph-blank))
21108          ;; @code{height} @r{is both the largest number}
21109          ;; @r{and the number with the most digits.}
21110          (height (apply 'max numbers-list))
21111 @end group
21112 @group
21113          (height-of-top-line
21114           (if (zerop (% height Y-axis-label-spacing))
21115               height
21116             ;; @r{else}
21117             (* (1+ (/ height Y-axis-label-spacing))
21118                Y-axis-label-spacing)))
21119 @end group
21120 @group
21121          (vertical-step (or vertical-step 1))
21122          (full-Y-label-width
21123           (length
21124            (concat
21125             (number-to-string
21126              (* height-of-top-line vertical-step))
21127             Y-axis-tic))))
21128 @end group
21129 @group
21131     (print-Y-axis
21132      height-of-top-line full-Y-label-width vertical-step)
21133     (graph-body-print
21134         numbers-list height-of-top-line symbol-width)
21135     (print-X-axis numbers-list horizontal-step)))
21136 @end group
21137 @end smallexample
21138 @end ignore
21140 @page
21141 @node Final printed graph,  , Another Bug, Print Whole Graph
21142 @appendixsubsec The Printed Graph
21144 When made and installed, you can call the @code{print-graph} command
21145 like this:
21146 @sp 1
21148 @smallexample
21149 @group
21150 (print-graph fiftieth-list-for-graph 50 10)
21151 @end group
21152 @end smallexample
21153 @sp 1
21155 @noindent
21156 Here is the graph:
21157 @sp 2
21159 @smallexample
21160 @group
21161 1000 -  *
21162         **
21163         **
21164         **
21165         **
21166  750 -  ***
21167         ***
21168         ***
21169         ***
21170         ****
21171  500 - *****
21172        ******
21173        ******
21174        ******
21175        *******
21176  250 - ********
21177        *********                     *
21178        ***********                   *
21179        *************                 *
21180   50 - ***************** *           *
21181        |   |    |    |    |    |    |    |
21182       10  50  100  150  200  250  300  350
21183 @end group
21184 @end smallexample
21186 @sp 2
21188 @noindent
21189 The largest group of functions contain 10 -- 19 words and symbols each.
21191 @node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top
21192 @appendix Free Software and Free Manuals
21194 @strong{by Richard M. Stallman}
21195 @sp 1
21197 The biggest deficiency in free operating systems is not in the
21198 software---it is the lack of good free manuals that we can include in
21199 these systems.  Many of our most important programs do not come with
21200 full manuals.  Documentation is an essential part of any software
21201 package; when an important free software package does not come with a
21202 free manual, that is a major gap.  We have many such gaps today.
21204 Once upon a time, many years ago, I thought I would learn Perl.  I got
21205 a copy of a free manual, but I found it hard to read.  When I asked
21206 Perl users about alternatives, they told me that there were better
21207 introductory manuals---but those were not free.
21209 Why was this?  The authors of the good manuals had written them for
21210 O'Reilly Associates, which published them with restrictive terms---no
21211 copying, no modification, source files not available---which exclude
21212 them from the free software community.
21214 That wasn't the first time this sort of thing has happened, and (to
21215 our community's great loss) it was far from the last.  Proprietary
21216 manual publishers have enticed a great many authors to restrict their
21217 manuals since then.  Many times I have heard a GNU user eagerly tell me
21218 about a manual that he is writing, with which he expects to help the
21219 GNU project---and then had my hopes dashed, as he proceeded to explain
21220 that he had signed a contract with a publisher that would restrict it
21221 so that we cannot use it.
21223 Given that writing good English is a rare skill among programmers, we
21224 can ill afford to lose manuals this way.
21226 @c (texinfo)uref
21227 (The Free Software Foundation
21228 @uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, ,
21229 sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html,
21230 GNU manuals}, too.)
21232 Free documentation, like free software, is a matter of freedom, not
21233 price.  The problem with these manuals was not that O'Reilly Associates
21234 charged a price for printed copies---that in itself is fine.  (The Free
21235 Software Foundation sells printed copies of free GNU manuals, too.)
21236 But GNU manuals are available in source code form, while these manuals
21237 are available only on paper.  GNU manuals come with permission to copy
21238 and modify; the Perl manuals do not.  These restrictions are the
21239 problems.
21241 The criterion for a free manual is pretty much the same as for free
21242 software: it is a matter of giving all users certain
21243 freedoms.  Redistribution (including commercial redistribution) must be
21244 permitted, so that the manual can accompany every copy of the program,
21245 on-line or on paper.  Permission for modification is crucial too.
21247 As a general rule, I don't believe that it is essential for people to
21248 have permission to modify all sorts of articles and books.  The issues
21249 for writings are not necessarily the same as those for software.  For
21250 example, I don't think you or I are obliged to give permission to
21251 modify articles like this one, which describe our actions and our
21252 views.
21254 But there is a particular reason why the freedom to modify is crucial
21255 for documentation for free software.  When people exercise their right
21256 to modify the software, and add or change its features, if they are
21257 conscientious they will change the manual too---so they can provide
21258 accurate and usable documentation with the modified program.  A manual
21259 which forbids programmers to be conscientious and finish the job, or
21260 more precisely requires them to write a new manual from scratch if
21261 they change the program, does not fill our community's needs.
21263 While a blanket prohibition on modification is unacceptable, some
21264 kinds of limits on the method of modification pose no problem.  For
21265 example, requirements to preserve the original author's copyright
21266 notice, the distribution terms, or the list of authors, are ok.  It is
21267 also no problem to require modified versions to include notice that
21268 they were modified, even to have entire sections that may not be
21269 deleted or changed, as long as these sections deal with nontechnical
21270 topics.  (Some GNU manuals have them.)
21272 These kinds of restrictions are not a problem because, as a practical
21273 matter, they don't stop the conscientious programmer from adapting the
21274 manual to fit the modified program.  In other words, they don't block
21275 the free software community from making full use of the manual.
21277 However, it must be possible to modify all the technical content of
21278 the manual, and then distribute the result in all the usual media,
21279 through all the usual channels; otherwise, the restrictions do block
21280 the community, the manual is not free, and so we need another manual.
21282 Unfortunately, it is often hard to find someone to write another
21283 manual when a proprietary manual exists.  The obstacle is that many
21284 users think that a proprietary manual is good enough---so they don't
21285 see the need to write a free manual.  They do not see that the free
21286 operating system has a gap that needs filling.
21288 Why do users think that proprietary manuals are good enough? Some have
21289 not considered the issue.  I hope this article will do something to
21290 change that.
21292 Other users consider proprietary manuals acceptable for the same
21293 reason so many people consider proprietary software acceptable: they
21294 judge in purely practical terms, not using freedom as a
21295 criterion.  These people are entitled to their opinions, but since
21296 those opinions spring from values which do not include freedom, they
21297 are no guide for those of us who do value freedom.
21299 Please spread the word about this issue.  We continue to lose manuals
21300 to proprietary publishing.  If we spread the word that proprietary
21301 manuals are not sufficient, perhaps the next person who wants to help
21302 GNU by writing documentation will realize, before it is too late, that
21303 he must above all make it free.
21305 We can also encourage commercial publishers to sell free, copylefted
21306 manuals instead of proprietary ones.  One way you can help this is to
21307 check the distribution terms of a manual before you buy it, and prefer
21308 copylefted manuals to non-copylefted ones.
21310 @sp 2
21311 @noindent
21312 Note: The Free Software Foundation maintains a page on its Web site
21313 that lists free books available from other publishers:@*
21314 @uref{http://www.gnu.org/doc/other-free-books.html}
21317 @node GNU Free Documentation License, Index, Free Software and Free Manuals, Top
21318 @appendix GNU Free Documentation License
21320 @cindex FDL, GNU Free Documentation License
21321 @center Version 1.2, November 2002
21323 @display
21324 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
21325 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
21327 Everyone is permitted to copy and distribute verbatim copies
21328 of this license document, but changing it is not allowed.
21329 @end display
21331 @enumerate 0
21332 @item
21333 PREAMBLE
21335 The purpose of this License is to make a manual, textbook, or other
21336 functional and useful document @dfn{free} in the sense of freedom: to
21337 assure everyone the effective freedom to copy and redistribute it,
21338 with or without modifying it, either commercially or noncommercially.
21339 Secondarily, this License preserves for the author and publisher a way
21340 to get credit for their work, while not being considered responsible
21341 for modifications made by others.
21343 This License is a kind of ``copyleft'', which means that derivative
21344 works of the document must themselves be free in the same sense.  It
21345 complements the GNU General Public License, which is a copyleft
21346 license designed for free software.
21348 We have designed this License in order to use it for manuals for free
21349 software, because free software needs free documentation: a free
21350 program should come with manuals providing the same freedoms that the
21351 software does.  But this License is not limited to software manuals;
21352 it can be used for any textual work, regardless of subject matter or
21353 whether it is published as a printed book.  We recommend this License
21354 principally for works whose purpose is instruction or reference.
21356 @item
21357 APPLICABILITY AND DEFINITIONS
21359 This License applies to any manual or other work, in any medium, that
21360 contains a notice placed by the copyright holder saying it can be
21361 distributed under the terms of this License.  Such a notice grants a
21362 world-wide, royalty-free license, unlimited in duration, to use that
21363 work under the conditions stated herein.  The ``Document'', below,
21364 refers to any such manual or work.  Any member of the public is a
21365 licensee, and is addressed as ``you''.  You accept the license if you
21366 copy, modify or distribute the work in a way requiring permission
21367 under copyright law.
21369 A ``Modified Version'' of the Document means any work containing the
21370 Document or a portion of it, either copied verbatim, or with
21371 modifications and/or translated into another language.
21373 A ``Secondary Section'' is a named appendix or a front-matter section
21374 of the Document that deals exclusively with the relationship of the
21375 publishers or authors of the Document to the Document's overall
21376 subject (or to related matters) and contains nothing that could fall
21377 directly within that overall subject.  (Thus, if the Document is in
21378 part a textbook of mathematics, a Secondary Section may not explain
21379 any mathematics.)  The relationship could be a matter of historical
21380 connection with the subject or with related matters, or of legal,
21381 commercial, philosophical, ethical or political position regarding
21382 them.
21384 The ``Invariant Sections'' are certain Secondary Sections whose titles
21385 are designated, as being those of Invariant Sections, in the notice
21386 that says that the Document is released under this License.  If a
21387 section does not fit the above definition of Secondary then it is not
21388 allowed to be designated as Invariant.  The Document may contain zero
21389 Invariant Sections.  If the Document does not identify any Invariant
21390 Sections then there are none.
21392 The ``Cover Texts'' are certain short passages of text that are listed,
21393 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
21394 the Document is released under this License.  A Front-Cover Text may
21395 be at most 5 words, and a Back-Cover Text may be at most 25 words.
21397 A ``Transparent'' copy of the Document means a machine-readable copy,
21398 represented in a format whose specification is available to the
21399 general public, that is suitable for revising the document
21400 straightforwardly with generic text editors or (for images composed of
21401 pixels) generic paint programs or (for drawings) some widely available
21402 drawing editor, and that is suitable for input to text formatters or
21403 for automatic translation to a variety of formats suitable for input
21404 to text formatters.  A copy made in an otherwise Transparent file
21405 format whose markup, or absence of markup, has been arranged to thwart
21406 or discourage subsequent modification by readers is not Transparent.
21407 An image format is not Transparent if used for any substantial amount
21408 of text.  A copy that is not ``Transparent'' is called ``Opaque''.
21410 Examples of suitable formats for Transparent copies include plain
21411 @sc{ascii} without markup, Texinfo input format, La@TeX{} input
21412 format, @acronym{SGML} or @acronym{XML} using a publicly available
21413 @acronym{DTD}, and standard-conforming simple @acronym{HTML},
21414 PostScript or @acronym{PDF} designed for human modification.  Examples
21415 of transparent image formats include @acronym{PNG}, @acronym{XCF} and
21416 @acronym{JPG}.  Opaque formats include proprietary formats that can be
21417 read and edited only by proprietary word processors, @acronym{SGML} or
21418 @acronym{XML} for which the @acronym{DTD} and/or processing tools are
21419 not generally available, and the machine-generated @acronym{HTML},
21420 PostScript or @acronym{PDF} produced by some word processors for
21421 output purposes only.
21423 The ``Title Page'' means, for a printed book, the title page itself,
21424 plus such following pages as are needed to hold, legibly, the material
21425 this License requires to appear in the title page.  For works in
21426 formats which do not have any title page as such, ``Title Page'' means
21427 the text near the most prominent appearance of the work's title,
21428 preceding the beginning of the body of the text.
21430 A section ``Entitled XYZ'' means a named subunit of the Document whose
21431 title either is precisely XYZ or contains XYZ in parentheses following
21432 text that translates XYZ in another language.  (Here XYZ stands for a
21433 specific section name mentioned below, such as ``Acknowledgements'',
21434 ``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
21435 of such a section when you modify the Document means that it remains a
21436 section ``Entitled XYZ'' according to this definition.
21438 The Document may include Warranty Disclaimers next to the notice which
21439 states that this License applies to the Document.  These Warranty
21440 Disclaimers are considered to be included by reference in this
21441 License, but only as regards disclaiming warranties: any other
21442 implication that these Warranty Disclaimers may have is void and has
21443 no effect on the meaning of this License.
21445 @item
21446 VERBATIM COPYING
21448 You may copy and distribute the Document in any medium, either
21449 commercially or noncommercially, provided that this License, the
21450 copyright notices, and the license notice saying this License applies
21451 to the Document are reproduced in all copies, and that you add no other
21452 conditions whatsoever to those of this License.  You may not use
21453 technical measures to obstruct or control the reading or further
21454 copying of the copies you make or distribute.  However, you may accept
21455 compensation in exchange for copies.  If you distribute a large enough
21456 number of copies you must also follow the conditions in section 3.
21458 You may also lend copies, under the same conditions stated above, and
21459 you may publicly display copies.
21461 @item
21462 COPYING IN QUANTITY
21464 If you publish printed copies (or copies in media that commonly have
21465 printed covers) of the Document, numbering more than 100, and the
21466 Document's license notice requires Cover Texts, you must enclose the
21467 copies in covers that carry, clearly and legibly, all these Cover
21468 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
21469 the back cover.  Both covers must also clearly and legibly identify
21470 you as the publisher of these copies.  The front cover must present
21471 the full title with all words of the title equally prominent and
21472 visible.  You may add other material on the covers in addition.
21473 Copying with changes limited to the covers, as long as they preserve
21474 the title of the Document and satisfy these conditions, can be treated
21475 as verbatim copying in other respects.
21477 If the required texts for either cover are too voluminous to fit
21478 legibly, you should put the first ones listed (as many as fit
21479 reasonably) on the actual cover, and continue the rest onto adjacent
21480 pages.
21482 If you publish or distribute Opaque copies of the Document numbering
21483 more than 100, you must either include a machine-readable Transparent
21484 copy along with each Opaque copy, or state in or with each Opaque copy
21485 a computer-network location from which the general network-using
21486 public has access to download using public-standard network protocols
21487 a complete Transparent copy of the Document, free of added material.
21488 If you use the latter option, you must take reasonably prudent steps,
21489 when you begin distribution of Opaque copies in quantity, to ensure
21490 that this Transparent copy will remain thus accessible at the stated
21491 location until at least one year after the last time you distribute an
21492 Opaque copy (directly or through your agents or retailers) of that
21493 edition to the public.
21495 It is requested, but not required, that you contact the authors of the
21496 Document well before redistributing any large number of copies, to give
21497 them a chance to provide you with an updated version of the Document.
21499 @item
21500 MODIFICATIONS
21502 You may copy and distribute a Modified Version of the Document under
21503 the conditions of sections 2 and 3 above, provided that you release
21504 the Modified Version under precisely this License, with the Modified
21505 Version filling the role of the Document, thus licensing distribution
21506 and modification of the Modified Version to whoever possesses a copy
21507 of it.  In addition, you must do these things in the Modified Version:
21509 @enumerate A
21510 @item
21511 Use in the Title Page (and on the covers, if any) a title distinct
21512 from that of the Document, and from those of previous versions
21513 (which should, if there were any, be listed in the History section
21514 of the Document).  You may use the same title as a previous version
21515 if the original publisher of that version gives permission.
21517 @item
21518 List on the Title Page, as authors, one or more persons or entities
21519 responsible for authorship of the modifications in the Modified
21520 Version, together with at least five of the principal authors of the
21521 Document (all of its principal authors, if it has fewer than five),
21522 unless they release you from this requirement.
21524 @item
21525 State on the Title page the name of the publisher of the
21526 Modified Version, as the publisher.
21528 @item
21529 Preserve all the copyright notices of the Document.
21531 @item
21532 Add an appropriate copyright notice for your modifications
21533 adjacent to the other copyright notices.
21535 @item
21536 Include, immediately after the copyright notices, a license notice
21537 giving the public permission to use the Modified Version under the
21538 terms of this License, in the form shown in the Addendum below.
21540 @item
21541 Preserve in that license notice the full lists of Invariant Sections
21542 and required Cover Texts given in the Document's license notice.
21544 @item
21545 Include an unaltered copy of this License.
21547 @item
21548 Preserve the section Entitled ``History'', Preserve its Title, and add
21549 to it an item stating at least the title, year, new authors, and
21550 publisher of the Modified Version as given on the Title Page.  If
21551 there is no section Entitled ``History'' in the Document, create one
21552 stating the title, year, authors, and publisher of the Document as
21553 given on its Title Page, then add an item describing the Modified
21554 Version as stated in the previous sentence.
21556 @item
21557 Preserve the network location, if any, given in the Document for
21558 public access to a Transparent copy of the Document, and likewise
21559 the network locations given in the Document for previous versions
21560 it was based on.  These may be placed in the ``History'' section.
21561 You may omit a network location for a work that was published at
21562 least four years before the Document itself, or if the original
21563 publisher of the version it refers to gives permission.
21565 @item
21566 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
21567 the Title of the section, and preserve in the section all the
21568 substance and tone of each of the contributor acknowledgements and/or
21569 dedications given therein.
21571 @item
21572 Preserve all the Invariant Sections of the Document,
21573 unaltered in their text and in their titles.  Section numbers
21574 or the equivalent are not considered part of the section titles.
21576 @item
21577 Delete any section Entitled ``Endorsements''.  Such a section
21578 may not be included in the Modified Version.
21580 @item
21581 Do not retitle any existing section to be Entitled ``Endorsements'' or
21582 to conflict in title with any Invariant Section.
21584 @item
21585 Preserve any Warranty Disclaimers.
21586 @end enumerate
21588 If the Modified Version includes new front-matter sections or
21589 appendices that qualify as Secondary Sections and contain no material
21590 copied from the Document, you may at your option designate some or all
21591 of these sections as invariant.  To do this, add their titles to the
21592 list of Invariant Sections in the Modified Version's license notice.
21593 These titles must be distinct from any other section titles.
21595 You may add a section Entitled ``Endorsements'', provided it contains
21596 nothing but endorsements of your Modified Version by various
21597 parties---for example, statements of peer review or that the text has
21598 been approved by an organization as the authoritative definition of a
21599 standard.
21601 You may add a passage of up to five words as a Front-Cover Text, and a
21602 passage of up to 25 words as a Back-Cover Text, to the end of the list
21603 of Cover Texts in the Modified Version.  Only one passage of
21604 Front-Cover Text and one of Back-Cover Text may be added by (or
21605 through arrangements made by) any one entity.  If the Document already
21606 includes a cover text for the same cover, previously added by you or
21607 by arrangement made by the same entity you are acting on behalf of,
21608 you may not add another; but you may replace the old one, on explicit
21609 permission from the previous publisher that added the old one.
21611 The author(s) and publisher(s) of the Document do not by this License
21612 give permission to use their names for publicity for or to assert or
21613 imply endorsement of any Modified Version.
21615 @item
21616 COMBINING DOCUMENTS
21618 You may combine the Document with other documents released under this
21619 License, under the terms defined in section 4 above for modified
21620 versions, provided that you include in the combination all of the
21621 Invariant Sections of all of the original documents, unmodified, and
21622 list them all as Invariant Sections of your combined work in its
21623 license notice, and that you preserve all their Warranty Disclaimers.
21625 The combined work need only contain one copy of this License, and
21626 multiple identical Invariant Sections may be replaced with a single
21627 copy.  If there are multiple Invariant Sections with the same name but
21628 different contents, make the title of each such section unique by
21629 adding at the end of it, in parentheses, the name of the original
21630 author or publisher of that section if known, or else a unique number.
21631 Make the same adjustment to the section titles in the list of
21632 Invariant Sections in the license notice of the combined work.
21634 In the combination, you must combine any sections Entitled ``History''
21635 in the various original documents, forming one section Entitled
21636 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
21637 and any sections Entitled ``Dedications''.  You must delete all
21638 sections Entitled ``Endorsements.''
21640 @item
21641 COLLECTIONS OF DOCUMENTS
21643 You may make a collection consisting of the Document and other documents
21644 released under this License, and replace the individual copies of this
21645 License in the various documents with a single copy that is included in
21646 the collection, provided that you follow the rules of this License for
21647 verbatim copying of each of the documents in all other respects.
21649 You may extract a single document from such a collection, and distribute
21650 it individually under this License, provided you insert a copy of this
21651 License into the extracted document, and follow this License in all
21652 other respects regarding verbatim copying of that document.
21654 @item
21655 AGGREGATION WITH INDEPENDENT WORKS
21657 A compilation of the Document or its derivatives with other separate
21658 and independent documents or works, in or on a volume of a storage or
21659 distribution medium, is called an ``aggregate'' if the copyright
21660 resulting from the compilation is not used to limit the legal rights
21661 of the compilation's users beyond what the individual works permit.
21662 When the Document is included in an aggregate, this License does not
21663 apply to the other works in the aggregate which are not themselves
21664 derivative works of the Document.
21666 If the Cover Text requirement of section 3 is applicable to these
21667 copies of the Document, then if the Document is less than one half of
21668 the entire aggregate, the Document's Cover Texts may be placed on
21669 covers that bracket the Document within the aggregate, or the
21670 electronic equivalent of covers if the Document is in electronic form.
21671 Otherwise they must appear on printed covers that bracket the whole
21672 aggregate.
21674 @item
21675 TRANSLATION
21677 Translation is considered a kind of modification, so you may
21678 distribute translations of the Document under the terms of section 4.
21679 Replacing Invariant Sections with translations requires special
21680 permission from their copyright holders, but you may include
21681 translations of some or all Invariant Sections in addition to the
21682 original versions of these Invariant Sections.  You may include a
21683 translation of this License, and all the license notices in the
21684 Document, and any Warranty Disclaimers, provided that you also include
21685 the original English version of this License and the original versions
21686 of those notices and disclaimers.  In case of a disagreement between
21687 the translation and the original version of this License or a notice
21688 or disclaimer, the original version will prevail.
21690 If a section in the Document is Entitled ``Acknowledgements'',
21691 ``Dedications'', or ``History'', the requirement (section 4) to Preserve
21692 its Title (section 1) will typically require changing the actual
21693 title.
21695 @item
21696 TERMINATION
21698 You may not copy, modify, sublicense, or distribute the Document except
21699 as expressly provided for under this License.  Any other attempt to
21700 copy, modify, sublicense or distribute the Document is void, and will
21701 automatically terminate your rights under this License.  However,
21702 parties who have received copies, or rights, from you under this
21703 License will not have their licenses terminated so long as such
21704 parties remain in full compliance.
21706 @item
21707 FUTURE REVISIONS OF THIS LICENSE
21709 The Free Software Foundation may publish new, revised versions
21710 of the GNU Free Documentation License from time to time.  Such new
21711 versions will be similar in spirit to the present version, but may
21712 differ in detail to address new problems or concerns.  See
21713 @uref{http://www.gnu.org/copyleft/}.
21715 Each version of the License is given a distinguishing version number.
21716 If the Document specifies that a particular numbered version of this
21717 License ``or any later version'' applies to it, you have the option of
21718 following the terms and conditions either of that specified version or
21719 of any later version that has been published (not as a draft) by the
21720 Free Software Foundation.  If the Document does not specify a version
21721 number of this License, you may choose any version ever published (not
21722 as a draft) by the Free Software Foundation.
21723 @end enumerate
21725 @page
21726 @appendixsubsec ADDENDUM: How to use this License for your documents
21728 To use this License in a document you have written, include a copy of
21729 the License in the document and put the following copyright and
21730 license notices just after the title page:
21732 @smallexample
21733 @group
21734 Copyright (C)  @var{year}  @var{your name}.
21735 Permission is granted to copy, distribute and/or modify this document
21736 under the terms of the GNU Free Documentation License, Version 1.2
21737 or any later version published by the Free Software Foundation;
21738 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
21739 A copy of the license is included in the section entitled ``GNU
21740 Free Documentation License''.
21741 @end group
21742 @end smallexample
21744 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
21745 replace the ``with...Texts.'' line with this:
21747 @smallexample
21748 @group
21749 with the Invariant Sections being @var{list their titles}, with
21750 the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
21751 being @var{list}.
21752 @end group
21753 @end smallexample
21755 If you have Invariant Sections without Cover Texts, or some other
21756 combination of the three, merge those two alternatives to suit the
21757 situation.
21759 If your document contains nontrivial examples of program code, we
21760 recommend releasing these examples in parallel under your choice of
21761 free software license, such as the GNU General Public License,
21762 to permit their use in free software.
21764 @node Index, About the Author, GNU Free Documentation License, Top
21765 @comment  node-name,  next,  previous,  up
21766 @unnumbered Index
21768 @ignore
21769 MENU ENTRY: NODE NAME.
21770 @end ignore
21772 @printindex cp
21774 @iftex
21775 @c Place biographical information on right-hand (verso) page
21777 @tex
21778 \ifodd\pageno
21779     \par\vfill\supereject
21780     \global\evenheadline={\hfil} \global\evenfootline={\hfil}
21781     \global\oddheadline={\hfil} \global\oddfootline={\hfil}
21782     \page\hbox{}\page
21783 \else
21784     \par\vfill\supereject
21785     \par\vfill\supereject
21786     \global\evenheadline={\hfil} \global\evenfootline={\hfil}
21787     \global\oddheadline={\hfil} \global\oddfootline={\hfil}
21788     \page\hbox{}\page
21789     \page\hbox{}\page
21791 @end tex
21793 @page
21794 @w{ }
21796 @c ================ Biographical information ================
21798 @w{ }
21799 @sp 8
21800 @center About the Author
21801 @sp 1
21802 @end iftex
21804 @ifnottex
21805 @node About the Author,  , Index, Top
21806 @unnumbered About the Author
21807 @end ifnottex
21809 @quotation
21810 Robert J. Chassell has worked with GNU Emacs since 1985.  He writes
21811 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
21812 world on software freedom.  Chassell was a founding Director and
21813 Treasurer of the Free Software Foundation, Inc.  He is co-author of
21814 the @cite{Texinfo} manual, and has edited more than a dozen other
21815 books.  He graduated from Cambridge University, in England.  He has an
21816 abiding interest in social and economic history and flies his own
21817 airplane.
21818 @end quotation
21820 @page
21821 @w{ }
21823 @c Prevent page number on blank verso, so eject it first.
21824 @tex
21825 \par\vfill\supereject
21826 @end tex
21828 @iftex
21829 @headings off
21830 @evenheading @thispage @| @| @thistitle
21831 @oddheading            @| @| @thispage
21832 @end iftex
21834 @bye
21836 @ignore
21837    arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
21838 @end ignore