*** empty log message ***
[emacs.git] / lispintro / emacs-lisp-intro.texi
blob0318ac5d3619e4c5c4bb682122769bb393b7e894
1 \input texinfo                                      @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename ../info/eintr
4 @c setfilename emacs-lisp-intro.info
5 @c sethtmlfilename emacs-lisp-intro.html
6 @settitle Programming in Emacs Lisp
7 @syncodeindex vr cp
8 @syncodeindex fn cp
9 @setchapternewpage odd
10 @finalout
12 @c ---------
13 @c <<<< For hard copy printing, this file is now
14 @c      set for smallbook, which works for all sizes
15 @c      of paper, and with Postscript figures >>>>
16 @smallbook
17 @clear  largebook
18 @set print-postscript-figures
19 @c set largebook
20 @c clear print-postscript-figures
21 @c ---------
23 @comment %**end of header
25 @set edition-number 3.07
26 @set update-date 9 November 2006
28 @ignore
29  ## Summary of shell commands to create various output formats:
31     pushd /usr/local/src/emacs/lispintro/
32     ## pushd /u/intro/
34     ## Info output
35     makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi
37       ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr"))
39     ## DVI output
40     texi2dvi emacs-lisp-intro.texi
42       ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
44     ## HTML output
45     makeinfo --html --no-split --verbose emacs-lisp-intro.texi
47       ## galeon emacs-lisp-intro.html
49     ## Plain text output
50     makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
51     --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
53     popd
55 # as user `root'
56 # insert thumbdrive
57   mtusb       #   mount -v -t ext3 /dev/sda /mnt
58   cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
59   umtusb      #   umount -v /mnt
60 # remove thumbdrive
62     ## Other shell commands
64     pushd /usr/local/src/emacs/lispintro/
65     ## pushd /u/intro/
67     ## PDF
68     texi2dvi --pdf emacs-lisp-intro.texi
69        # xpdf emacs-lisp-intro.pdf &
71     ## DocBook                    -- note file extension
72     makeinfo --docbook --no-split --paragraph-indent=0 \
73     --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi
75     ## XML with a Texinfo DTD     -- note file extension
76     makeinfo --xml --no-split --paragraph-indent=0 \
77     --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi
79     ## PostScript (needs DVI)
80         #     gv emacs-lisp-intro.ps &
81         # Create DVI if we lack it
82         # texi2dvi emacs-lisp-intro.texi
83     dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps
85     ## RTF (needs HTML)
86         # Use OpenOffice to view RTF
87         # Create HTML if we lack it
88         # makeinfo --no-split --html emacs-lisp-intro.texi
89     /usr/local/src/html2rtf.pl emacs-lisp-intro.html
91     ## LaTeX (needs RTF)
92     /usr/bin/rtf2latex emacs-lisp-intro.rtf
94     popd
96 @end ignore
98 @c ================ Included Figures ================
100 @c Set  print-postscript-figures  if you print PostScript figures.
101 @c If you clear this, the ten figures will be printed as ASCII diagrams.
102 @c (This is not relevant to Info, since Info only handles ASCII.)
103 @c Your site may require editing changes to print PostScript; in this
104 @c case, search for `print-postscript-figures' and make appropriate changes.
106 @c ================ How to Create an Info file ================
108 @c If you have `makeinfo' installed, run the following command
110 @c     makeinfo emacs-lisp-intro.texi
112 @c or, if you want a single, large Info file, and no paragraph indents:
113 @c     makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
115 @c After creating the Info file, edit your Info `dir' file, if the
116 @c `dircategory' section below does not enable your system to
117 @c install the manual automatically.
118 @c (The `dir' file is often in the `/usr/local/share/info/' directory.)
120 @c ================ How to Create an HTML file ================
122 @c To convert to HTML format
123 @c     makeinfo --html --no-split --verbose emacs-lisp-intro.texi
125 @c ================ How to Print a Book in Various Sizes ================
127 @c This book can be printed in any of three different sizes.
128 @c In the above header, set @-commands appropriately.
130 @c     7 by 9.25 inches:
131 @c              @smallbook
132 @c              @clear largebook
134 @c     8.5 by 11 inches:
135 @c              @c smallbook
136 @c              @set largebook
138 @c     European A4 size paper:
139 @c              @c smallbook
140 @c              @afourpaper
141 @c              @set largebook
143 @c ================ How to Typeset and Print ================
145 @c If you do not include PostScript figures, run either of the
146 @c following command sequences, or similar commands suited to your
147 @c system:
149 @c     texi2dvi emacs-lisp-intro.texi
150 @c     lpr -d emacs-lisp-intro.dvi
152 @c or else:
154 @c     tex emacs-lisp-intro.texi
155 @c     texindex emacs-lisp-intro.??
156 @c     tex emacs-lisp-intro.texi
157 @c     lpr -d emacs-lisp-intro.dvi
159 @c If you include the PostScript figures, and you have old software,
160 @c you may need to convert the .dvi file to a .ps file before
161 @c printing.  Run either of the following command sequences, or one
162 @c similar:
164 @c     dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
166 @c or else:
168 @c     postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
171 @c (Note: if you edit the book so as to change the length of the
172 @c table of contents, you may have to change the value of `pageno' below.)
174 @c ================ End of Formatting Sections ================
176 @c For next or subsequent edition:
177 @c   create function using with-output-to-temp-buffer
178 @c   create a major mode, with keymaps
179 @c   run an asynchronous process, like grep or diff
181 @c For 8.5 by 11 inch format: do not use such a small amount of
182 @c whitespace between paragraphs as smallbook format
183 @ifset largebook
184 @tex
185 \global\parskip 6pt plus 1pt
186 @end tex
187 @end ifset
189 @c For all sized formats:  print within-book cross
190 @c reference with ``...''  rather than [...]
192 @c This works with the texinfo.tex file, version 2003-05-04.08,
193 @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
195 @tex
196 \if \xrefprintnodename
197  \global\def\xrefprintnodename#1{\unskip, ``#1''}
198  \else
199  \global\def\xrefprintnodename#1{ ``#1''}
201 % \global\def\xrefprintnodename#1{, ``#1''}
202 @end tex
204 @c ----------------------------------------------------
206 @dircategory Emacs
207 @direntry
208 * Emacs Lisp Intro: (eintr).
209                           A simple introduction to Emacs Lisp programming.
210 @end direntry
212 @copying
213 This is an @cite{Introduction to Programming in Emacs Lisp}, for
214 people who are not programmers.
215 @sp 1
216 Edition @value{edition-number}, @value{update-date}
217 @sp 1
218 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
219    2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
220 @sp 1
222 @iftex
223 Published by the:@*
225 GNU Press,                      @hfill  @uref{http://www.gnupress.org}@*
226 a division of the               @hfill General: @email{press@@gnu.org}@*
227 Free Software Foundation, Inc.  @hfill Orders:@w{ }  @email{sales@@gnu.org}@*
228 51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@*
229 Boston, MA 02110-1301 USA       @hfill Fax: +1 (617) 542-2652@*
230 @end iftex
232 @ifnottex
233 Published by the:
235 @example
236 GNU Press,                          Website: http://www.gnupress.org
237 a division of the                   General: press@@gnu.org
238 Free Software Foundation, Inc.      Orders:  sales@@gnu.org
239 51 Franklin Street, Fifth Floor     Tel: +1 (617) 542-5942
240 Boston, MA 02110-1301 USA           Fax: +1 (617) 542-2652
241 @end example
242 @end ifnottex
244 @sp 1
245 @c Printed copies are available for $30 each.@*
246 ISBN 1-882114-43-4
248 Permission is granted to copy, distribute and/or modify this document
249 under the terms of the GNU Free Documentation License, Version 1.2 or
250 any later version published by the Free Software Foundation; there
251 being no Invariant Section, with the Front-Cover Texts being ``A GNU
252 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of
253 the license is included in the section entitled ``GNU Free
254 Documentation License''.
256 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
257 modify this GNU Manual, like GNU software.  Copies published by the
258 Free Software Foundation raise funds for GNU development.''
259 @end copying
261 @c half title; two lines here, so do not use `shorttitlepage'
262 @tex
263 {\begingroup%
264     \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
265         \endgroup}%
266 {\begingroup\hbox{}\vskip 0.25in \chaprm%
267         \centerline{Programming in Emacs Lisp}%
268         \endgroup\page\hbox{}\page}
269 @end tex
271 @titlepage
272 @sp 6
273 @center @titlefont{An Introduction to}
274 @sp 2
275 @center @titlefont{Programming in Emacs Lisp}
276 @sp 2
277 @center Revised Third Edition
278 @sp 4
279 @center by Robert J. Chassell
281 @page
282 @vskip 0pt plus 1filll
283 @insertcopying
284 @end titlepage
286 @iftex
287 @headings off
288 @evenheading @thispage @| @| @thischapter
289 @oddheading @thissection @| @| @thispage
290 @end iftex
292 @ifnothtml
293 @c     Keep T.O.C. short by tightening up for largebook
294 @ifset largebook
295 @tex
296 \global\parskip 2pt plus 1pt
297 \global\advance\baselineskip by -1pt
298 @end tex
299 @end ifset
300 @end ifnothtml
302 @shortcontents
303 @contents
305 @ifnottex
306 @node Top, Preface, (dir), (dir)
307 @top An Introduction to Programming in Emacs Lisp
309 @insertcopying
311 This master menu first lists each chapter and index; then it lists
312 every node in every chapter.
313 @end ifnottex
315 @c >>>> Set pageno appropriately <<<<
317 @c The first page of the Preface is a roman numeral; it is the first
318 @c right handed page after the Table of Contents; hence the following
319 @c setting must be for an odd negative number.
321 @iftex
322 @global@pageno = -11
323 @end iftex
325 @menu
326 * Preface::                     What to look for.
327 * List Processing::             What is Lisp?
328 * Practicing Evaluation::       Running several programs.
329 * Writing Defuns::              How to write function definitions.
330 * Buffer Walk Through::         Exploring a few buffer-related functions.
331 * More Complex::                A few, even more complex functions.
332 * Narrowing & Widening::        Restricting your and Emacs attention to
333                                     a region.
334 * car cdr & cons::              Fundamental functions in Lisp.
335 * Cutting & Storing Text::      Removing text and saving it.
336 * List Implementation::         How lists are implemented in the computer.
337 * Yanking::                     Pasting stored text.
338 * Loops & Recursion::           How to repeat a process.
339 * Regexp Search::               Regular expression searches.
340 * Counting Words::              A review of repetition and regexps.
341 * Words in a defun::            Counting words in a @code{defun}.
342 * Readying a Graph::            A prototype graph printing function.
343 * Emacs Initialization::        How to write a @file{.emacs} file.
344 * Debugging::                   How to run the Emacs Lisp debuggers.
345 * Conclusion::                  Now you have the basics.
346 * the-the::                     An appendix: how to find reduplicated words.
347 * Kill Ring::                   An appendix: how the kill ring works.
348 * Full Graph::                  How to create a graph with labelled axes.
349 * Free Software and Free Manuals::
350 * GNU Free Documentation License::
351 * Index::
352 * About the Author::
354 @detailmenu
355  --- The Detailed Node Listing ---
357 Preface
359 * Why::                         Why learn Emacs Lisp?
360 * On Reading this Text::        Read, gain familiarity, pick up habits....
361 * Who You Are::                 For whom this is written.
362 * Lisp History::
363 * Note for Novices::            You can read this as a novice.
364 * Thank You::
366 List Processing
368 * Lisp Lists::                  What are lists?
369 * Run a Program::               Any list in Lisp is a program ready to run.
370 * Making Errors::               Generating an error message.
371 * Names & Definitions::         Names of symbols and function definitions.
372 * Lisp Interpreter::            What the Lisp interpreter does.
373 * Evaluation::                  Running a program.
374 * Variables::                   Returning a value from a variable.
375 * Arguments::                   Passing information to a function.
376 * set & setq::                  Setting the value of a variable.
377 * Summary::                     The major points.
378 * Error Message Exercises::
380 Lisp Lists
382 * Numbers Lists::               List have numbers, other lists, in them.
383 * Lisp Atoms::                  Elemental entities.
384 * Whitespace in Lists::         Formatting lists to be readable.
385 * Typing Lists::                How GNU Emacs helps you type lists.
387 The Lisp Interpreter
389 * Complications::               Variables, Special forms, Lists within.
390 * Byte Compiling::              Specially processing code for speed.
392 Evaluation
394 * How the Interpreter Acts::    Returns and Side Effects...
395 * Evaluating Inner Lists::      Lists within lists...
397 Variables
399 * fill-column Example::
400 * Void Function::               The error message for a symbol
401                                   without a function.
402 * Void Variable::               The error message for a symbol without a value.
404 Arguments
406 * Data types::                  Types of data passed to a function.
407 * Args as Variable or List::    An argument can be the value
408                                   of a variable or list.
409 * Variable Number of Arguments::  Some functions may take a
410                                   variable number of arguments.
411 * Wrong Type of Argument::      Passing an argument of the wrong type
412                                   to a function.
413 * message::                     A useful function for sending messages.
415 Setting the Value of a Variable
417 * Using set::                  Setting values.
418 * Using setq::                 Setting a quoted value.
419 * Counting::                   Using @code{setq} to count.
421 Practicing Evaluation
423 * How to Evaluate::            Typing editing commands or @kbd{C-x C-e}
424                                  causes evaluation.
425 * Buffer Names::               Buffers and files are different.
426 * Getting Buffers::            Getting a buffer itself, not merely its name.
427 * Switching Buffers::          How to change to another buffer.
428 * Buffer Size & Locations::    Where point is located and the size of
429                                the buffer.
430 * Evaluation Exercise::
432 How To Write Function Definitions
434 * Primitive Functions::
435 * defun::                        The @code{defun} special form.
436 * Install::                      Install a function definition.
437 * Interactive::                  Making a function interactive.
438 * Interactive Options::          Different options for @code{interactive}.
439 * Permanent Installation::       Installing code permanently.
440 * let::                          Creating and initializing local variables.
441 * if::                           What if?
442 * else::                         If--then--else expressions.
443 * Truth & Falsehood::            What Lisp considers false and true.
444 * save-excursion::               Keeping track of point, mark, and buffer.
445 * Review::
446 * defun Exercises::
448 Install a Function Definition
450 * Effect of installation::
451 * Change a defun::              How to change a function definition.
453 Make a Function Interactive
455 * Interactive multiply-by-seven::  An overview.
456 * multiply-by-seven in detail::    The interactive version.
458 @code{let}
460 * Prevent confusion::
461 * Parts of let Expression::
462 * Sample let Expression::
463 * Uninitialized let Variables::
465 The @code{if} Special Form
467 * if in more detail::
468 * type-of-animal in detail::    An example of an @code{if} expression.
470 Truth and Falsehood in Emacs Lisp
472 * nil explained::               @code{nil} has two meanings.
474 @code{save-excursion}
476 * Point and mark::              A review of various locations.
477 * Template for save-excursion::
479 A Few Buffer--Related Functions
481 * Finding More::                How to find more information.
482 * simplified-beginning-of-buffer::  Shows @code{goto-char},
483                                 @code{point-min}, and @code{push-mark}.
484 * mark-whole-buffer::           Almost the same as @code{beginning-of-buffer}.
485 * append-to-buffer::            Uses @code{save-excursion} and
486                                 @code{insert-buffer-substring}.
487 * Buffer Related Review::       Review.
488 * Buffer Exercises::
490 The Definition of @code{mark-whole-buffer}
492 * mark-whole-buffer overview::
493 * Body of mark-whole-buffer::   Only three lines of code.
495 The Definition of @code{append-to-buffer}
497 * append-to-buffer overview::
498 * append interactive::          A two part interactive expression.
499 * append-to-buffer body::       Incorporates a @code{let} expression.
500 * append save-excursion::       How the @code{save-excursion} works.
502 A Few More Complex Functions
504 * copy-to-buffer::              With @code{set-buffer}, @code{get-buffer-create}.
505 * insert-buffer::               Read-only, and with @code{or}.
506 * beginning-of-buffer::         Shows @code{goto-char},
507                                 @code{point-min}, and @code{push-mark}.
508 * Second Buffer Related Review::
509 * optional Exercise::
511 The Definition of @code{insert-buffer}
513 * insert-buffer code::
514 * insert-buffer interactive::   When you can read, but not write.
515 * insert-buffer body::          The body has an @code{or} and a @code{let}.
516 * if & or::                     Using an @code{if} instead of an @code{or}.
517 * Insert or::                   How the @code{or} expression works.
518 * Insert let::                  Two @code{save-excursion} expressions.
519 * New insert-buffer::
521 The Interactive Expression in @code{insert-buffer}
523 * Read-only buffer::            When a buffer cannot be modified.
524 * b for interactive::           An existing buffer or else its name.
526 Complete Definition of @code{beginning-of-buffer}
528 * Optional Arguments::
529 * beginning-of-buffer opt arg::  Example with optional argument.
530 * beginning-of-buffer complete::
532 @code{beginning-of-buffer} with an Argument
534 * Disentangle beginning-of-buffer::
535 * Large buffer case::
536 * Small buffer case::
538 Narrowing and Widening
540 * Narrowing advantages::        The advantages of narrowing
541 * save-restriction::            The @code{save-restriction} special form.
542 * what-line::                   The number of the line that point is on.
543 * narrow Exercise::
545 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
547 * Strange Names::               An historical aside: why the strange names?
548 * car & cdr::                   Functions for extracting part of a list.
549 * cons::                        Constructing a list.
550 * nthcdr::                      Calling @code{cdr} repeatedly.
551 * nth::
552 * setcar::                      Changing the first element of a list.
553 * setcdr::                      Changing the rest of a list.
554 * cons Exercise::
556 @code{cons}
558 * Build a list::
559 * length::                      How to find the length of a list.
561 Cutting and Storing Text
563 * Storing Text::                Text is stored in a list.
564 * zap-to-char::                 Cutting out text up to a character.
565 * kill-region::                 Cutting text out of a region.
566 * copy-region-as-kill::         A definition for copying text.
567 * Digression into C::           Minor note on C programming language macros.
568 * defvar::                      How to give a variable an initial value.
569 * cons & search-fwd Review::
570 * search Exercises::
572 @code{zap-to-char}
574 * Complete zap-to-char::        The complete implementation.
575 * zap-to-char interactive::     A three part interactive expression.
576 * zap-to-char body::            A short overview.
577 * search-forward::              How to search for a string.
578 * progn::                       The @code{progn} special form.
579 * Summing up zap-to-char::      Using @code{point} and @code{search-forward}.
581 @code{kill-region}
583 * Complete kill-region::        The function definition.
584 * condition-case::              Dealing with a problem.
585 * Lisp macro::
587 @code{copy-region-as-kill}
589 * Complete copy-region-as-kill::  The complete function definition.
590 * copy-region-as-kill body::      The body of @code{copy-region-as-kill}.
592 The Body of @code{copy-region-as-kill}
594 * last-command & this-command::
595 * kill-append function::
596 * kill-new function::
598 Initializing a Variable with @code{defvar}
600 * See variable current value::
601 * defvar and asterisk::
603 How Lists are Implemented
605 * Lists diagrammed::
606 * Symbols as Chest::            Exploring a powerful metaphor.
607 * List Exercise::
609 Yanking Text Back
611 * Kill Ring Overview::
612 * kill-ring-yank-pointer::      The kill ring is a list.
613 * yank nthcdr Exercises::       The @code{kill-ring-yank-pointer} variable.
615 Loops and Recursion
617 * while::                       Causing a stretch of code to repeat.
618 * dolist dotimes::
619 * Recursion::                   Causing a function to call itself.
620 * Looping exercise::
622 @code{while}
624 * Looping with while::          Repeat so long as test returns true.
625 * Loop Example::                A @code{while} loop that uses a list.
626 * print-elements-of-list::      Uses @code{while}, @code{car}, @code{cdr}.
627 * Incrementing Loop::           A loop with an incrementing counter.
628 * Incrementing Loop Details::
629 * Decrementing Loop::           A loop with a decrementing counter.
631 Details of an Incrementing Loop
633 * Incrementing Example::        Counting pebbles in a triangle.
634 * Inc Example parts::           The parts of the function definition.
635 * Inc Example altogether::      Putting the function definition together.
637 Loop with a Decrementing Counter
639 * Decrementing Example::        More pebbles on the beach.
640 * Dec Example parts::           The parts of the function definition.
641 * Dec Example altogether::      Putting the function definition together.
643 Save your time: @code{dolist} and @code{dotimes}
645 * dolist::
646 * dotimes::
648 Recursion
650 * Building Robots::             Same model, different serial number ...
651 * Recursive Definition Parts::  Walk until you stop ...
652 * Recursion with list::         Using a list as the test whether to recurse.
653 * Recursive triangle function::
654 * Recursion with cond::
655 * Recursive Patterns::          Often used templates.
656 * No Deferment::                Don't store up work ...
657 * No deferment solution::
659 Recursion in Place of a Counter
661 * Recursive Example arg of 1 or 2::
662 * Recursive Example arg of 3 or 4::
664 Recursive Patterns
666 * Every::
667 * Accumulate::
668 * Keep::
670 Regular Expression Searches
672 * sentence-end::                The regular expression for @code{sentence-end}.
673 * re-search-forward::           Very similar to @code{search-forward}.
674 * forward-sentence::            A straightforward example of regexp search.
675 * forward-paragraph::           A somewhat complex example.
676 * etags::                       How to create your own @file{TAGS} table.
677 * Regexp Review::
678 * re-search Exercises::
680 @code{forward-sentence}
682 * Complete forward-sentence::
683 * fwd-sentence while loops::    Two @code{while} loops.
684 * fwd-sentence re-search::      A regular expression search.
686 @code{forward-paragraph}: a Goldmine of Functions
688 * forward-paragraph in brief::  Key parts of the function definition.
689 * fwd-para let::                The @code{let*} expression.
690 * fwd-para while::              The forward motion @code{while} loop.
692 Counting: Repetition and Regexps
694 * Why Count Words::
695 * count-words-region::          Use a regexp, but find a problem.
696 * recursive-count-words::       Start with case of no words in region.
697 * Counting Exercise::
699 The @code{count-words-region} Function
701 * Design count-words-region::   The definition using a @code{while} loop.
702 * Whitespace Bug::              The Whitespace Bug in @code{count-words-region}.
704 Counting Words in a @code{defun}
706 * Divide and Conquer::
707 * Words and Symbols::           What to count?
708 * Syntax::                      What constitutes a word or symbol?
709 * count-words-in-defun::        Very like @code{count-words}.
710 * Several defuns::              Counting several defuns in a file.
711 * Find a File::                 Do you want to look at a file?
712 * lengths-list-file::           A list of the lengths of many definitions.
713 * Several files::               Counting in definitions in different files.
714 * Several files recursively::   Recursively counting in different files.
715 * Prepare the data::            Prepare the data for display in a graph.
717 Count Words in @code{defuns} in Different Files
719 * lengths-list-many-files::     Return a list of the lengths of defuns.
720 * append::                      Attach one list to another.
722 Prepare the Data for Display in a Graph
724 * Data for Display in Detail::
725 * Sorting::                     Sorting lists.
726 * Files List::                  Making a list of files.
727 * Counting function definitions::
729 Readying a Graph
731 * Columns of a graph::
732 * graph-body-print::            How to print the body of a graph.
733 * recursive-graph-body-print::
734 * Printed Axes::
735 * Line Graph Exercise::
737 Your @file{.emacs} File
739 * Default Configuration::
740 * Site-wide Init::              You can write site-wide init files.
741 * defcustom::                   Emacs will write code for you.
742 * Beginning a .emacs File::     How to write a @code{.emacs file}.
743 * Text and Auto-fill::          Automatically wrap lines.
744 * Mail Aliases::                Use abbreviations for email addresses.
745 * Indent Tabs Mode::            Don't use tabs with @TeX{}
746 * Keybindings::                 Create some personal keybindings.
747 * Keymaps::                     More about key binding.
748 * Loading Files::               Load (i.e., evaluate) files automatically.
749 * Autoload::                    Make functions available.
750 * Simple Extension::            Define a function; bind it to a key.
751 * X11 Colors::                  Colors in X.
752 * Miscellaneous::
753 * Mode Line::                   How to customize your mode line.
755 Debugging
757 * debug::                       How to use the built-in debugger.
758 * debug-on-entry::              Start debugging when you call a function.
759 * debug-on-quit::               Start debugging when you quit with @kbd{C-g}.
760 * edebug::                      How to use Edebug, a source level debugger.
761 * Debugging Exercises::
763 Handling the Kill Ring
765 * What the Kill Ring Does::
766 * current-kill::
767 * yank::                        Paste a copy of a clipped element.
768 * yank-pop::                    Insert element pointed to.
769 * ring file::
771 The @code{current-kill} Function
773 * Understanding current-kill::
775 @code{current-kill} in Outline
777 * Body of current-kill::
778 * Digression concerning error::  How to mislead humans, but not computers.
779 * Determining the Element::
781 A Graph with Labelled Axes
783 * Labelled Example::
784 * print-graph Varlist::         @code{let} expression in @code{print-graph}.
785 * print-Y-axis::                Print a label for the vertical axis.
786 * print-X-axis::                Print a horizontal label.
787 * Print Whole Graph::           The function to print a complete graph.
789 The @code{print-Y-axis} Function
791 * print-Y-axis in Detail::
792 * Height of label::             What height for the Y axis?
793 * Compute a Remainder::         How to compute the remainder of a division.
794 * Y Axis Element::              Construct a line for the Y axis.
795 * Y-axis-column::               Generate a list of Y axis labels.
796 * print-Y-axis Penultimate::    A not quite final version.
798 The @code{print-X-axis} Function
800 * Similarities differences::    Much like @code{print-Y-axis}, but not exactly.
801 * X Axis Tic Marks::            Create tic marks for the horizontal axis.
803 Printing the Whole Graph
805 * The final version::           A few changes.
806 * Test print-graph::            Run a short test.
807 * Graphing words in defuns::    Executing the final code.
808 * lambda::                      How to write an anonymous function.
809 * mapcar::                      Apply a function to elements of a list.
810 * Another Bug::                 Yet another bug @dots{} most insidious.
811 * Final printed graph::         The graph itself!
813 @end detailmenu
814 @end menu
816 @node Preface, List Processing, Top, Top
817 @comment  node-name,  next,  previous,  up
818 @unnumbered Preface
820 Most of the GNU Emacs integrated environment is written in the programming
821 language called Emacs Lisp.  The code written in this programming
822 language is the software---the sets of instructions---that tell the
823 computer what to do when you give it commands.  Emacs is designed so
824 that you can write new code in Emacs Lisp and easily install it as an
825 extension to the editor.
827 (GNU Emacs is sometimes called an ``extensible editor'', but it does
828 much more than provide editing capabilities.  It is better to refer to
829 Emacs as an ``extensible computing environment''.  However, that
830 phrase is quite a mouthful.  It is easier to refer to Emacs simply as
831 an editor.  Moreover, everything you do in Emacs---find the Mayan date
832 and phases of the moon, simplify polynomials, debug code, manage
833 files, read letters, write books---all these activities are kinds of
834 editing in the most general sense of the word.)
836 @menu
837 * Why::                         Why learn Emacs Lisp?
838 * On Reading this Text::        Read, gain familiarity, pick up habits....
839 * Who You Are::                 For whom this is written.
840 * Lisp History::
841 * Note for Novices::            You can read this as a novice.
842 * Thank You::
843 @end menu
845 @node Why, On Reading this Text, Preface, Preface
846 @ifnottex
847 @unnumberedsec Why Study Emacs Lisp?
848 @end ifnottex
850 Although Emacs Lisp is usually thought of in association only with Emacs,
851 it is a full computer programming language.  You can use Emacs Lisp as
852 you would any other programming language.
854 Perhaps you want to understand programming; perhaps you want to extend
855 Emacs; or perhaps you want to become a programmer.  This introduction to
856 Emacs Lisp is designed to get you started: to guide you in learning the
857 fundamentals of programming, and more importantly, to show you how you
858 can teach yourself to go further.
860 @node On Reading this Text, Who You Are, Why, Preface
861 @comment  node-name,  next,  previous,  up
862 @unnumberedsec On Reading this Text
864 All through this document, you will see little sample programs you can
865 run inside of Emacs.  If you read this document in Info inside of GNU
866 Emacs, you can run the programs as they appear.  (This is easy to do and
867 is explained when the examples are presented.)  Alternatively, you can
868 read this introduction as a printed book while sitting beside a computer
869 running Emacs.  (This is what I like to do; I like printed books.)  If
870 you don't have a running Emacs beside you, you can still read this book,
871 but in this case, it is best to treat it as a novel or as a travel guide
872 to a country not yet visited: interesting, but not the same as being
873 there.
875 Much of this introduction is dedicated to walk-throughs or guided tours
876 of code used in GNU Emacs.  These tours are designed for two purposes:
877 first, to give you familiarity with real, working code (code you use
878 every day); and, second, to give you familiarity with the way Emacs
879 works.  It is interesting to see how a working environment is
880 implemented.
881 Also, I
882 hope that you will pick up the habit of browsing through source code.
883 You can learn from it and mine it for ideas.  Having GNU Emacs is like
884 having a dragon's cave of treasures.
886 In addition to learning about Emacs as an editor and Emacs Lisp as a
887 programming language, the examples and guided tours will give you an
888 opportunity to get acquainted with Emacs as a Lisp programming
889 environment.  GNU Emacs supports programming and provides tools that
890 you will want to become comfortable using, such as @kbd{M-.} (the key
891 which invokes the @code{find-tag} command).  You will also learn about
892 buffers and other objects that are part of the environment.
893 Learning about these features of Emacs is like learning new routes
894 around your home town.
896 @ignore
897 In addition, I have written several programs as extended examples.
898 Although these are examples, the programs are real.  I use them.
899 Other people use them.  You may use them.  Beyond the fragments of
900 programs used for illustrations, there is very little in here that is
901 `just for teaching purposes'; what you see is used.  This is a great
902 advantage of Emacs Lisp: it is easy to learn to use it for work.
903 @end ignore
905 Finally, I hope to convey some of the skills for using Emacs to
906 learn aspects of programming that you don't know.  You can often use
907 Emacs to help you understand what puzzles you or to find out how to do
908 something new.  This self-reliance is not only a pleasure, but an
909 advantage.
911 @node Who You Are, Lisp History, On Reading this Text, Preface
912 @comment  node-name,  next,  previous,  up
913 @unnumberedsec For Whom This is Written
915 This text is written as an elementary introduction for people who are
916 not programmers.  If you are a programmer, you may not be satisfied with
917 this primer.  The reason is that you may have become expert at reading
918 reference manuals and be put off by the way this text is organized.
920 An expert programmer who reviewed this text said to me:
922 @quotation
923 @i{I prefer to learn from reference manuals.  I ``dive into'' each
924 paragraph, and ``come up for air'' between paragraphs.}
926 @i{When I get to the end of a paragraph, I assume that that subject is
927 done, finished, that I know everything I need (with the
928 possible exception of the case when the next paragraph starts talking
929 about it in more detail).  I expect that a well written reference manual
930 will not have a lot of redundancy, and that it will have excellent
931 pointers to the (one) place where the information I want is.}
932 @end quotation
934 This introduction is not written for this person!
936 Firstly, I try to say everything at least three times: first, to
937 introduce it; second, to show it in context; and third, to show it in a
938 different context, or to review it.
940 Secondly, I hardly ever put all the information about a subject in one
941 place, much less in one paragraph.  To my way of thinking, that imposes
942 too heavy a burden on the reader.  Instead I try to explain only what
943 you need to know at the time.  (Sometimes I include a little extra
944 information so you won't be surprised later when the additional
945 information is formally introduced.)
947 When you read this text, you are not expected to learn everything the
948 first time.  Frequently, you need only make, as it were, a `nodding
949 acquaintance' with some of the items mentioned.  My hope is that I have
950 structured the text and given you enough hints that you will be alert to
951 what is important, and concentrate on it.
953 You will need to ``dive into'' some paragraphs; there is no other way
954 to read them.  But I have tried to keep down the number of such
955 paragraphs.  This book is intended as an approachable hill, rather than
956 as a daunting mountain.
958 This introduction to @cite{Programming in Emacs Lisp} has a companion
959 document,
960 @iftex
961 @cite{The GNU Emacs Lisp Reference Manual}.
962 @end iftex
963 @ifnottex
964 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
965 Emacs Lisp Reference Manual}.
966 @end ifnottex
967 The reference manual has more detail than this introduction.  In the
968 reference manual, all the information about one topic is concentrated
969 in one place.  You should turn to it if you are like the programmer
970 quoted above.  And, of course, after you have read this
971 @cite{Introduction}, you will find the @cite{Reference Manual} useful
972 when you are writing your own programs.
974 @node Lisp History, Note for Novices, Who You Are, Preface
975 @unnumberedsec Lisp History
976 @cindex Lisp history
978 Lisp was first developed in the late 1950s at the Massachusetts
979 Institute of Technology for research in artificial intelligence.  The
980 great power of the Lisp language makes it superior for other purposes as
981 well, such as writing editor commands and integrated environments.
983 @cindex Maclisp
984 @cindex Common Lisp
985 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT
986 in the 1960s.  It is somewhat inspired by Common Lisp, which became a
987 standard in the 1980s.  However, Emacs Lisp is much simpler than Common
988 Lisp.  (The standard Emacs distribution contains an optional extensions
989 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.)
991 @node Note for Novices, Thank You, Lisp History, Preface
992 @comment  node-name,  next,  previous,  up
993 @unnumberedsec A Note for Novices
995 If you don't know GNU Emacs, you can still read this document
996 profitably.  However, I recommend you learn Emacs, if only to learn to
997 move around your computer screen.  You can teach yourself how to use
998 Emacs with the on-line tutorial.  To use it, type @kbd{C-h t}.  (This
999 means you press and release the @key{CTRL} key and the @kbd{h} at the
1000 same time, and then press and release @kbd{t}.)
1002 Also, I often refer to one of Emacs' standard commands by listing the
1003 keys which you press to invoke the command and then giving the name of
1004 the command in parentheses, like this: @kbd{M-C-\}
1005 (@code{indent-region}).  What this means is that the
1006 @code{indent-region} command is customarily invoked by typing
1007 @kbd{M-C-\}.  (You can, if you wish, change the keys that are typed to
1008 invoke the command; this is called @dfn{rebinding}.  @xref{Keymaps, ,
1009 Keymaps}.)  The abbreviation @kbd{M-C-\} means that you type your
1010 @key{META} key, @key{CTRL} key and @key{\} key all at the same time.
1011 (On many modern keyboards the @key{META} key is labelled
1012 @key{ALT}.)
1013 Sometimes a combination like this is called a keychord, since it is
1014 similar to the way you play a chord on a piano.  If your keyboard does
1015 not have a @key{META} key, the @key{ESC} key prefix is used in place
1016 of it.  In this case, @kbd{M-C-\} means that you press and release your
1017 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
1018 the same time.  But usually @kbd{M-C-\} means press the @key{CTRL} key
1019 along with the key that is labelled @key{ALT} and, at the same time,
1020 press the @key{\} key.
1022 In addition to typing a lone keychord, you can prefix what you type
1023 with @kbd{C-u}, which is called the `universal argument'.  The
1024 @kbd{C-u} keychord passes an argument to the subsequent command.
1025 Thus, to indent a region of plain text by 6 spaces, mark the region,
1026 and then type @w{@kbd{C-u 6 M-C-\}}.  (If you do not specify a number,
1027 Emacs either passes the number 4 to the command or otherwise runs the
1028 command differently than it would otherwise.)  @xref{Arguments, ,
1029 Numeric Arguments, emacs, The GNU Emacs Manual}.
1031 If you are reading this in Info using GNU Emacs, you can read through
1032 this whole document just by pressing the space bar, @key{SPC}.
1033 (To learn about Info, type @kbd{C-h i} and then select Info.)
1035 A note on terminology:  when I use the word Lisp alone, I often am
1036 referring to the various dialects of Lisp in general, but when I speak
1037 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
1039 @node Thank You,  , Note for Novices, Preface
1040 @comment  node-name,  next,  previous,  up
1041 @unnumberedsec Thank You
1043 My thanks to all who helped me with this book.  My especial thanks to
1044 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
1045 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@:
1046 Stallman}, and @w{Melissa Weisshaus}.  My thanks also go to both
1047 @w{Philip Johnson} and @w{David Stampe} for their patient
1048 encouragement.  My mistakes are my own.
1050 @flushright
1051 Robert J. Chassell
1052 @end flushright
1054 @c ================ Beginning of main text ================
1056 @c Start main text on right-hand (verso) page
1058 @tex
1059 \par\vfill\supereject
1060 \headings off
1061 \ifodd\pageno
1062     \par\vfill\supereject
1063 \else
1064     \par\vfill\supereject
1065     \page\hbox{}\page
1066     \par\vfill\supereject
1068 @end tex
1070 @iftex
1071 @headings off
1072 @evenheading @thispage @| @| @thischapter
1073 @oddheading @thissection @| @| @thispage
1074 @global@pageno = 1
1075 @end iftex
1077 @node List Processing, Practicing Evaluation, Preface, Top
1078 @comment  node-name,  next,  previous,  up
1079 @chapter List Processing
1081 To the untutored eye, Lisp is a strange programming language.  In Lisp
1082 code there are parentheses everywhere.  Some people even claim that
1083 the name stands for `Lots of Isolated Silly Parentheses'.  But the
1084 claim is unwarranted.  Lisp stands for LISt Processing, and the
1085 programming language handles @emph{lists} (and lists of lists) by
1086 putting them between parentheses.  The parentheses mark the boundaries
1087 of the list.  Sometimes a list is preceded by a single apostrophe or
1088 quotation mark, @samp{'}@footnote{The single apostrophe or quotation
1089 mark is an abbreviation for the function @code{quote}; you need not
1090 think about functions now; functions are defined in @ref{Making
1091 Errors, , Generate an Error Message}.}  Lists are the basis of Lisp.
1093 @menu
1094 * Lisp Lists::                  What are lists?
1095 * Run a Program::               Any list in Lisp is a program ready to run.
1096 * Making Errors::               Generating an error message.
1097 * Names & Definitions::         Names of symbols and function definitions.
1098 * Lisp Interpreter::            What the Lisp interpreter does.
1099 * Evaluation::                  Running a program.
1100 * Variables::                   Returning a value from a variable.
1101 * Arguments::                   Passing information to a function.
1102 * set & setq::                  Setting the value of a variable.
1103 * Summary::                     The major points.
1104 * Error Message Exercises::
1105 @end menu
1107 @node Lisp Lists, Run a Program, List Processing, List Processing
1108 @comment  node-name,  next,  previous,  up
1109 @section Lisp Lists
1110 @cindex Lisp Lists
1112 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}.
1113 This list is preceded by a single apostrophe.  It could just as well be
1114 written as follows, which looks more like the kind of list you are likely
1115 to be familiar with:
1117 @smallexample
1118 @group
1119 '(rose
1120   violet
1121   daisy
1122   buttercup)
1123 @end group
1124 @end smallexample
1126 @noindent
1127 The elements of this list are the names of the four different flowers,
1128 separated from each other by whitespace and surrounded by parentheses,
1129 like flowers in a field with a stone wall around them.
1130 @cindex Flowers in a field
1132 @menu
1133 * Numbers Lists::               List have numbers, other lists, in them.
1134 * Lisp Atoms::                  Elemental entities.
1135 * Whitespace in Lists::         Formatting lists to be readable.
1136 * Typing Lists::                How GNU Emacs helps you type lists.
1137 @end menu
1139 @node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
1140 @ifnottex
1141 @unnumberedsubsec Numbers, Lists inside of Lists
1142 @end ifnottex
1144 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}.
1145 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each
1146 separated by whitespace.
1148 In Lisp, both data and programs are represented the same way; that is,
1149 they are both lists of words, numbers, or other lists, separated by
1150 whitespace and surrounded by parentheses.  (Since a program looks like
1151 data, one program may easily serve as data for another; this is a very
1152 powerful feature of Lisp.)  (Incidentally, these two parenthetical
1153 remarks are @emph{not} Lisp lists, because they contain @samp{;} and
1154 @samp{.} as punctuation marks.)
1156 @need 1200
1157 Here is another list, this time with a list inside of it:
1159 @smallexample
1160 '(this list has (a list inside of it))
1161 @end smallexample
1163 The components of this list are the words @samp{this}, @samp{list},
1164 @samp{has}, and the list @samp{(a list inside of it)}.  The interior
1165 list is made up of the words @samp{a}, @samp{list}, @samp{inside},
1166 @samp{of}, @samp{it}.
1168 @node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists
1169 @comment  node-name,  next,  previous,  up
1170 @subsection Lisp Atoms
1171 @cindex Lisp Atoms
1173 In Lisp, what we have been calling words are called @dfn{atoms}.  This
1174 term comes from the historical meaning of the word atom, which means
1175 `indivisible'.  As far as Lisp is concerned, the words we have been
1176 using in the lists cannot be divided into any smaller parts and still
1177 mean the same thing as part of a program; likewise with numbers and
1178 single character symbols like @samp{+}.  On the other hand, unlike an
1179 ancient atom, a list can be split into parts.  (@xref{car cdr & cons,
1180 , @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
1182 In a list, atoms are separated from each other by whitespace.  They can be
1183 right next to a parenthesis.
1185 @cindex @samp{empty list} defined
1186 Technically speaking, a list in Lisp consists of parentheses surrounding
1187 atoms separated by whitespace or surrounding other lists or surrounding
1188 both atoms and other lists.  A list can have just one atom in it or
1189 have nothing in it at all.  A list with nothing in it looks like this:
1190 @code{()}, and is called the @dfn{empty list}.  Unlike anything else, an
1191 empty list is considered both an atom and a list at the same time.
1193 @cindex Symbolic expressions, introduced
1194 @cindex @samp{expression} defined
1195 @cindex @samp{form} defined
1196 The printed representation of both atoms and lists are called
1197 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
1198 The word @dfn{expression} by itself can refer to either the printed
1199 representation, or to the atom or list as it is held internally in the
1200 computer.  Often, people use the term @dfn{expression}
1201 indiscriminately.  (Also, in many texts, the word @dfn{form} is used
1202 as a synonym for expression.)
1204 Incidentally, the atoms that make up our universe were named such when
1205 they were thought to be indivisible; but it has been found that physical
1206 atoms are not indivisible.  Parts can split off an atom or it can
1207 fission into two parts of roughly equal size.  Physical atoms were named
1208 prematurely, before their truer nature was found.  In Lisp, certain
1209 kinds of atom, such as an array, can be separated into parts; but the
1210 mechanism for doing this is different from the mechanism for splitting a
1211 list.  As far as list operations are concerned, the atoms of a list are
1212 unsplittable.
1214 As in English, the meanings of the component letters of a Lisp atom
1215 are different from the meaning the letters make as a word.  For
1216 example, the word for the South American sloth, the @samp{ai}, is
1217 completely different from the two words, @samp{a}, and @samp{i}.
1219 There are many kinds of atom in nature but only a few in Lisp: for
1220 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such
1221 as @samp{+}, @samp{foo}, or @samp{forward-line}.  The words we have
1222 listed in the examples above are all symbols.  In everyday Lisp
1223 conversation, the word ``atom'' is not often used, because programmers
1224 usually try to be more specific about what kind of atom they are dealing
1225 with.  Lisp programming is mostly about symbols (and sometimes numbers)
1226 within lists.  (Incidentally, the preceding three word parenthetical
1227 remark is a proper list in Lisp, since it consists of atoms, which in
1228 this case are symbols, separated by whitespace and enclosed by
1229 parentheses, without any non-Lisp punctuation.)
1231 @need 1250
1232 In addition, text between double quotation marks---even sentences or
1233 paragraphs---is an atom.  Here is an example:
1234 @cindex Text between double quotation marks
1236 @smallexample
1237 '(this list includes "text between quotation marks.")
1238 @end smallexample
1240 @cindex @samp{string} defined
1241 @noindent
1242 In Lisp, all of the quoted text including the punctuation mark and the
1243 blank spaces is a single atom.  This kind of atom is called a
1244 @dfn{string} (for `string of characters') and is the sort of thing that
1245 is used for messages that a computer can print for a human to read.
1246 Strings are a different kind of atom than numbers or symbols and are
1247 used differently.
1249 @node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists
1250 @comment  node-name,  next,  previous,  up
1251 @subsection Whitespace in Lists
1252 @cindex Whitespace in lists
1254 @need 1200
1255 The amount of whitespace in a list does not matter.  From the point of view
1256 of the Lisp language,
1258 @smallexample
1259 @group
1260 '(this list
1261    looks like this)
1262 @end group
1263 @end smallexample
1265 @need 800
1266 @noindent
1267 is exactly the same as this:
1269 @smallexample
1270 '(this list looks like this)
1271 @end smallexample
1273 Both examples show what to Lisp is the same list, the list made up of
1274 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and
1275 @samp{this} in that order.
1277 Extra whitespace and newlines are designed to make a list more readable
1278 by humans.  When Lisp reads the expression, it gets rid of all the extra
1279 whitespace (but it needs to have at least one space between atoms in
1280 order to tell them apart.)
1282 Odd as it seems, the examples we have seen cover almost all of what Lisp
1283 lists look like!  Every other list in Lisp looks more or less like one
1284 of these examples, except that the list may be longer and more complex.
1285 In brief, a list is between parentheses, a string is between quotation
1286 marks, a symbol looks like a word, and a number looks like a number.
1287 (For certain situations, square brackets, dots and a few other special
1288 characters may be used; however, we will go quite far without them.)
1290 @node Typing Lists,  , Whitespace in Lists, Lisp Lists
1291 @comment  node-name,  next,  previous,  up
1292 @subsection GNU Emacs Helps You Type Lists
1293 @cindex Help typing lists
1294 @cindex Formatting help
1296 When you type a Lisp expression in GNU Emacs using either Lisp
1297 Interaction mode or Emacs Lisp mode, you have available to you several
1298 commands to format the Lisp expression so it is easy to read.  For
1299 example, pressing the @key{TAB} key automatically indents the line the
1300 cursor is on by the right amount.  A command to properly indent the
1301 code in a region is customarily bound to @kbd{M-C-\}.  Indentation is
1302 designed so that you can see which elements of a list belong to which
1303 list---elements of a sub-list are indented more than the elements of
1304 the enclosing list.
1306 In addition, when you type a closing parenthesis, Emacs momentarily
1307 jumps the cursor back to the matching opening parenthesis, so you can
1308 see which one it is.  This is very useful, since every list you type
1309 in Lisp must have its closing parenthesis match its opening
1310 parenthesis.  (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs
1311 Manual}, for more information about Emacs' modes.)
1313 @node Run a Program, Making Errors, Lisp Lists, List Processing
1314 @comment  node-name,  next,  previous,  up
1315 @section Run a Program
1316 @cindex Run a program
1317 @cindex Program, running one
1319 @cindex @samp{evaluate} defined
1320 A list in Lisp---any list---is a program ready to run.  If you run it
1321 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one
1322 of three things: do nothing except return to you the list itself; send
1323 you an error message; or, treat the first symbol in the list as a
1324 command to do something.  (Usually, of course, it is the last of these
1325 three things that you really want!)
1327 @c use code for the single apostrophe, not samp.
1328 The single apostrophe, @code{'}, that I put in front of some of the
1329 example lists in preceding sections is called a @dfn{quote}; when it
1330 precedes a list, it tells Lisp to do nothing with the list, other than
1331 take it as it is written.  But if there is no quote preceding a list,
1332 the first item of the list is special: it is a command for the computer
1333 to obey.  (In Lisp, these commands are called @emph{functions}.)  The list
1334 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp
1335 understands that the @code{+} is an instruction to do something with the
1336 rest of the list: add the numbers that follow.
1338 @need 1250
1339 If you are reading this inside of GNU Emacs in Info, here is how you can
1340 evaluate such a list:  place your cursor immediately after the right
1341 hand parenthesis of the following list and then type @kbd{C-x C-e}:
1343 @smallexample
1344 (+ 2 2)
1345 @end smallexample
1347 @c use code for the number four, not samp.
1348 @noindent
1349 You will see the number @code{4} appear in the echo area.  (In the
1350 jargon, what you have just done is ``evaluate the list.''  The echo area
1351 is the line at the bottom of the screen that displays or ``echoes''
1352 text.)  Now try the same thing with a quoted list:  place the cursor
1353 right after the following list and type @kbd{C-x C-e}:
1355 @smallexample
1356 '(this is a quoted list)
1357 @end smallexample
1359 @noindent
1360 You will see @code{(this is a quoted list)} appear in the echo area.
1362 @cindex Lisp interpreter, explained
1363 @cindex Interpreter, Lisp, explained
1364 In both cases, what you are doing is giving a command to the program
1365 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
1366 interpreter a command to evaluate the expression.  The name of the Lisp
1367 interpreter comes from the word for the task done by a human who comes
1368 up with the meaning of an expression---who ``interprets'' it.
1370 You can also evaluate an atom that is not part of a list---one that is
1371 not surrounded by parentheses; again, the Lisp interpreter translates
1372 from the humanly readable expression to the language of the computer.
1373 But before discussing this (@pxref{Variables}), we will discuss what the
1374 Lisp interpreter does when you make an error.
1376 @node Making Errors, Names & Definitions, Run a Program, List Processing
1377 @comment  node-name,  next,  previous,  up
1378 @section Generate an Error Message
1379 @cindex Generate an error message
1380 @cindex Error message generation
1382 Partly so you won't worry if you do it accidentally, we will now give
1383 a command to the Lisp interpreter that generates an error message.
1384 This is a harmless activity; and indeed, we will often try to generate
1385 error messages intentionally.  Once you understand the jargon, error
1386 messages can be informative.  Instead of being called ``error''
1387 messages, they should be called ``help'' messages.  They are like
1388 signposts to a traveller in a strange country; deciphering them can be
1389 hard, but once understood, they can point the way.
1391 The error message is generated by a built-in GNU Emacs debugger.  We
1392 will `enter the debugger'.  You get out of the debugger by typing @code{q}.
1394 What we will do is evaluate a list that is not quoted and does not
1395 have a meaningful command as its first element.  Here is a list almost
1396 exactly the same as the one we just used, but without the single-quote
1397 in front of it.  Position the cursor right after it and type @kbd{C-x
1398 C-e}:
1400 @smallexample
1401 (this is an unquoted list)
1402 @end smallexample
1404 @noindent
1405 What you see depends on which version of Emacs you are running.  GNU
1406 Emacs version 22 provides more information than version 20 and before.
1407 First, the more recent result of generating an error; then the
1408 earlier, version 20 result.
1410 @need 1250
1411 @noindent
1412 In GNU Emacs version 22, a @file{*Backtrace*} window will open up and
1413 you will see the following in it:
1415 @smallexample
1416 @group
1417 ---------- Buffer: *Backtrace* ----------
1418 Debugger entered--Lisp error: (void-function this)
1419   (this is an unquoted list)
1420   eval((this is an unquoted list))
1421   eval-last-sexp-1(nil)
1422   eval-last-sexp(nil)
1423   call-interactively(eval-last-sexp)
1424 ---------- Buffer: *Backtrace* ----------
1425 @end group
1426 @end smallexample
1428 @need 1200
1429 @noindent
1430 Your cursor will be in this window (you may have to wait a few seconds
1431 before it becomes visible).  To quit the debugger and make the
1432 debugger window go away, type:
1434 @smallexample
1436 @end smallexample
1438 @noindent
1439 Please type @kbd{q} right now, so you become confident that you can
1440 get out of the debugger.  Then, type @kbd{C-x C-e} again to re-enter
1443 @cindex @samp{function} defined
1444 Based on what we already know, we can almost read this error message.
1446 You read the @file{*Backtrace*} buffer from the bottom up; it tells
1447 you what Emacs did.  When you typed @kbd{C-x C-e}, you made an
1448 interactive call to the command @code{eval-last-sexp}.  @code{eval} is
1449 an abbreviation for `evaluate' and @code{sexp} is an abbreviation for
1450 `symbolic expression'.  The command means `evaluate last symbolic
1451 expression', which is the expression just before your cursor.
1453 Each line above tells you what the Lisp interpreter evaluated next.
1454 The most recent action is at the top.  The buffer is called the
1455 @file{*Backtrace*} buffer because it enables you to track Emacs
1456 backwards.
1458 @need 800
1459 At the top of the @file{*Backtrace*} buffer, you see the line:
1461 @smallexample
1462 Debugger entered--Lisp error: (void-function this)
1463 @end smallexample
1465 @noindent
1466 The Lisp interpreter tried to evaluate the first atom of the list, the
1467 word @samp{this}.  It is this action that generated the error message
1468 @samp{void-function this}.
1470 The message contains the words @samp{void-function} and @samp{this}.
1472 @cindex @samp{function} defined
1473 The word @samp{function} was mentioned once before.  It is a very
1474 important word.  For our purposes, we can define it by saying that a
1475 @dfn{function} is a set of instructions to the computer that tell the
1476 computer to do something.
1478 Now we can begin to understand the error message: @samp{void-function
1479 this}.  The function (that is, the word @samp{this}) does not have a
1480 definition of any set of instructions for the computer to carry out.
1482 The slightly odd word, @samp{void-function}, is designed to cover the
1483 way Emacs Lisp is implemented, which is that when a symbol does not
1484 have a function definition attached to it, the place that should
1485 contain the instructions is `void'.
1487 On the other hand, since we were able to add 2 plus 2 successfully, by
1488 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
1489 have a set of instructions for the computer to obey and those
1490 instructions must be to add the numbers that follow the @code{+}.
1492 @need 1250
1493 In GNU Emacs version 20, and in earlier versions, you will see only
1494 one line of error message; it will appear in the echo area and look
1495 like this:
1497 @smallexample
1498 Symbol's function definition is void:@: this
1499 @end smallexample
1501 @noindent
1502 (Also, your terminal may beep at you---some do, some don't; and others
1503 blink.  This is just a device to get your attention.)  The message goes
1504 away as soon as you type another key, even just to move the cursor.
1506 We know the meaning of the word @samp{Symbol}.  It refers to the first
1507 atom of the list, the word @samp{this}.  The word @samp{function}
1508 refers to the instructions that tell the computer what to do.
1509 (Technically, the symbol tells the computer where to find the
1510 instructions, but this is a complication we can ignore for the
1511 moment.)
1513 The error message can be understood: @samp{Symbol's function
1514 definition is void:@: this}.  The symbol (that is, the word
1515 @samp{this}) lacks instructions for the computer to carry out.
1517 @node Names & Definitions, Lisp Interpreter, Making Errors, List Processing
1518 @comment  node-name,  next,  previous,  up
1519 @section Symbol Names and Function Definitions
1520 @cindex Symbol names
1522 We can articulate another characteristic of Lisp based on what we have
1523 discussed so far---an important characteristic: a symbol, like
1524 @code{+}, is not itself the set of instructions for the computer to
1525 carry out.  Instead, the symbol is used, perhaps temporarily, as a way
1526 of locating the definition or set of instructions.  What we see is the
1527 name through which the instructions can be found.  Names of people
1528 work the same way.  I can be referred to as @samp{Bob}; however, I am
1529 not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the
1530 consciousness consistently associated with a particular life-form.
1531 The name is not me, but it can be used to refer to me.
1533 In Lisp, one set of instructions can be attached to several names.
1534 For example, the computer instructions for adding numbers can be
1535 linked to the symbol @code{plus} as well as to the symbol @code{+}
1536 (and are in some dialects of Lisp).  Among humans, I can be referred
1537 to as @samp{Robert} as well as @samp{Bob} and by other words as well.
1539 On the other hand, a symbol can have only one function definition
1540 attached to it at a time.  Otherwise, the computer would be confused as
1541 to which definition to use.  If this were the case among people, only
1542 one person in the world could be named @samp{Bob}.  However, the function
1543 definition to which the name refers can be changed readily.
1544 (@xref{Install, , Install a Function Definition}.)
1546 Since Emacs Lisp is large, it is customary to name symbols in a way
1547 that identifies the part of Emacs to which the function belongs.
1548 Thus, all the names for functions that deal with Texinfo start with
1549 @samp{texinfo-} and those for functions that deal with reading mail
1550 start with @samp{rmail-}.
1552 @node Lisp Interpreter, Evaluation, Names & Definitions, List Processing
1553 @comment  node-name,  next,  previous,  up
1554 @section The Lisp Interpreter
1555 @cindex Lisp interpreter, what it does
1556 @cindex Interpreter, what it does
1558 Based on what we have seen, we can now start to figure out what the
1559 Lisp interpreter does when we command it to evaluate a list.
1560 First, it looks to see whether there is a quote before the list; if
1561 there is, the interpreter just gives us the list.  On the other
1562 hand, if there is no quote, the interpreter looks at the first element
1563 in the list and sees whether it has a function definition.  If it does,
1564 the interpreter carries out the instructions in the function definition.
1565 Otherwise, the interpreter prints an error message.
1567 This is how Lisp works.  Simple.  There are added complications which we
1568 will get to in a minute, but these are the fundamentals.  Of course, to
1569 write Lisp programs, you need to know how to write function definitions
1570 and attach them to names, and how to do this without confusing either
1571 yourself or the computer.
1573 @menu
1574 * Complications::               Variables, Special forms, Lists within.
1575 * Byte Compiling::              Specially processing code for speed.
1576 @end menu
1578 @node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
1579 @ifnottex
1580 @unnumberedsubsec Complications
1581 @end ifnottex
1583 Now, for the first complication.  In addition to lists, the Lisp
1584 interpreter can evaluate a symbol that is not quoted and does not have
1585 parentheses around it.  The Lisp interpreter will attempt to determine
1586 the symbol's value as a @dfn{variable}.  This situation is described
1587 in the section on variables.  (@xref{Variables}.)
1589 @cindex Special form
1590 The second complication occurs because some functions are unusual and do
1591 not work in the usual manner.  Those that don't are called @dfn{special
1592 forms}.  They are used for special jobs, like defining a function, and
1593 there are not many of them.  In the next few chapters, you will be
1594 introduced to several of the more important special forms.
1596 The third and final complication is this: if the function that the
1597 Lisp interpreter is looking at is not a special form, and if it is part
1598 of a list, the Lisp interpreter looks to see whether the list has a list
1599 inside of it.  If there is an inner list, the Lisp interpreter first
1600 figures out what it should do with the inside list, and then it works on
1601 the outside list.  If there is yet another list embedded inside the
1602 inner list, it works on that one first, and so on.  It always works on
1603 the innermost list first.  The interpreter works on the innermost list
1604 first, to evaluate the result of that list.  The result may be
1605 used by the enclosing expression.
1607 Otherwise, the interpreter works left to right, from one expression to
1608 the next.
1610 @node Byte Compiling,  , Complications, Lisp Interpreter
1611 @subsection Byte Compiling
1612 @cindex Byte compiling
1614 One other aspect of interpreting: the Lisp interpreter is able to
1615 interpret two kinds of entity: humanly readable code, on which we will
1616 focus exclusively, and specially processed code, called @dfn{byte
1617 compiled} code, which is not humanly readable.  Byte compiled code
1618 runs faster than humanly readable code.
1620 You can transform humanly readable code into byte compiled code by
1621 running one of the compile commands such as @code{byte-compile-file}.
1622 Byte compiled code is usually stored in a file that ends with a
1623 @file{.elc} extension rather than a @file{.el} extension.  You will
1624 see both kinds of file in the @file{emacs/lisp} directory; the files
1625 to read are those with @file{.el} extensions.
1627 As a practical matter, for most things you might do to customize or
1628 extend Emacs, you do not need to byte compile; and I will not discuss
1629 the topic here.  @xref{Byte Compilation, , Byte Compilation, elisp,
1630 The GNU Emacs Lisp Reference Manual}, for a full description of byte
1631 compilation.
1633 @node Evaluation, Variables, Lisp Interpreter, List Processing
1634 @comment  node-name,  next,  previous,  up
1635 @section Evaluation
1636 @cindex Evaluation
1638 When the Lisp interpreter works on an expression, the term for the
1639 activity is called @dfn{evaluation}.  We say that the interpreter
1640 `evaluates the expression'.  I've used this term several times before.
1641 The word comes from its use in everyday language, `to ascertain the
1642 value or amount of; to appraise', according to @cite{Webster's New
1643 Collegiate Dictionary}.
1645 @menu
1646 * How the Interpreter Acts::    Returns and Side Effects...
1647 * Evaluating Inner Lists::      Lists within lists...
1648 @end menu
1650 @node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation
1651 @ifnottex
1652 @unnumberedsubsec How the Lisp Interpreter Acts
1653 @end ifnottex
1655 @cindex @samp{returned value} explained
1656 After evaluating an expression, the Lisp interpreter will most likely
1657 @dfn{return} the value that the computer produces by carrying out the
1658 instructions it found in the function definition, or perhaps it will
1659 give up on that function and produce an error message.  (The interpreter
1660 may also find itself tossed, so to speak, to a different function or it
1661 may attempt to repeat continually what it is doing for ever and ever in
1662 what is called an `infinite loop'.  These actions are less common; and
1663 we can ignore them.)  Most frequently, the interpreter returns a value.
1665 @cindex @samp{side effect} defined
1666 At the same time the interpreter returns a value, it may do something
1667 else as well, such as move a cursor or copy a file; this other kind of
1668 action is called a @dfn{side effect}.  Actions that we humans think are
1669 important, such as printing results, are often ``side effects'' to the
1670 Lisp interpreter.  The jargon can sound peculiar, but it turns out that
1671 it is fairly easy to learn to use side effects.
1673 In summary, evaluating a symbolic expression most commonly causes the
1674 Lisp interpreter to return a value and perhaps carry out a side effect;
1675 or else produce an error.
1677 @node Evaluating Inner Lists,  , How the Interpreter Acts, Evaluation
1678 @comment  node-name,  next,  previous,  up
1679 @subsection Evaluating Inner Lists
1680 @cindex Inner list evaluation
1681 @cindex Evaluating inner lists
1683 If evaluation applies to a list that is inside another list, the outer
1684 list may use the value returned by the first evaluation as information
1685 when the outer list is evaluated.  This explains why inner expressions
1686 are evaluated first: the values they return are used by the outer
1687 expressions.
1689 @need 1250
1690 We can investigate this process by evaluating another addition example.
1691 Place your cursor after the following expression and type @kbd{C-x C-e}:
1693 @smallexample
1694 (+ 2 (+ 3 3))
1695 @end smallexample
1697 @noindent
1698 The number 8 will appear in the echo area.
1700 What happens is that the Lisp interpreter first evaluates the inner
1701 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it
1702 evaluates the outer expression as if it were written @code{(+ 2 6)}, which
1703 returns the value 8.  Since there are no more enclosing expressions to
1704 evaluate, the interpreter prints that value in the echo area.
1706 Now it is easy to understand the name of the command invoked by the
1707 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}.  The
1708 letters @code{sexp} are an abbreviation for `symbolic expression', and
1709 @code{eval} is an abbreviation for `evaluate'.  The command means
1710 `evaluate last symbolic expression'.
1712 As an experiment, you can try evaluating the expression by putting the
1713 cursor at the beginning of the next line immediately following the
1714 expression, or inside the expression.
1716 @need 800
1717 Here is another copy of the expression:
1719 @smallexample
1720 (+ 2 (+ 3 3))
1721 @end smallexample
1723 @noindent
1724 If you place the cursor at the beginning of the blank line that
1725 immediately follows the expression and type @kbd{C-x C-e}, you will
1726 still get the value 8 printed in the echo area.  Now try putting the
1727 cursor inside the expression.  If you put it right after the next to
1728 last parenthesis (so it appears to sit on top of the last parenthesis),
1729 you will get a 6 printed in the echo area!  This is because the command
1730 evaluates the expression @code{(+ 3 3)}.
1732 Now put the cursor immediately after a number.  Type @kbd{C-x C-e} and
1733 you will get the number itself.  In Lisp, if you evaluate a number, you
1734 get the number itself---this is how numbers differ from symbols.  If you
1735 evaluate a list starting with a symbol like @code{+}, you will get a
1736 value returned that is the result of the computer carrying out the
1737 instructions in the function definition attached to that name.  If a
1738 symbol by itself is evaluated, something different happens, as we will
1739 see in the next section.
1741 @node Variables, Arguments, Evaluation, List Processing
1742 @comment  node-name,  next,  previous,  up
1743 @section Variables
1744 @cindex Variables
1746 In Emacs Lisp, a symbol can have a value attached to it just as it can
1747 have a function definition attached to it.  The two are different.
1748 The function definition is a set of instructions that a computer will
1749 obey.  A value, on the other hand, is something, such as number or a
1750 name, that can vary (which is why such a symbol is called a variable).
1751 The value of a symbol can be any expression in Lisp, such as a symbol,
1752 number, list, or string.  A symbol that has a value is often called a
1753 @dfn{variable}.
1755 A symbol can have both a function definition and a value attached to
1756 it at the same time.  Or it can have just one or the other.
1757 The two are separate.  This is somewhat similar
1758 to the way the name Cambridge can refer to the city in Massachusetts
1759 and have some information attached to the name as well, such as
1760 ``great programming center''.
1762 @ignore
1763 (Incidentally, in Emacs Lisp, a symbol can have two
1764 other things attached to it, too: a property list and a documentation
1765 string; these are discussed later.)
1766 @end ignore
1768 Another way to think about this is to imagine a symbol as being a chest
1769 of drawers.  The function definition is put in one drawer, the value in
1770 another, and so on.  What is put in the drawer holding the value can be
1771 changed without affecting the contents of the drawer holding the
1772 function definition, and vice-verse.
1774 @menu
1775 * fill-column Example::
1776 * Void Function::               The error message for a symbol
1777                                   without a function.
1778 * Void Variable::               The error message for a symbol without a value.
1779 @end menu
1781 @node fill-column Example, Void Function, Variables, Variables
1782 @ifnottex
1783 @unnumberedsubsec @code{fill-column}, an Example Variable
1784 @end ifnottex
1786 @findex fill-column, @r{an example variable}
1787 @cindex Example variable, @code{fill-column}
1788 @cindex Variable, example of, @code{fill-column}
1789 The variable @code{fill-column} illustrates a symbol with a value
1790 attached to it: in every GNU Emacs buffer, this symbol is set to some
1791 value, usually 72 or 70, but sometimes to some other value.  To find the
1792 value of this symbol, evaluate it by itself.  If you are reading this in
1793 Info inside of GNU Emacs, you can do this by putting the cursor after
1794 the symbol and typing @kbd{C-x C-e}:
1796 @smallexample
1797 fill-column
1798 @end smallexample
1800 @noindent
1801 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo
1802 area.  This is the value for which @code{fill-column} is set for me as I
1803 write this.  It may be different for you in your Info buffer.  Notice
1804 that the value returned as a variable is printed in exactly the same way
1805 as the value returned by a function carrying out its instructions.  From
1806 the point of view of the Lisp interpreter, a value returned is a value
1807 returned.  What kind of expression it came from ceases to matter once
1808 the value is known.
1810 A symbol can have any value attached to it or, to use the jargon, we can
1811 @dfn{bind} the variable to a value: to a number, such as 72; to a
1812 string, @code{"such as this"}; to a list, such as @code{(spruce pine
1813 oak)}; we can even bind a variable to a function definition.
1815 A symbol can be bound to a value in several ways.  @xref{set & setq, ,
1816 Setting the Value of a Variable}, for information about one way to do
1817 this.
1819 @node Void Function, Void Variable, fill-column Example, Variables
1820 @comment  node-name,  next,  previous,  up
1821 @subsection Error Message for a Symbol Without a Function
1822 @cindex Symbol without function error
1823 @cindex Error for symbol without function
1825 When we evaluated @code{fill-column} to find its value as a variable,
1826 we did not place parentheses around the word.  This is because we did
1827 not intend to use it as a function name.
1829 If @code{fill-column} were the first or only element of a list, the
1830 Lisp interpreter would attempt to find the function definition
1831 attached to it.  But @code{fill-column} has no function definition.
1832 Try evaluating this:
1834 @smallexample
1835 (fill-column)
1836 @end smallexample
1838 @need 1250
1839 @noindent
1840 In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer
1841 that says:
1843 @smallexample
1844 @group
1845 ---------- Buffer: *Backtrace* ----------
1846 Debugger entered--Lisp error: (void-function fill-column)
1847   (fill-column)
1848   eval((fill-column))
1849   eval-last-sexp-1(nil)
1850   eval-last-sexp(nil)
1851   call-interactively(eval-last-sexp)
1852 ---------- Buffer: *Backtrace* ----------
1853 @end group
1854 @end smallexample
1856 @noindent
1857 (Remember, to quit the debugger and make the debugger window go away,
1858 type @kbd{q} in the @file{*Backtrace*} buffer.)
1860 @ignore
1861 @need 800
1862 In GNU Emacs 20 and before, you will produce an error message that says:
1864 @smallexample
1865 Symbol's function definition is void:@: fill-column
1866 @end smallexample
1868 @noindent
1869 (The message will go away as soon as you move the cursor or type
1870 another key.)
1871 @end ignore
1873 @node Void Variable,  , Void Function, Variables
1874 @comment  node-name,  next,  previous,  up
1875 @subsection Error Message for a Symbol Without a Value
1876 @cindex Symbol without value error
1877 @cindex Error for symbol without value
1879 If you attempt to evaluate a symbol that does not have a value bound to
1880 it, you will receive an error message.  You can see this by
1881 experimenting with our 2 plus 2 addition.  In the following expression,
1882 put your cursor right after the @code{+}, before the first number 2,
1883 type @kbd{C-x C-e}:
1885 @smallexample
1886 (+ 2 2)
1887 @end smallexample
1889 @need 1500
1890 @noindent
1891 In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that
1892 says:
1894 @smallexample
1895 @group
1896 ---------- Buffer: *Backtrace* ----------
1897 Debugger entered--Lisp error: (void-variable +)
1898   eval(+)
1899   eval-last-sexp-1(nil)
1900   eval-last-sexp(nil)
1901   call-interactively(eval-last-sexp)
1902 ---------- Buffer: *Backtrace* ----------
1903 @end group
1904 @end smallexample
1906 @noindent
1907 (As with the other times we entered the debugger, you can quit by
1908 typing @kbd{q} in the @file{*Backtrace*} buffer.)
1910 This backtrace is different from the very first error message we saw,
1911 which said, @samp{Debugger entered--Lisp error: (void-function this)}.
1912 In this case, the function does not have a value as a variable; while
1913 in the other error message, the function (the word `this') did not
1914 have a definition.
1916 In this experiment with the @code{+}, what we did was cause the Lisp
1917 interpreter to evaluate the @code{+} and look for the value of the
1918 variable instead of the function definition.  We did this by placing the
1919 cursor right after the symbol rather than after the parenthesis of the
1920 enclosing list as we did before.  As a consequence, the Lisp interpreter
1921 evaluated the preceding s-expression, which in this case was the
1922 @code{+} by itself.
1924 Since @code{+} does not have a value bound to it, just the function
1925 definition, the error message reported that the symbol's value as a
1926 variable was void.
1928 @ignore
1929 @need 800
1930 In GNU Emacs version 20 and before, your error message will say:
1932 @example
1933 Symbol's value as variable is void:@: +
1934 @end example
1936 @noindent
1937 The meaning is the same as in GNU Emacs 22.
1938 @end ignore
1940 @node Arguments, set & setq, Variables, List Processing
1941 @comment  node-name,  next,  previous,  up
1942 @section Arguments
1943 @cindex Arguments
1944 @cindex Passing information to functions
1946 To see how information is passed to functions, let's look again at
1947 our old standby, the addition of two plus two.  In Lisp, this is written
1948 as follows:
1950 @smallexample
1951 (+ 2 2)
1952 @end smallexample
1954 If you evaluate this expression, the number 4 will appear in your echo
1955 area.  What the Lisp interpreter does is add the numbers that follow
1956 the @code{+}.
1958 @cindex @samp{argument} defined
1959 The numbers added by @code{+} are called the @dfn{arguments} of the
1960 function @code{+}.  These numbers are the information that is given to
1961 or @dfn{passed} to the function.
1963 The word `argument' comes from the way it is used in mathematics and
1964 does not refer to a disputation between two people; instead it refers to
1965 the information presented to the function, in this case, to the
1966 @code{+}.  In Lisp, the arguments to a function are the atoms or lists
1967 that follow the function.  The values returned by the evaluation of
1968 these atoms or lists are passed to the function.  Different functions
1969 require different numbers of arguments; some functions require none at
1970 all.@footnote{It is curious to track the path by which the word `argument'
1971 came to have two different meanings, one in mathematics and the other in
1972 everyday English.  According to the @cite{Oxford English Dictionary},
1973 the word derives from the Latin for @samp{to make clear, prove}; thus it
1974 came to mean, by one thread of derivation, `the evidence offered as
1975 proof', which is to say, `the information offered', which led to its
1976 meaning in Lisp.  But in the other thread of derivation, it came to mean
1977 `to assert in a manner against which others may make counter
1978 assertions', which led to the meaning of the word as a disputation.
1979 (Note here that the English word has two different definitions attached
1980 to it at the same time.  By contrast, in Emacs Lisp, a symbol cannot
1981 have two different function definitions at the same time.)}
1983 @menu
1984 * Data types::                  Types of data passed to a function.
1985 * Args as Variable or List::    An argument can be the value
1986                                   of a variable or list.
1987 * Variable Number of Arguments::  Some functions may take a
1988                                   variable number of arguments.
1989 * Wrong Type of Argument::      Passing an argument of the wrong type
1990                                   to a function.
1991 * message::                     A useful function for sending messages.
1992 @end menu
1994 @node Data types, Args as Variable or List, Arguments, Arguments
1995 @comment  node-name,  next,  previous,  up
1996 @subsection Arguments' Data Types
1997 @cindex Data types
1998 @cindex Types of data
1999 @cindex Arguments' data types
2001 The type of data that should be passed to a function depends on what
2002 kind of information it uses.  The arguments to a function such as
2003 @code{+} must have values that are numbers, since @code{+} adds numbers.
2004 Other functions use different kinds of data for their arguments.
2006 @need 1250
2007 @findex concat
2008 For example, the @code{concat} function links together or unites two or
2009 more strings of text to produce a string.  The arguments are strings.
2010 Concatenating the two character strings @code{abc}, @code{def} produces
2011 the single string @code{abcdef}.  This can be seen by evaluating the
2012 following:
2014 @smallexample
2015 (concat "abc" "def")
2016 @end smallexample
2018 @noindent
2019 The value produced by evaluating this expression is @code{"abcdef"}.
2021 A function such as @code{substring} uses both a string and numbers as
2022 arguments.  The function returns a part of the string, a substring of
2023 the first argument.  This function takes three arguments.  Its first
2024 argument is the string of characters, the second and third arguments are
2025 numbers that indicate the beginning and end of the substring.  The
2026 numbers are a count of the number of characters (including spaces and
2027 punctuations) from the beginning of the string.
2029 @need 800
2030 For example, if you evaluate the following:
2032 @smallexample
2033 (substring "The quick brown fox jumped." 16 19)
2034 @end smallexample
2036 @noindent
2037 you will see @code{"fox"} appear in the echo area.  The arguments are the
2038 string and the two numbers.
2040 Note that the string passed to @code{substring} is a single atom even
2041 though it is made up of several words separated by spaces.  Lisp counts
2042 everything between the two quotation marks as part of the string,
2043 including the spaces.  You can think of the @code{substring} function as
2044 a kind of `atom smasher' since it takes an otherwise indivisible atom
2045 and extracts a part.  However, @code{substring} is only able to extract
2046 a substring from an argument that is a string, not from another type of
2047 atom such as a number or symbol.
2049 @node Args as Variable or List, Variable Number of Arguments, Data types, Arguments
2050 @comment  node-name,  next,  previous,  up
2051 @subsection An Argument as the Value of a Variable or List
2053 An argument can be a symbol that returns a value when it is evaluated.
2054 For example, when the symbol @code{fill-column} by itself is evaluated,
2055 it returns a number.  This number can be used in an addition.
2057 @need 1250
2058 Position the cursor after the following expression and type @kbd{C-x
2059 C-e}:
2061 @smallexample
2062 (+ 2 fill-column)
2063 @end smallexample
2065 @noindent
2066 The value will be a number two more than what you get by evaluating
2067 @code{fill-column} alone.  For me, this is 74, because my value of
2068 @code{fill-column} is 72.
2070 As we have just seen, an argument can be a symbol that returns a value
2071 when evaluated.  In addition, an argument can be a list that returns a
2072 value when it is evaluated.  For example, in the following expression,
2073 the arguments to the function @code{concat} are the strings
2074 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list
2075 @code{(number-to-string (+ 2 fill-column))}.
2077 @c For GNU Emacs 22, need number-to-string
2078 @smallexample
2079 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
2080 @end smallexample
2082 @noindent
2083 If you evaluate this expression---and if, as with my Emacs,
2084 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will
2085 appear in the echo area.  (Note that you must put spaces after the
2086 word @samp{The} and before the word @samp{red} so they will appear in
2087 the final string.  The function @code{number-to-string} converts the
2088 integer that the addition function returns to a string.
2089 @code{number-to-string} is also known as @code{int-to-string}.)
2091 @node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments
2092 @comment  node-name,  next,  previous,  up
2093 @subsection Variable Number of Arguments
2094 @cindex Variable number of arguments
2095 @cindex Arguments, variable number of
2097 Some functions, such as @code{concat}, @code{+} or @code{*}, take any
2098 number of arguments.  (The @code{*} is the symbol for multiplication.)
2099 This can be seen by evaluating each of the following expressions in
2100 the usual way.  What you will see in the echo area is printed in this
2101 text after @samp{@result{}}, which you may read as `evaluates to'.
2103 @need 1250
2104 In the first set, the functions have no arguments:
2106 @smallexample
2107 @group
2108 (+)       @result{} 0
2110 (*)       @result{} 1
2111 @end group
2112 @end smallexample
2114 @need 1250
2115 In this set, the functions have one argument each:
2117 @smallexample
2118 @group
2119 (+ 3)     @result{} 3
2121 (* 3)     @result{} 3
2122 @end group
2123 @end smallexample
2125 @need 1250
2126 In this set, the functions have three arguments each:
2128 @smallexample
2129 @group
2130 (+ 3 4 5) @result{} 12
2132 (* 3 4 5) @result{} 60
2133 @end group
2134 @end smallexample
2136 @node Wrong Type of Argument, message, Variable Number of Arguments, Arguments
2137 @comment  node-name,  next,  previous,  up
2138 @subsection Using the Wrong Type Object as an Argument
2139 @cindex Wrong type of argument
2140 @cindex Argument, wrong type of
2142 When a function is passed an argument of the wrong type, the Lisp
2143 interpreter produces an error message.  For example, the @code{+}
2144 function expects the values of its arguments to be numbers.  As an
2145 experiment we can pass it the quoted symbol @code{hello} instead of a
2146 number.  Position the cursor after the following expression and type
2147 @kbd{C-x C-e}:
2149 @smallexample
2150 (+ 2 'hello)
2151 @end smallexample
2153 @noindent
2154 When you do this you will generate an error message.  What has happened
2155 is that @code{+} has tried to add the 2 to the value returned by
2156 @code{'hello}, but the value returned by @code{'hello} is the symbol
2157 @code{hello}, not a number.  Only numbers can be added.  So @code{+}
2158 could not carry out its addition.
2160 @need 1250
2161 In GNU Emacs version 22, you will create and enter a
2162 @file{*Backtrace*} buffer that says:
2164 @noindent
2165 @smallexample
2166 @group
2167 ---------- Buffer: *Backtrace* ----------
2168 Debugger entered--Lisp error:
2169          (wrong-type-argument number-or-marker-p hello)
2170   +(2 hello)
2171   eval((+ 2 (quote hello)))
2172   eval-last-sexp-1(nil)
2173   eval-last-sexp(nil)
2174   call-interactively(eval-last-sexp)
2175 ---------- Buffer: *Backtrace* ----------
2176 @end group
2177 @end smallexample
2179 @need 1250
2180 As usual, the error message tries to be helpful and makes sense after you
2181 learn how to read it.@footnote{@code{(quote hello)} is an expansion of
2182 the abbreviation @code{'hello}.}
2184 The first part of the error message is straightforward; it says
2185 @samp{wrong type argument}.  Next comes the mysterious jargon word
2186 @w{@samp{number-or-marker-p}}.  This word is trying to tell you what
2187 kind of argument the @code{+} expected.
2189 The symbol @code{number-or-marker-p} says that the Lisp interpreter is
2190 trying to determine whether the information presented it (the value of
2191 the argument) is a number or a marker (a special object representing a
2192 buffer position).  What it does is test to see whether the @code{+} is
2193 being given numbers to add.  It also tests to see whether the
2194 argument is something called a marker, which is a specific feature of
2195 Emacs Lisp.  (In Emacs, locations in a buffer are recorded as markers.
2196 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
2197 its position is kept as a marker.  The mark can be considered a
2198 number---the number of characters the location is from the beginning
2199 of the buffer.)  In Emacs Lisp, @code{+} can be used to add the
2200 numeric value of marker positions as numbers.
2202 The @samp{p} of @code{number-or-marker-p} is the embodiment of a
2203 practice started in the early days of Lisp programming.  The @samp{p}
2204 stands for `predicate'.  In the jargon used by the early Lisp
2205 researchers, a predicate refers to a function to determine whether some
2206 property is true or false.  So the @samp{p} tells us that
2207 @code{number-or-marker-p} is the name of a function that determines
2208 whether it is true or false that the argument supplied is a number or
2209 a marker.  Other Lisp symbols that end in @samp{p} include @code{zerop},
2210 a function that tests whether its argument has the value of zero, and
2211 @code{listp}, a function that tests whether its argument is a list.
2213 Finally, the last part of the error message is the symbol @code{hello}.
2214 This is the value of the argument that was passed to @code{+}.  If the
2215 addition had been passed the correct type of object, the value passed
2216 would have been a number, such as 37, rather than a symbol like
2217 @code{hello}.  But then you would not have got the error message.
2219 @ignore
2220 @need 1250
2221 In GNU Emacs version 20 and before, the echo area displays an error
2222 message that says:
2224 @smallexample
2225 Wrong type argument:@: number-or-marker-p, hello
2226 @end smallexample
2228 This says, in different words, the same as the top line of the
2229 @file{*Backtrace*} buffer.
2230 @end ignore
2232 @node message,  , Wrong Type of Argument, Arguments
2233 @comment  node-name,  next,  previous,  up
2234 @subsection The @code{message} Function
2235 @findex message
2237 Like @code{+}, the @code{message} function takes a variable number of
2238 arguments.  It is used to send messages to the user and is so useful
2239 that we will describe it here.
2241 @need 1250
2242 A message is printed in the echo area.  For example, you can print a
2243 message in your echo area by evaluating the following list:
2245 @smallexample
2246 (message "This message appears in the echo area!")
2247 @end smallexample
2249 The whole string between double quotation marks is a single argument
2250 and is printed @i{in toto}.  (Note that in this example, the message
2251 itself will appear in the echo area within double quotes; that is
2252 because you see the value returned by the @code{message} function.  In
2253 most uses of @code{message} in programs that you write, the text will
2254 be printed in the echo area as a side-effect, without the quotes.
2255 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in
2256 detail}, for an example of this.)
2258 However, if there is a @samp{%s} in the quoted string of characters, the
2259 @code{message} function does not print the @samp{%s} as such, but looks
2260 to the argument that follows the string.  It evaluates the second
2261 argument and prints the value at the location in the string where the
2262 @samp{%s} is.
2264 @need 1250
2265 You can see this by positioning the cursor after the following
2266 expression and typing @kbd{C-x C-e}:
2268 @smallexample
2269 (message "The name of this buffer is: %s." (buffer-name))
2270 @end smallexample
2272 @noindent
2273 In Info, @code{"The name of this buffer is: *info*."} will appear in the
2274 echo area.  The function @code{buffer-name} returns the name of the
2275 buffer as a string, which the @code{message} function inserts in place
2276 of @code{%s}.
2278 To print a value as an integer, use @samp{%d} in the same way as
2279 @samp{%s}.  For example, to print a message in the echo area that
2280 states the value of the @code{fill-column}, evaluate the following:
2282 @smallexample
2283 (message "The value of fill-column is %d." fill-column)
2284 @end smallexample
2286 @noindent
2287 On my system, when I evaluate this list, @code{"The value of
2288 fill-column is 72."} appears in my echo area@footnote{Actually, you
2289 can use @code{%s} to print a number.  It is non-specific.  @code{%d}
2290 prints only the part of a number left of a decimal point, and not
2291 anything that is not a number.}.
2293 If there is more than one @samp{%s} in the quoted string, the value of
2294 the first argument following the quoted string is printed at the
2295 location of the first @samp{%s} and the value of the second argument is
2296 printed at the location of the second @samp{%s}, and so on.
2298 @need 1250
2299 For example, if you evaluate the following,
2301 @smallexample
2302 @group
2303 (message "There are %d %s in the office!"
2304          (- fill-column 14) "pink elephants")
2305 @end group
2306 @end smallexample
2308 @noindent
2309 a rather whimsical message will appear in your echo area.  On my system
2310 it says, @code{"There are 58 pink elephants in the office!"}.
2312 The expression @code{(- fill-column 14)} is evaluated and the resulting
2313 number is inserted in place of the @samp{%d}; and the string in double
2314 quotes, @code{"pink elephants"}, is treated as a single argument and
2315 inserted in place of the @samp{%s}.  (That is to say, a string between
2316 double quotes evaluates to itself, like a number.)
2318 Finally, here is a somewhat complex example that not only illustrates
2319 the computation of a number, but also shows how you can use an
2320 expression within an expression to generate the text that is substituted
2321 for @samp{%s}:
2323 @smallexample
2324 @group
2325 (message "He saw %d %s"
2326          (- fill-column 32)
2327          (concat "red "
2328                  (substring
2329                   "The quick brown foxes jumped." 16 21)
2330                  " leaping."))
2331 @end group
2332 @end smallexample
2334 In this example, @code{message} has three arguments: the string,
2335 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and
2336 the expression beginning with the function @code{concat}.  The value
2337 resulting from the evaluation of @code{(- fill-column 32)} is inserted
2338 in place of the @samp{%d}; and the value returned by the expression
2339 beginning with @code{concat} is inserted in place of the @samp{%s}.
2341 When your fill column is 70 and you evaluate the expression, the
2342 message @code{"He saw 38 red foxes leaping."} appears in your echo
2343 area.
2345 @node set & setq, Summary, Arguments, List Processing
2346 @comment  node-name,  next,  previous,  up
2347 @section Setting the Value of a Variable
2348 @cindex Variable, setting value
2349 @cindex Setting value of variable
2351 @cindex @samp{bind} defined
2352 There are several ways by which a variable can be given a value.  One of
2353 the ways is to use either the function @code{set} or the function
2354 @code{setq}.  Another way is to use @code{let} (@pxref{let}).  (The
2355 jargon for this process is to @dfn{bind} a variable to a value.)
2357 The following sections not only describe how @code{set} and @code{setq}
2358 work but also illustrate how arguments are passed.
2360 @menu
2361 * Using set::                  Setting values.
2362 * Using setq::                 Setting a quoted value.
2363 * Counting::                   Using @code{setq} to count.
2364 @end menu
2366 @node Using set, Using setq, set & setq, set & setq
2367 @comment  node-name,  next,  previous,  up
2368 @subsection Using @code{set}
2369 @findex set
2371 To set the value of the symbol @code{flowers} to the list @code{'(rose
2372 violet daisy buttercup)}, evaluate the following expression by
2373 positioning the cursor after the expression and typing @kbd{C-x C-e}.
2375 @smallexample
2376 (set 'flowers '(rose violet daisy buttercup))
2377 @end smallexample
2379 @noindent
2380 The list @code{(rose violet daisy buttercup)} will appear in the echo
2381 area.  This is what is @emph{returned} by the @code{set} function.  As a
2382 side effect, the symbol @code{flowers} is bound to the list; that is,
2383 the symbol @code{flowers}, which can be viewed as a variable, is given
2384 the list as its value.  (This process, by the way, illustrates how a
2385 side effect to the Lisp interpreter, setting the value, can be the
2386 primary effect that we humans are interested in.  This is because every
2387 Lisp function must return a value if it does not get an error, but it
2388 will only have a side effect if it is designed to have one.)
2390 After evaluating the @code{set} expression, you can evaluate the symbol
2391 @code{flowers} and it will return the value you just set.  Here is the
2392 symbol.  Place your cursor after it and type @kbd{C-x C-e}.
2394 @smallexample
2395 flowers
2396 @end smallexample
2398 @noindent
2399 When you evaluate @code{flowers}, the list
2400 @code{(rose violet daisy buttercup)} appears in the echo area.
2402 Incidentally, if you evaluate @code{'flowers}, the variable with a quote
2403 in front of it, what you will see in the echo area is the symbol itself,
2404 @code{flowers}.  Here is the quoted symbol, so you can try this:
2406 @smallexample
2407 'flowers
2408 @end smallexample
2410 Note also, that when you use @code{set}, you need to quote both
2411 arguments to @code{set}, unless you want them evaluated.  Since we do
2412 not want either argument evaluated, neither the variable
2413 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
2414 are quoted.  (When you use @code{set} without quoting its first
2415 argument, the first argument is evaluated before anything else is
2416 done.  If you did this and @code{flowers} did not have a value
2417 already, you would get an error message that the @samp{Symbol's value
2418 as variable is void}; on the other hand, if @code{flowers} did return
2419 a value after it was evaluated, the @code{set} would attempt to set
2420 the value that was returned.  There are situations where this is the
2421 right thing for the function to do; but such situations are rare.)
2423 @node Using setq, Counting, Using set, set & setq
2424 @comment  node-name,  next,  previous,  up
2425 @subsection Using @code{setq}
2426 @findex setq
2428 As a practical matter, you almost always quote the first argument to
2429 @code{set}.  The combination of @code{set} and a quoted first argument
2430 is so common that it has its own name: the special form @code{setq}.
2431 This special form is just like @code{set} except that the first argument
2432 is quoted automatically, so you don't need to type the quote mark
2433 yourself.  Also, as an added convenience, @code{setq} permits you to set
2434 several different variables to different values, all in one expression.
2436 To set the value of the variable @code{carnivores} to the list
2437 @code{'(lion tiger leopard)} using @code{setq}, the following expression
2438 is used:
2440 @smallexample
2441 (setq carnivores '(lion tiger leopard))
2442 @end smallexample
2444 @noindent
2445 This is exactly the same as using @code{set} except the first argument
2446 is automatically quoted by @code{setq}.  (The @samp{q} in @code{setq}
2447 means @code{quote}.)
2449 @need 1250
2450 With @code{set}, the expression would look like this:
2452 @smallexample
2453 (set 'carnivores '(lion tiger leopard))
2454 @end smallexample
2456 Also, @code{setq} can be used to assign different values to
2457 different variables.  The first argument is bound to the value
2458 of the second argument, the third argument is bound to the value of the
2459 fourth argument, and so on.  For example, you could use the following to
2460 assign a list of trees to the symbol @code{trees} and a list of herbivores
2461 to the symbol @code{herbivores}:
2463 @smallexample
2464 @group
2465 (setq trees '(pine fir oak maple)
2466       herbivores '(gazelle antelope zebra))
2467 @end group
2468 @end smallexample
2470 @noindent
2471 (The expression could just as well have been on one line, but it might
2472 not have fit on a page; and humans find it easier to read nicely
2473 formatted lists.)
2475 Although I have been using the term `assign', there is another way of
2476 thinking about the workings of @code{set} and @code{setq}; and that is to
2477 say that @code{set} and @code{setq} make the symbol @emph{point} to the
2478 list.  This latter way of thinking is very common and in forthcoming
2479 chapters we shall come upon at least one symbol that has `pointer' as
2480 part of its name.  The name is chosen because the symbol has a value,
2481 specifically a list, attached to it; or, expressed another way,
2482 the symbol is set to ``point'' to the list.
2484 @node Counting,  , Using setq, set & setq
2485 @comment  node-name,  next,  previous,  up
2486 @subsection Counting
2487 @cindex Counting
2489 Here is an example that shows how to use @code{setq} in a counter.  You
2490 might use this to count how many times a part of your program repeats
2491 itself.  First set a variable to zero; then add one to the number each
2492 time the program repeats itself.  To do this, you need a variable that
2493 serves as a counter, and two expressions: an initial @code{setq}
2494 expression that sets the counter variable to zero; and a second
2495 @code{setq} expression that increments the counter each time it is
2496 evaluated.
2498 @smallexample
2499 @group
2500 (setq counter 0)                ; @r{Let's call this the initializer.}
2502 (setq counter (+ counter 1))    ; @r{This is the incrementer.}
2504 counter                         ; @r{This is the counter.}
2505 @end group
2506 @end smallexample
2508 @noindent
2509 (The text following the @samp{;} are comments.  @xref{Change a
2510 defun, , Change a Function Definition}.)
2512 If you evaluate the first of these expressions, the initializer,
2513 @code{(setq counter 0)}, and then evaluate the third expression,
2514 @code{counter}, the number @code{0} will appear in the echo area.  If
2515 you then evaluate the second expression, the incrementer, @code{(setq
2516 counter (+ counter 1))}, the counter will get the value 1.  So if you
2517 again evaluate @code{counter}, the number @code{1} will appear in the
2518 echo area.  Each time you evaluate the second expression, the value of
2519 the counter will be incremented.
2521 When you evaluate the incrementer, @code{(setq counter (+ counter 1))},
2522 the Lisp interpreter first evaluates the innermost list; this is the
2523 addition.  In order to evaluate this list, it must evaluate the variable
2524 @code{counter} and the number @code{1}.  When it evaluates the variable
2525 @code{counter}, it receives its current value.  It passes this value and
2526 the number @code{1} to the @code{+} which adds them together.  The sum
2527 is then returned as the value of the inner list and passed to the
2528 @code{setq} which sets the variable @code{counter} to this new value.
2529 Thus, the value of the variable, @code{counter}, is changed.
2531 @node Summary, Error Message Exercises, set & setq, List Processing
2532 @comment  node-name,  next,  previous,  up
2533 @section Summary
2535 Learning Lisp is like climbing a hill in which the first part is the
2536 steepest.  You have now climbed the most difficult part; what remains
2537 becomes easier as you progress onwards.
2539 @need 1000
2540 In summary,
2542 @itemize @bullet
2544 @item
2545 Lisp programs are made up of expressions, which are lists or single atoms.
2547 @item
2548 Lists are made up of zero or more atoms or inner lists, separated by whitespace and
2549 surrounded by parentheses.  A list can be empty.
2551 @item
2552 Atoms are multi-character symbols, like @code{forward-paragraph}, single
2553 character symbols like @code{+}, strings of characters between double
2554 quotation marks, or numbers.
2556 @item
2557 A number evaluates to itself.
2559 @item
2560 A string between double quotes also evaluates to itself.
2562 @item
2563 When you evaluate a symbol by itself, its value is returned.
2565 @item
2566 When you evaluate a list, the Lisp interpreter looks at the first symbol
2567 in the list and then at the function definition bound to that symbol.
2568 Then the instructions in the function definition are carried out.
2570 @item
2571 A single quotation mark,
2572 @ifinfo
2574 @end ifinfo
2575 @ifnotinfo
2576 @code{'}
2577 @end ifnotinfo
2578 , tells the Lisp interpreter that it should
2579 return the following expression as written, and not evaluate it as it
2580 would if the quote were not there.
2582 @item
2583 Arguments are the information passed to a function.  The arguments to a
2584 function are computed by evaluating the rest of the elements of the list
2585 of which the function is the first element.
2587 @item
2588 A function always returns a value when it is evaluated (unless it gets
2589 an error); in addition, it may also carry out some action called a
2590 ``side effect''.  In many cases, a function's primary purpose is to
2591 create a side effect.
2592 @end itemize
2594 @node Error Message Exercises,  , Summary, List Processing
2595 @comment  node-name,  next,  previous,  up
2596 @section Exercises
2598 A few simple exercises:
2600 @itemize @bullet
2601 @item
2602 Generate an error message by evaluating an appropriate symbol that is
2603 not within parentheses.
2605 @item
2606 Generate an error message by evaluating an appropriate symbol that is
2607 between parentheses.
2609 @item
2610 Create a counter that increments by two rather than one.
2612 @item
2613 Write an expression that prints a message in the echo area when
2614 evaluated.
2615 @end itemize
2617 @node Practicing Evaluation, Writing Defuns, List Processing, Top
2618 @comment  node-name,  next,  previous,  up
2619 @chapter Practicing Evaluation
2620 @cindex Practicing evaluation
2621 @cindex Evaluation practice
2623 Before learning how to write a function definition in Emacs Lisp, it is
2624 useful to spend a little time evaluating various expressions that have
2625 already been written.  These expressions will be lists with the
2626 functions as their first (and often only) element.  Since some of the
2627 functions associated with buffers are both simple and interesting, we
2628 will start with those.  In this section, we will evaluate a few of
2629 these.  In another section, we will study the code of several other
2630 buffer-related functions, to see how they were written.
2632 @menu
2633 * How to Evaluate::            Typing editing commands or @kbd{C-x C-e}
2634                                  causes evaluation.
2635 * Buffer Names::               Buffers and files are different.
2636 * Getting Buffers::            Getting a buffer itself, not merely its name.
2637 * Switching Buffers::          How to change to another buffer.
2638 * Buffer Size & Locations::    Where point is located and the size of
2639                                the buffer.
2640 * Evaluation Exercise::
2641 @end menu
2643 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
2644 @ifnottex
2645 @unnumberedsec How to Evaluate
2646 @end ifnottex
2648 @i{Whenever you give an editing command} to Emacs Lisp, such as the
2649 command to move the cursor or to scroll the screen, @i{you are evaluating
2650 an expression,} the first element of which is a function.  @i{This is
2651 how Emacs works.}
2653 @cindex @samp{interactive function} defined
2654 @cindex @samp{command} defined
2655 When you type keys, you cause the Lisp interpreter to evaluate an
2656 expression and that is how you get your results.  Even typing plain text
2657 involves evaluating an Emacs Lisp function, in this case, one that uses
2658 @code{self-insert-command}, which simply inserts the character you
2659 typed.  The functions you evaluate by typing keystrokes are called
2660 @dfn{interactive} functions, or @dfn{commands}; how you make a function
2661 interactive will be illustrated in the chapter on how to write function
2662 definitions.  @xref{Interactive, , Making a Function Interactive}.
2664 In addition to typing keyboard commands, we have seen a second way to
2665 evaluate an expression: by positioning the cursor after a list and
2666 typing @kbd{C-x C-e}.  This is what we will do in the rest of this
2667 section.  There are other ways to evaluate an expression as well; these
2668 will be described as we come to them.
2670 Besides being used for practicing evaluation, the functions shown in the
2671 next few sections are important in their own right.  A study of these
2672 functions makes clear the distinction between buffers and files, how to
2673 switch to a buffer, and how to determine a location within it.
2675 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation
2676 @comment  node-name,  next,  previous,  up
2677 @section Buffer Names
2678 @findex buffer-name
2679 @findex buffer-file-name
2681 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
2682 the difference between a file and a buffer.  When you evaluate the
2683 following expression, @code{(buffer-name)}, the name of the buffer
2684 appears in the echo area.  When you evaluate @code{(buffer-file-name)},
2685 the name of the file to which the buffer refers appears in the echo
2686 area.  Usually, the name returned by @code{(buffer-name)} is the same as
2687 the name of the file to which it refers, and the name returned by
2688 @code{(buffer-file-name)} is the full path-name of the file.
2690 A file and a buffer are two different entities.  A file is information
2691 recorded permanently in the computer (unless you delete it).  A buffer,
2692 on the other hand, is information inside of Emacs that will vanish at
2693 the end of the editing session (or when you kill the buffer).  Usually,
2694 a buffer contains information that you have copied from a file; we say
2695 the buffer is @dfn{visiting} that file.  This copy is what you work on
2696 and modify.  Changes to the buffer do not change the file, until you
2697 save the buffer.  When you save the buffer, the buffer is copied to the file
2698 and is thus saved permanently.
2700 @need 1250
2701 If you are reading this in Info inside of GNU Emacs, you can evaluate
2702 each of the following expressions by positioning the cursor after it and
2703 typing @kbd{C-x C-e}.
2705 @example
2706 @group
2707 (buffer-name)
2709 (buffer-file-name)
2710 @end group
2711 @end example
2713 @noindent
2714 When I do this in Info, the value returned by evaluating
2715 @code{(buffer-name)} is @file{"*info*"}, and the value returned by
2716 evaluating @code{(buffer-file-name)} is @file{nil}.
2718 On the other hand, while I am writing this Introduction, the value
2719 returned by evaluating @code{(buffer-name)} is
2720 @file{"introduction.texinfo"}, and the value returned by evaluating
2721 @code{(buffer-file-name)} is
2722 @file{"/gnu/work/intro/introduction.texinfo"}.
2724 @cindex @code{nil}, history of word
2725 The former is the name of the buffer and the latter is the name of the
2726 file.  In Info, the buffer name is @file{"*info*"}.  Info does not
2727 point to any file, so the result of evaluating
2728 @code{(buffer-file-name)} is @file{nil}.  The symbol @code{nil} is
2729 from the Latin word for `nothing'; in this case, it means that the
2730 buffer is not associated with any file.  (In Lisp, @code{nil} is also
2731 used to mean `false' and is a synonym for the empty list, @code{()}.)
2733 When I am writing, the name of my buffer is
2734 @file{"introduction.texinfo"}.  The name of the file to which it
2735 points is @file{"/gnu/work/intro/introduction.texinfo"}.
2737 (In the expressions, the parentheses tell the Lisp interpreter to
2738 treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
2739 functions; without the parentheses, the interpreter would attempt to
2740 evaluate the symbols as variables.  @xref{Variables}.)
2742 In spite of the distinction between files and buffers, you will often
2743 find that people refer to a file when they mean a buffer and vice-verse.
2744 Indeed, most people say, ``I am editing a file,'' rather than saying,
2745 ``I am editing a buffer which I will soon save to a file.''  It is
2746 almost always clear from context what people mean.  When dealing with
2747 computer programs, however, it is important to keep the distinction in mind,
2748 since the computer is not as smart as a person.
2750 @cindex Buffer, history of word
2751 The word `buffer', by the way, comes from the meaning of the word as a
2752 cushion that deadens the force of a collision.  In early computers, a
2753 buffer cushioned the interaction between files and the computer's
2754 central processing unit.  The drums or tapes that held a file and the
2755 central processing unit were pieces of equipment that were very
2756 different from each other, working at their own speeds, in spurts.  The
2757 buffer made it possible for them to work together effectively.
2758 Eventually, the buffer grew from being an intermediary, a temporary
2759 holding place, to being the place where work is done.  This
2760 transformation is rather like that of a small seaport that grew into a
2761 great city: once it was merely the place where cargo was warehoused
2762 temporarily before being loaded onto ships; then it became a business
2763 and cultural center in its own right.
2765 Not all buffers are associated with files.  For example, a
2766 @file{*scratch*} buffer does not visit any file.  Similarly, a
2767 @file{*Help*} buffer is not associated with any file.
2769 In the old days, when you lacked a @file{~/.emacs} file and started an
2770 Emacs session by typing the command @code{emacs} alone, without naming
2771 any files, Emacs started with the @file{*scratch*} buffer visible.
2772 Nowadays, you will see a splash screen.  You can follow one of the
2773 commands suggested on the splash screen, visit a file, or press the
2774 spacebar to reach the @file{*scratch*} buffer.
2776 If you switch to the @file{*scratch*} buffer, type
2777 @code{(buffer-name)}, position the cursor after it, and then type
2778 @kbd{C-x C-e} to evaluate the expression.  The name @code{"*scratch*"}
2779 will be returned and will appear in the echo area.  @code{"*scratch*"}
2780 is the name of the buffer.  When you type @code{(buffer-file-name)} in
2781 the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
2782 in the echo area, just as it does when you evaluate
2783 @code{(buffer-file-name)} in Info.
2785 Incidentally, if you are in the @file{*scratch*} buffer and want the
2786 value returned by an expression to appear in the @file{*scratch*}
2787 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
2788 instead of @kbd{C-x C-e}.  This causes the value returned to appear
2789 after the expression.  The buffer will look like this:
2791 @smallexample
2792 (buffer-name)"*scratch*"
2793 @end smallexample
2795 @noindent
2796 You cannot do this in Info since Info is read-only and it will not allow
2797 you to change the contents of the buffer.  But you can do this in any
2798 buffer you can edit; and when you write code or documentation (such as
2799 this book), this feature is very useful.
2801 @node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation
2802 @comment  node-name,  next,  previous,  up
2803 @section Getting Buffers
2804 @findex current-buffer
2805 @findex other-buffer
2806 @cindex Getting a buffer
2808 The @code{buffer-name} function returns the @emph{name} of the buffer;
2809 to get the buffer @emph{itself}, a different function is needed: the
2810 @code{current-buffer} function.  If you use this function in code, what
2811 you get is the buffer itself.
2813 A name and the object or entity to which the name refers are different
2814 from each other.  You are not your name.  You are a person to whom
2815 others refer by name.  If you ask to speak to George and someone hands you
2816 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
2817 @samp{g}, and @samp{e} written on it, you might be amused, but you would
2818 not be satisfied.  You do not want to speak to the name, but to the
2819 person to whom the name refers.  A buffer is similar: the name of the
2820 scratch buffer is @file{*scratch*}, but the name is not the buffer.  To
2821 get a buffer itself, you need to use a function such as
2822 @code{current-buffer}.
2824 However, there is a slight complication: if you evaluate
2825 @code{current-buffer} in an expression on its own, as we will do here,
2826 what you see is a printed representation of the name of the buffer
2827 without the contents of the buffer.  Emacs works this way for two
2828 reasons: the buffer may be thousands of lines long---too long to be
2829 conveniently displayed; and, another buffer may have the same contents
2830 but a different name, and it is important to distinguish between them.
2832 @need 800
2833 Here is an expression containing the function:
2835 @smallexample
2836 (current-buffer)
2837 @end smallexample
2839 @noindent
2840 If you evaluate this expression in Info in Emacs in the usual way,
2841 @file{#<buffer *info*>} will appear in the echo area.  The special
2842 format indicates that the buffer itself is being returned, rather than
2843 just its name.
2845 Incidentally, while you can type a number or symbol into a program, you
2846 cannot do that with the printed representation of a buffer: the only way
2847 to get a buffer itself is with a function such as @code{current-buffer}.
2849 A related function is @code{other-buffer}.  This returns the most
2850 recently selected buffer other than the one you are in currently, not
2851 a printed representation of its name.  If you have recently switched
2852 back and forth from the @file{*scratch*} buffer, @code{other-buffer}
2853 will return that buffer.
2855 @need 800
2856 You can see this by evaluating the expression:
2858 @smallexample
2859 (other-buffer)
2860 @end smallexample
2862 @noindent
2863 You should see @file{#<buffer *scratch*>} appear in the echo area, or
2864 the name of whatever other buffer you switched back from most
2865 recently@footnote{Actually, by default, if the buffer from which you
2866 just switched is visible to you in another window, @code{other-buffer}
2867 will choose the most recent buffer that you cannot see; this is a
2868 subtlety that I often forget.}.
2870 @node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation
2871 @comment  node-name,  next,  previous,  up
2872 @section Switching Buffers
2873 @findex switch-to-buffer
2874 @findex set-buffer
2875 @cindex Switching to a buffer
2877 The @code{other-buffer} function actually provides a buffer when it is
2878 used as an argument to a function that requires one.  We can see this
2879 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
2880 different buffer.
2882 But first, a brief introduction to the @code{switch-to-buffer}
2883 function.  When you switched back and forth from Info to the
2884 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
2885 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
2886 rather, to save typing, you probably only typed @kbd{RET} if the
2887 default buffer was @file{*scratch*}, or if it was different, then you
2888 typed just part of the name, such as @code{*sc}, pressed your
2889 @kbd{TAB} key to cause it to expand to the full name, and then typed
2890 your @kbd{RET} key.} when prompted in the minibuffer for the name of
2891 the buffer to which you wanted to switch.  The keystrokes, @kbd{C-x
2892 b}, cause the Lisp interpreter to evaluate the interactive function
2893 @code{switch-to-buffer}.  As we said before, this is how Emacs works:
2894 different keystrokes call or run different functions.  For example,
2895 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
2896 @code{forward-sentence}, and so on.
2898 By writing @code{switch-to-buffer} in an expression, and giving it a
2899 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
2900 does.
2902 @need 1000
2903 Here is the Lisp expression:
2905 @smallexample
2906 (switch-to-buffer (other-buffer))
2907 @end smallexample
2909 @noindent
2910 The symbol @code{switch-to-buffer} is the first element of the list,
2911 so the Lisp interpreter will treat it as a function and carry out the
2912 instructions that are attached to it.  But before doing that, the
2913 interpreter will note that @code{other-buffer} is inside parentheses
2914 and work on that symbol first.  @code{other-buffer} is the first (and
2915 in this case, the only) element of this list, so the Lisp interpreter
2916 calls or runs the function.  It returns another buffer.  Next, the
2917 interpreter runs @code{switch-to-buffer}, passing to it, as an
2918 argument, the other buffer, which is what Emacs will switch to.  If
2919 you are reading this in Info, try this now.  Evaluate the expression.
2920 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
2921 expression will move you to your most recent other buffer that you
2922 cannot see.  If you really want to go to your most recently selected
2923 buffer, even if you can still see it, you need to evaluate the
2924 following more complex expression:
2926 @smallexample
2927 (switch-to-buffer (other-buffer (current-buffer) t))
2928 @end smallexample
2930 @c noindent
2931 In this case, the first argument to @code{other-buffer} tells it which
2932 buffer to skip---the current one---and the second argument tells
2933 @code{other-buffer} it is OK to switch to a visible buffer.
2934 In regular use, @code{switch-to-buffer} takes you to an invisible
2935 window since you would most likely use @kbd{C-x o} (@code{other-window})
2936 to go to another visible buffer.}
2938 In the programming examples in later sections of this document, you will
2939 see the function @code{set-buffer} more often than
2940 @code{switch-to-buffer}.  This is because of a difference between
2941 computer programs and humans: humans have eyes and expect to see the
2942 buffer on which they are working on their computer terminals.  This is
2943 so obvious, it almost goes without saying.  However, programs do not
2944 have eyes.  When a computer program works on a buffer, that buffer does
2945 not need to be visible on the screen.
2947 @code{switch-to-buffer} is designed for humans and does two different
2948 things: it switches the buffer to which Emacs' attention is directed; and
2949 it switches the buffer displayed in the window to the new buffer.
2950 @code{set-buffer}, on the other hand, does only one thing: it switches
2951 the attention of the computer program to a different buffer.  The buffer
2952 on the screen remains unchanged (of course, normally nothing happens
2953 there until the command finishes running).
2955 @cindex @samp{call} defined
2956 Also, we have just introduced another jargon term, the word @dfn{call}.
2957 When you evaluate a list in which the first symbol is a function, you
2958 are calling that function.  The use of the term comes from the notion of
2959 the function as an entity that can do something for you if you `call'
2960 it---just as a plumber is an entity who can fix a leak if you call him
2961 or her.
2963 @node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation
2964 @comment  node-name,  next,  previous,  up
2965 @section Buffer Size and the Location of Point
2966 @cindex Size of buffer
2967 @cindex Buffer size
2968 @cindex Point location
2969 @cindex Location of point
2971 Finally, let's look at several rather simple functions,
2972 @code{buffer-size}, @code{point}, @code{point-min}, and
2973 @code{point-max}.  These give information about the size of a buffer and
2974 the location of point within it.
2976 The function @code{buffer-size} tells you the size of the current
2977 buffer; that is, the function returns a count of the number of
2978 characters in the buffer.
2980 @smallexample
2981 (buffer-size)
2982 @end smallexample
2984 @noindent
2985 You can evaluate this in the usual way, by positioning the
2986 cursor after the expression and typing @kbd{C-x C-e}.
2988 @cindex @samp{point} defined
2989 In Emacs, the current  position of the cursor is called @dfn{point}.
2990 The expression @code{(point)} returns a number that tells you where the
2991 cursor is located as a count of the number of characters from the
2992 beginning of the buffer up to point.
2994 @need 1250
2995 You can see the character count for point in this buffer by evaluating
2996 the following expression in the usual way:
2998 @smallexample
2999 (point)
3000 @end smallexample
3002 @noindent
3003 As I write this, the value of @code{point} is 65724.  The @code{point}
3004 function is frequently used in some of the examples later in this
3005 book.
3007 @need 1250
3008 The value of point depends, of course, on its location within the
3009 buffer.  If you evaluate point in this spot, the number will be larger:
3011 @smallexample
3012 (point)
3013 @end smallexample
3015 @noindent
3016 For me, the value of point in this location is 66043, which means that
3017 there are 319 characters (including spaces) between the two
3018 expressions.  (Doubtless, you will see different numbers, since I will
3019 have edited this since I first evaluated point.)
3021 @cindex @samp{narrowing} defined
3022 The function @code{point-min} is somewhat similar to @code{point}, but
3023 it returns the value of the minimum permissible value of point in the
3024 current buffer.  This is the number 1 unless @dfn{narrowing} is in
3025 effect.  (Narrowing is a mechanism whereby you can restrict yourself,
3026 or a program, to operations on just a part of a buffer.
3027 @xref{Narrowing & Widening, , Narrowing and Widening}.)  Likewise, the
3028 function @code{point-max} returns the value of the maximum permissible
3029 value of point in the current buffer.
3031 @node Evaluation Exercise,  , Buffer Size & Locations, Practicing Evaluation
3032 @section Exercise
3034 Find a file with which you are working and move towards its middle.
3035 Find its buffer name, file name, length, and your position in the file.
3037 @node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top
3038 @comment  node-name,  next,  previous,  up
3039 @chapter How To Write Function Definitions
3040 @cindex Definition writing
3041 @cindex Function definition writing
3042 @cindex Writing a function definition
3044 When the Lisp interpreter evaluates a list, it looks to see whether the
3045 first symbol on the list has a function definition attached to it; or,
3046 put another way, whether the symbol points to a function definition.  If
3047 it does, the computer carries out the instructions in the definition.  A
3048 symbol that has a function definition is called, simply, a function
3049 (although, properly speaking, the definition is the function and the
3050 symbol refers to it.)
3052 @menu
3053 * Primitive Functions::
3054 * defun::                        The @code{defun} special form.
3055 * Install::                      Install a function definition.
3056 * Interactive::                  Making a function interactive.
3057 * Interactive Options::          Different options for @code{interactive}.
3058 * Permanent Installation::       Installing code permanently.
3059 * let::                          Creating and initializing local variables.
3060 * if::                           What if?
3061 * else::                         If--then--else expressions.
3062 * Truth & Falsehood::            What Lisp considers false and true.
3063 * save-excursion::               Keeping track of point, mark, and buffer.
3064 * Review::
3065 * defun Exercises::
3066 @end menu
3068 @node Primitive Functions, defun, Writing Defuns, Writing Defuns
3069 @ifnottex
3070 @unnumberedsec An Aside about Primitive Functions
3071 @end ifnottex
3072 @cindex Primitive functions
3073 @cindex Functions, primitive
3075 @cindex C language primitives
3076 @cindex Primitives written in C
3077 All functions are defined in terms of other functions, except for a few
3078 @dfn{primitive} functions that are written in the C programming
3079 language.  When you write functions' definitions, you will write them in
3080 Emacs Lisp and use other functions as your building blocks.  Some of the
3081 functions you will use will themselves be written in Emacs Lisp (perhaps
3082 by you) and some will be primitives written in C.  The primitive
3083 functions are used exactly like those written in Emacs Lisp and behave
3084 like them.  They are written in C so we can easily run GNU Emacs on any
3085 computer that has sufficient power and can run C.
3087 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
3088 distinguish between the use of functions written in C and the use of
3089 functions written in Emacs Lisp.  The difference is irrelevant.  I
3090 mention the distinction only because it is interesting to know.  Indeed,
3091 unless you investigate, you won't know whether an already-written
3092 function is written in Emacs Lisp or C.
3094 @node defun, Install, Primitive Functions, Writing Defuns
3095 @comment  node-name,  next,  previous,  up
3096 @section The @code{defun} Special Form
3097 @findex defun
3098 @cindex Special form of @code{defun}
3100 @cindex @samp{function definition} defined
3101 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
3102 it that tells the computer what to do when the function is called.
3103 This code is called the @dfn{function definition} and is created by
3104 evaluating a Lisp expression that starts with the symbol @code{defun}
3105 (which is an abbreviation for @emph{define function}).  Because
3106 @code{defun} does not evaluate its arguments in the usual way, it is
3107 called a @dfn{special form}.
3109 In subsequent sections, we will look at function definitions from the
3110 Emacs source code, such as @code{mark-whole-buffer}.  In this section,
3111 we will describe a simple function definition so you can see how it
3112 looks.  This function definition uses arithmetic because it makes for a
3113 simple example.  Some people dislike examples using arithmetic; however,
3114 if you are such a person, do not despair.  Hardly any of the code we
3115 will study in the remainder of this introduction involves arithmetic or
3116 mathematics.  The examples mostly involve text in one way or another.
3118 A function definition has up to five parts following the word
3119 @code{defun}:
3121 @enumerate
3122 @item
3123 The name of the symbol to which the function definition should be
3124 attached.
3126 @item
3127 A list of the arguments that will be passed to the function.  If no
3128 arguments will be passed to the function, this is an empty list,
3129 @code{()}.
3131 @item
3132 Documentation describing the function.  (Technically optional, but
3133 strongly recommended.)
3135 @item
3136 Optionally, an expression to make the function interactive so you can
3137 use it by typing @kbd{M-x} and then the name of the function; or by
3138 typing an appropriate key or keychord.
3140 @cindex @samp{body} defined
3141 @item
3142 The code that instructs the computer what to do: the @dfn{body} of the
3143 function definition.
3144 @end enumerate
3146 It is helpful to think of the five parts of a function definition as
3147 being organized in a template, with slots for each part:
3149 @smallexample
3150 @group
3151 (defun @var{function-name} (@var{arguments}@dots{})
3152   "@var{optional-documentation}@dots{}"
3153   (interactive @var{argument-passing-info})     ; @r{optional}
3154   @var{body}@dots{})
3155 @end group
3156 @end smallexample
3158 As an example, here is the code for a function that multiplies its
3159 argument by 7.  (This example is not interactive.  @xref{Interactive,
3160 , Making a Function Interactive}, for that information.)
3162 @smallexample
3163 @group
3164 (defun multiply-by-seven (number)
3165   "Multiply NUMBER by seven."
3166   (* 7 number))
3167 @end group
3168 @end smallexample
3170 This definition begins with a parenthesis and the symbol @code{defun},
3171 followed by the name of the function.
3173 @cindex @samp{argument list} defined
3174 The name of the function is followed by a list that contains the
3175 arguments that will be passed to the function.  This list is called
3176 the @dfn{argument list}.  In this example, the list has only one
3177 element, the symbol, @code{number}.  When the function is used, the
3178 symbol will be bound to the value that is used as the argument to the
3179 function.
3181 Instead of choosing the word @code{number} for the name of the argument,
3182 I could have picked any other name.  For example, I could have chosen
3183 the word @code{multiplicand}.  I picked the word `number' because it
3184 tells what kind of value is intended for this slot; but I could just as
3185 well have chosen the word `multiplicand' to indicate the role that the
3186 value placed in this slot will play in the workings of the function.  I
3187 could have called it @code{foogle}, but that would have been a bad
3188 choice because it would not tell humans what it means.  The choice of
3189 name is up to the programmer and should be chosen to make the meaning of
3190 the function clear.
3192 Indeed, you can choose any name you wish for a symbol in an argument
3193 list, even the name of a symbol used in some other function: the name
3194 you use in an argument list is private to that particular definition.
3195 In that definition, the name refers to a different entity than any use
3196 of the same name outside the function definition.  Suppose you have a
3197 nick-name `Shorty' in your family; when your family members refer to
3198 `Shorty', they mean you.  But outside your family, in a movie, for
3199 example, the name `Shorty' refers to someone else.  Because a name in an
3200 argument list is private to the function definition, you can change the
3201 value of such a symbol inside the body of a function without changing
3202 its value outside the function.  The effect is similar to that produced
3203 by a @code{let} expression.  (@xref{let, , @code{let}}.)
3205 @ignore
3206 Note also that we discuss the word `number' in two different ways: as a
3207 symbol that appears in the code, and as the name of something that will
3208 be replaced by a something else during the evaluation of the function.
3209 In the first case, @code{number} is a symbol, not a number; it happens
3210 that within the function, it is a variable who value is the number in
3211 question, but our primary interest in it is as a symbol.  On the other
3212 hand, when we are talking about the function, our interest is that we
3213 will substitute a number for the word @var{number}.  To keep this
3214 distinction clear, we use different typography for the two
3215 circumstances.  When we talk about this function, or about how it works,
3216 we refer to this number by writing @var{number}.  In the function
3217 itself, we refer to it by writing @code{number}.
3218 @end ignore
3220 The argument list is followed by the documentation string that
3221 describes the function.  This is what you see when you type
3222 @w{@kbd{C-h f}} and the name of a function.  Incidentally, when you
3223 write a documentation string like this, you should make the first line
3224 a complete sentence since some commands, such as @code{apropos}, print
3225 only the first line of a multi-line documentation string.  Also, you
3226 should not indent the second line of a documentation string, if you
3227 have one, because that looks odd when you use @kbd{C-h f}
3228 (@code{describe-function}).  The documentation string is optional, but
3229 it is so useful, it should be included in almost every function you
3230 write.
3232 @findex * @r{(multiplication)}
3233 The third line of the example consists of the body of the function
3234 definition.  (Most functions' definitions, of course, are longer than
3235 this.)  In this function, the body is the list, @code{(* 7 number)}, which
3236 says to multiply the value of @var{number} by 7.  (In Emacs Lisp,
3237 @code{*} is the function for multiplication, just as @code{+} is the
3238 function for addition.)
3240 When you use the @code{multiply-by-seven} function, the argument
3241 @code{number} evaluates to the actual number you want used.  Here is an
3242 example that shows how @code{multiply-by-seven} is used; but don't try
3243 to evaluate this yet!
3245 @smallexample
3246 (multiply-by-seven 3)
3247 @end smallexample
3249 @noindent
3250 The symbol @code{number}, specified in the function definition in the
3251 next section, is given or ``bound to'' the value 3 in the actual use of
3252 the function.  Note that although @code{number} was inside parentheses
3253 in the function definition, the argument passed to the
3254 @code{multiply-by-seven} function is not in parentheses.  The
3255 parentheses are written in the function definition so the computer can
3256 figure out where the argument list ends and the rest of the function
3257 definition begins.
3259 If you evaluate this example, you are likely to get an error message.
3260 (Go ahead, try it!)  This is because we have written the function
3261 definition, but not yet told the computer about the definition---we have
3262 not yet installed (or `loaded') the function definition in Emacs.
3263 Installing a function is the process that tells the Lisp interpreter the
3264 definition of the function.  Installation is described in the next
3265 section.
3267 @node Install, Interactive, defun, Writing Defuns
3268 @comment  node-name,  next,  previous,  up
3269 @section Install a Function Definition
3270 @cindex Install a Function Definition
3271 @cindex Definition installation
3272 @cindex Function definition installation
3274 If you are reading this inside of Info in Emacs, you can try out the
3275 @code{multiply-by-seven} function by first evaluating the function
3276 definition and then evaluating @code{(multiply-by-seven 3)}.  A copy of
3277 the function definition follows.  Place the cursor after the last
3278 parenthesis of the function definition and type @kbd{C-x C-e}.  When you
3279 do this, @code{multiply-by-seven} will appear in the echo area.  (What
3280 this means is that when a function definition is evaluated, the value it
3281 returns is the name of the defined function.)  At the same time, this
3282 action installs the function definition.
3284 @smallexample
3285 @group
3286 (defun multiply-by-seven (number)
3287   "Multiply NUMBER by seven."
3288   (* 7 number))
3289 @end group
3290 @end smallexample
3292 @noindent
3293 By evaluating this @code{defun}, you have just installed
3294 @code{multiply-by-seven} in Emacs.  The function is now just as much a
3295 part of Emacs as @code{forward-word} or any other editing function you
3296 use.  (@code{multiply-by-seven} will stay installed until you quit
3297 Emacs.  To reload code automatically whenever you start Emacs, see
3298 @ref{Permanent Installation, , Installing Code Permanently}.)
3300 @menu
3301 * Effect of installation::
3302 * Change a defun::              How to change a function definition.
3303 @end menu
3305 @node Effect of installation, Change a defun, Install, Install
3306 @ifnottex
3307 @unnumberedsubsec The effect of installation
3308 @end ifnottex
3310 You can see the effect of installing @code{multiply-by-seven} by
3311 evaluating the following sample.  Place the cursor after the following
3312 expression and type @kbd{C-x C-e}.  The number 21 will appear in the
3313 echo area.
3315 @smallexample
3316 (multiply-by-seven 3)
3317 @end smallexample
3319 If you wish, you can read the documentation for the function by typing
3320 @kbd{C-h f} (@code{describe-function}) and then the name of the
3321 function, @code{multiply-by-seven}.  When you do this, a
3322 @file{*Help*} window will appear on your screen that says:
3324 @smallexample
3325 @group
3326 multiply-by-seven is a Lisp function.
3327 (multiply-by-seven NUMBER)
3329 Multiply NUMBER by seven.
3330 @end group
3331 @end smallexample
3333 @noindent
3334 (To return to a single window on your screen, type @kbd{C-x 1}.)
3336 @node Change a defun,  , Effect of installation, Install
3337 @comment  node-name,  next,  previous,  up
3338 @subsection Change a Function Definition
3339 @cindex Changing a function definition
3340 @cindex Function definition, how to change
3341 @cindex Definition, how to change
3343 If you want to change the code in @code{multiply-by-seven}, just rewrite
3344 it.  To install the new version in place of the old one, evaluate the
3345 function definition again.  This is how you modify code in Emacs.  It is
3346 very simple.
3348 As an example, you can change the @code{multiply-by-seven} function to
3349 add the number to itself seven times instead of multiplying the number
3350 by seven.  It produces the same answer, but by a different path.  At
3351 the same time, we will add a comment to the code; a comment is text
3352 that the Lisp interpreter ignores, but that a human reader may find
3353 useful or enlightening.  The comment is that this is the ``second
3354 version''.
3356 @smallexample
3357 @group
3358 (defun multiply-by-seven (number)       ; @r{Second version.}
3359   "Multiply NUMBER by seven."
3360   (+ number number number number number number number))
3361 @end group
3362 @end smallexample
3364 @cindex Comments in Lisp code
3365 The comment follows a semicolon, @samp{;}.  In Lisp, everything on a
3366 line that follows a semicolon is a comment.  The end of the line is the
3367 end of the comment.  To stretch a comment over two or more lines, begin
3368 each line with a semicolon.
3370 @xref{Beginning a .emacs File, , Beginning a @file{.emacs}
3371 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
3372 Reference Manual}, for more about comments.
3374 You can install this version of the @code{multiply-by-seven} function by
3375 evaluating it in the same way you evaluated the first function: place
3376 the cursor after the last parenthesis and type @kbd{C-x C-e}.
3378 In summary, this is how you write code in Emacs Lisp: you write a
3379 function; install it; test it; and then make fixes or enhancements and
3380 install it again.
3382 @node Interactive, Interactive Options, Install, Writing Defuns
3383 @comment  node-name,  next,  previous,  up
3384 @section Make a Function Interactive
3385 @cindex Interactive functions
3386 @findex interactive
3388 You make a function interactive by placing a list that begins with
3389 the special form @code{interactive} immediately after the
3390 documentation.  A user can invoke an interactive function by typing
3391 @kbd{M-x} and then the name of the function; or by typing the keys to
3392 which it is bound, for example, by typing @kbd{C-n} for
3393 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
3395 Interestingly, when you call an interactive function interactively,
3396 the value returned is not automatically displayed in the echo area.
3397 This is because you often call an interactive function for its side
3398 effects, such as moving forward by a word or line, and not for the
3399 value returned.  If the returned value were displayed in the echo area
3400 each time you typed a key, it would be very distracting.
3402 @menu
3403 * Interactive multiply-by-seven::  An overview.
3404 * multiply-by-seven in detail::    The interactive version.
3405 @end menu
3407 @node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
3408 @ifnottex
3409 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
3410 @end ifnottex
3412 Both the use of the special form @code{interactive} and one way to
3413 display a value in the echo area can be illustrated by creating an
3414 interactive version of @code{multiply-by-seven}.
3416 @need 1250
3417 Here is the code:
3419 @smallexample
3420 @group
3421 (defun multiply-by-seven (number)       ; @r{Interactive version.}
3422   "Multiply NUMBER by seven."
3423   (interactive "p")
3424   (message "The result is %d" (* 7 number)))
3425 @end group
3426 @end smallexample
3428 @noindent
3429 You can install this code by placing your cursor after it and typing
3430 @kbd{C-x C-e}.  The name of the function will appear in your echo area.
3431 Then, you can use this code by typing @kbd{C-u} and a number and then
3432 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}.  The phrase
3433 @samp{The result is @dots{}} followed by the product will appear in the
3434 echo area.
3436 Speaking more generally, you invoke a function like this in either of two
3437 ways:
3439 @enumerate
3440 @item
3441 By typing a prefix argument that contains the number to be passed, and
3442 then typing @kbd{M-x} and the name of the function, as with
3443 @kbd{C-u 3 M-x forward-sentence}; or,
3445 @item
3446 By typing whatever key or keychord the function is bound to, as with
3447 @kbd{C-u 3 M-e}.
3448 @end enumerate
3450 @noindent
3451 Both the examples just mentioned work identically to move point forward
3452 three sentences.  (Since @code{multiply-by-seven} is not bound to a key,
3453 it could not be used as an example of key binding.)
3455 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
3456 to a key.)
3458 A prefix argument is passed to an interactive function by typing the
3459 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
3460 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
3461 type @kbd{C-u} without a number, it defaults to 4).
3463 @node multiply-by-seven in detail,  , Interactive multiply-by-seven, Interactive
3464 @comment  node-name,  next,  previous,  up
3465 @subsection An Interactive @code{multiply-by-seven}
3467 Let's look at the use of the special form @code{interactive} and then at
3468 the function @code{message} in the interactive version of
3469 @code{multiply-by-seven}.  You will recall that the function definition
3470 looks like this:
3472 @smallexample
3473 @group
3474 (defun multiply-by-seven (number)       ; @r{Interactive version.}
3475   "Multiply NUMBER by seven."
3476   (interactive "p")
3477   (message "The result is %d" (* 7 number)))
3478 @end group
3479 @end smallexample
3481 In this function, the expression, @code{(interactive "p")}, is a list of
3482 two elements.  The @code{"p"} tells Emacs to pass the prefix argument to
3483 the function and use its value for the argument of the function.
3485 @need 1000
3486 The argument will be a number.  This means that the symbol
3487 @code{number} will be bound to a number in the line:
3489 @smallexample
3490 (message "The result is %d" (* 7 number))
3491 @end smallexample
3493 @need 1250
3494 @noindent
3495 For example, if your prefix argument is 5, the Lisp interpreter will
3496 evaluate the line as if it were:
3498 @smallexample
3499 (message "The result is %d" (* 7 5))
3500 @end smallexample
3502 @noindent
3503 (If you are reading this in GNU Emacs, you can evaluate this expression
3504 yourself.)  First, the interpreter will evaluate the inner list, which
3505 is @code{(* 7 5)}.  This returns a value of 35.  Next, it
3506 will evaluate the outer list, passing the values of the second and
3507 subsequent elements of the list to the function @code{message}.
3509 As we have seen, @code{message} is an Emacs Lisp function especially
3510 designed for sending a one line message to a user.  (@xref{message, ,
3511 The @code{message} function}.)  In summary, the @code{message}
3512 function prints its first argument in the echo area as is, except for
3513 occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
3514 which we have not mentioned).  When it sees a control sequence, the
3515 function looks to the second or subsequent arguments and prints the
3516 value of the argument in the location in the string where the control
3517 sequence is located.
3519 In the interactive @code{multiply-by-seven} function, the control string
3520 is @samp{%d}, which requires a number, and the value returned by
3521 evaluating @code{(* 7 5)} is the number 35.  Consequently, the number 35
3522 is printed in place of the @samp{%d} and the message is @samp{The result
3523 is 35}.
3525 (Note that when you call the function @code{multiply-by-seven}, the
3526 message is printed without quotes, but when you call @code{message}, the
3527 text is printed in double quotes.  This is because the value returned by
3528 @code{message} is what appears in the echo area when you evaluate an
3529 expression whose first element is @code{message}; but when embedded in a
3530 function, @code{message} prints the text as a side effect without
3531 quotes.)
3533 @node Interactive Options, Permanent Installation, Interactive, Writing Defuns
3534 @comment  node-name,  next,  previous,  up
3535 @section Different Options for @code{interactive}
3536 @cindex Options for @code{interactive}
3537 @cindex Interactive options
3539 In the example, @code{multiply-by-seven} used @code{"p"} as the
3540 argument to @code{interactive}.  This argument told Emacs to interpret
3541 your typing either @kbd{C-u} followed by a number or @key{META}
3542 followed by a number as a command to pass that number to the function
3543 as its argument.  Emacs has more than twenty characters predefined for
3544 use with @code{interactive}.  In almost every case, one of these
3545 options will enable you to pass the right information interactively to
3546 a function.  (@xref{Interactive Codes, , Code Characters for
3547 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
3549 @need 1250
3550 Consider the function @code{zap-to-char}.  Its interactive expression
3553 @smallexample
3554 (interactive "p\ncZap to char: ")
3555 @end smallexample
3557 The first part of the argument to @code{interactive} is @samp{p}, with
3558 which you are already familiar.  This argument tells Emacs to
3559 interpret a `prefix', as a number to be passed to the function.  You
3560 can specify a prefix either by typing @kbd{C-u} followed by a number
3561 or by typing @key{META} followed by a number.  The prefix is the
3562 number of specified characters.  Thus, if your prefix is three and the
3563 specified character is @samp{x}, then you will delete all the text up
3564 to and including the third next @samp{x}.  If you do not set a prefix,
3565 then you delete all the text up to and including the specified
3566 character, but no more.
3568 The @samp{c} tells the function the name of the character to which to delete.
3570 More formally, a function with two or more arguments can have
3571 information passed to each argument by adding parts to the string that
3572 follows @code{interactive}.  When you do this, the information is
3573 passed to each argument in the same order it is specified in the
3574 @code{interactive} list.  In the string, each part is separated from
3575 the next part by a @samp{\n}, which is a newline.  For example, you
3576 can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
3577 This causes Emacs to pass the value of the prefix argument (if there
3578 is one) and the character.
3580 In this case, the function definition looks like the following, where
3581 @code{arg} and @code{char} are the symbols to which @code{interactive}
3582 binds the prefix argument and the specified character:
3584 @smallexample
3585 @group
3586 (defun @var{name-of-function} (arg char)
3587   "@var{documentation}@dots{}"
3588   (interactive "p\ncZap to char: ")
3589   @var{body-of-function}@dots{})
3590 @end group
3591 @end smallexample
3593 @noindent
3594 (The space after the colon in the prompt makes it look better when you
3595 are prompted.  @xref{copy-to-buffer, , The Definition of
3596 @code{copy-to-buffer}}, for an example.)
3598 When a function does not take arguments, @code{interactive} does not
3599 require any.  Such a function contains the simple expression
3600 @code{(interactive)}.  The @code{mark-whole-buffer} function is like
3601 this.
3603 Alternatively, if the special letter-codes are not right for your
3604 application, you can pass your own arguments to @code{interactive} as
3605 a list.
3607 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
3608 for an example.  @xref{Using Interactive, , Using @code{Interactive},
3609 elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
3610 explanation about this technique.
3612 @node Permanent Installation, let, Interactive Options, Writing Defuns
3613 @comment  node-name,  next,  previous,  up
3614 @section Install Code Permanently
3615 @cindex Install code permanently
3616 @cindex Permanent code installation
3617 @cindex Code installation
3619 When you install a function definition by evaluating it, it will stay
3620 installed until you quit Emacs.  The next time you start a new session
3621 of Emacs, the function will not be installed unless you evaluate the
3622 function definition again.
3624 At some point, you may want to have code installed automatically
3625 whenever you start a new session of Emacs.  There are several ways of
3626 doing this:
3628 @itemize @bullet
3629 @item
3630 If you have code that is just for yourself, you can put the code for the
3631 function definition in your @file{.emacs} initialization file.  When you
3632 start Emacs, your @file{.emacs} file is automatically evaluated and all
3633 the function definitions within it are installed.
3634 @xref{Emacs Initialization, , Your @file{.emacs} File}.
3636 @item
3637 Alternatively, you can put the function definitions that you want
3638 installed in one or more files of their own and use the @code{load}
3639 function to cause Emacs to evaluate and thereby install each of the
3640 functions in the files.
3641 @xref{Loading Files, , Loading Files}.
3643 @item
3644 Thirdly, if you have code that your whole site will use, it is usual
3645 to put it in a file called @file{site-init.el} that is loaded when
3646 Emacs is built.  This makes the code available to everyone who uses
3647 your machine.  (See the @file{INSTALL} file that is part of the Emacs
3648 distribution.)
3649 @end itemize
3651 Finally, if you have code that everyone who uses Emacs may want, you
3652 can post it on a computer network or send a copy to the Free Software
3653 Foundation.  (When you do this, please license the code and its
3654 documentation under a license that permits other people to run, copy,
3655 study, modify, and redistribute the code and which protects you from
3656 having your work taken from you.)  If you send a copy of your code to
3657 the Free Software Foundation, and properly protect yourself and
3658 others, it may be included in the next release of Emacs.  In large
3659 part, this is how Emacs has grown over the past years, by donations.
3661 @node let, if, Permanent Installation, Writing Defuns
3662 @comment  node-name,  next,  previous,  up
3663 @section @code{let}
3664 @findex let
3666 The @code{let} expression is a special form in Lisp that you will need
3667 to use in most function definitions.
3669 @code{let} is used to attach or bind a symbol to a value in such a way
3670 that the Lisp interpreter will not confuse the variable with a
3671 variable of the same name that is not part of the function.
3673 To understand why the @code{let} special form is necessary, consider
3674 the situation in which you own a home that you generally refer to as
3675 `the house', as in the sentence, ``The house needs painting.''  If you
3676 are visiting a friend and your host refers to `the house', he is
3677 likely to be referring to @emph{his} house, not yours, that is, to a
3678 different house.
3680 If your friend is referring to his house and you think he is referring
3681 to your house, you may be in for some confusion.  The same thing could
3682 happen in Lisp if a variable that is used inside of one function has
3683 the same name as a variable that is used inside of another function,
3684 and the two are not intended to refer to the same value.  The
3685 @code{let} special form prevents this kind of confusion.
3687 @menu
3688 * Prevent confusion::
3689 * Parts of let Expression::
3690 * Sample let Expression::
3691 * Uninitialized let Variables::
3692 @end menu
3694 @node Prevent confusion, Parts of let Expression, let, let
3695 @ifnottex
3696 @unnumberedsubsec @code{let} Prevents Confusion
3697 @end ifnottex
3699 @cindex @samp{local variable} defined
3700 @cindex @samp{variable, local}, defined
3701 The @code{let} special form prevents confusion.  @code{let} creates a
3702 name for a @dfn{local variable} that overshadows any use of the same
3703 name outside the @code{let} expression.  This is like understanding
3704 that whenever your host refers to `the house', he means his house, not
3705 yours.  (Symbols used in argument lists work the same way.
3706 @xref{defun, , The @code{defun} Special Form}.)
3708 Local variables created by a @code{let} expression retain their value
3709 @emph{only} within the @code{let} expression itself (and within
3710 expressions called within the @code{let} expression); the local
3711 variables have no effect outside the @code{let} expression.
3713 Another way to think about @code{let} is that it is like a @code{setq}
3714 that is temporary and local.  The values set by @code{let} are
3715 automatically undone when the @code{let} is finished.  The setting
3716 only affects expressions that are inside the bounds of the @code{let}
3717 expression.  In computer science jargon, we would say ``the binding of
3718 a symbol is visible only in functions called in the @code{let} form;
3719 in Emacs Lisp, scoping is dynamic, not lexical.''
3721 @code{let} can create more than one variable at once.  Also,
3722 @code{let} gives each variable it creates an initial value, either a
3723 value specified by you, or @code{nil}.  (In the jargon, this is called
3724 `binding the variable to the value'.)  After @code{let} has created
3725 and bound the variables, it executes the code in the body of the
3726 @code{let}, and returns the value of the last expression in the body,
3727 as the value of the whole @code{let} expression.  (`Execute' is a jargon
3728 term that means to evaluate a list; it comes from the use of the word
3729 meaning `to give practical effect to' (@cite{Oxford English
3730 Dictionary}).  Since you evaluate an expression to perform an action,
3731 `execute' has evolved as a synonym to `evaluate'.)
3733 @node Parts of let Expression, Sample let Expression, Prevent confusion, let
3734 @comment  node-name,  next,  previous,  up
3735 @subsection The Parts of a @code{let} Expression
3736 @cindex @code{let} expression, parts of
3737 @cindex Parts of @code{let} expression
3739 @cindex @samp{varlist} defined
3740 A @code{let} expression is a list of three parts.  The first part is
3741 the symbol @code{let}.  The second part is a list, called a
3742 @dfn{varlist}, each element of which is either a symbol by itself or a
3743 two-element list, the first element of which is a symbol.  The third
3744 part of the @code{let} expression is the body of the @code{let}.  The
3745 body usually consists of one or more lists.
3747 @need 800
3748 A template for a @code{let} expression looks like this:
3750 @smallexample
3751 (let @var{varlist} @var{body}@dots{})
3752 @end smallexample
3754 @noindent
3755 The symbols in the varlist are the variables that are given initial
3756 values by the @code{let} special form.  Symbols by themselves are given
3757 the initial value of @code{nil}; and each symbol that is the first
3758 element of a two-element list is bound to the value that is returned
3759 when the Lisp interpreter evaluates the second element.
3761 Thus, a varlist might look like this: @code{(thread (needles 3))}.  In
3762 this case, in a @code{let} expression, Emacs binds the symbol
3763 @code{thread} to an initial value of @code{nil}, and binds the symbol
3764 @code{needles} to an initial value of 3.
3766 When you write a @code{let} expression, what you do is put the
3767 appropriate expressions in the slots of the @code{let} expression
3768 template.
3770 If the varlist is composed of two-element lists, as is often the case,
3771 the template for the @code{let} expression looks like this:
3773 @smallexample
3774 @group
3775 (let ((@var{variable} @var{value})
3776       (@var{variable} @var{value})
3777       @dots{})
3778   @var{body}@dots{})
3779 @end group
3780 @end smallexample
3782 @node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let
3783 @comment  node-name,  next,  previous,  up
3784 @subsection Sample @code{let} Expression
3785 @cindex Sample @code{let} expression
3786 @cindex @code{let} expression sample
3788 The following expression creates and gives initial values
3789 to the two variables @code{zebra} and @code{tiger}.  The body of the
3790 @code{let} expression is a list which calls the @code{message} function.
3792 @smallexample
3793 @group
3794 (let ((zebra 'stripes)
3795       (tiger 'fierce))
3796   (message "One kind of animal has %s and another is %s."
3797            zebra tiger))
3798 @end group
3799 @end smallexample
3801 Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}.
3803 The two variables are @code{zebra} and @code{tiger}.  Each variable is
3804 the first element of a two-element list and each value is the second
3805 element of its two-element list.  In the varlist, Emacs binds the
3806 variable @code{zebra} to the value @code{stripes}@footnote{According
3807 to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
3808 become impossibly dangerous as they grow older'' but the claim here is
3809 that they do not become fierce like a tiger.  (1997, W. W. Norton and
3810 Co., ISBN 0-393-03894-2, page 171)}, and binds the
3811 variable @code{tiger} to the value @code{fierce}.  In this example,
3812 both values are symbols preceded by a quote.  The values could just as
3813 well have been another list or a string.  The body of the @code{let}
3814 follows after the list holding the variables.  In this example, the
3815 body is a list that uses the @code{message} function to print a string
3816 in the echo area.
3818 @need 1500
3819 You may evaluate the example in the usual fashion, by placing the
3820 cursor after the last parenthesis and typing @kbd{C-x C-e}.  When you do
3821 this, the following will appear in the echo area:
3823 @smallexample
3824 "One kind of animal has stripes and another is fierce."
3825 @end smallexample
3827 As we have seen before, the @code{message} function prints its first
3828 argument, except for @samp{%s}.  In this example, the value of the variable
3829 @code{zebra} is printed at the location of the first @samp{%s} and the
3830 value of the variable @code{tiger} is printed at the location of the
3831 second @samp{%s}.
3833 @node Uninitialized let Variables,  , Sample let Expression, let
3834 @comment  node-name,  next,  previous,  up
3835 @subsection Uninitialized Variables in a @code{let} Statement
3836 @cindex Uninitialized @code{let} variables
3837 @cindex @code{let} variables uninitialized
3839 If you do not bind the variables in a @code{let} statement to specific
3840 initial values, they will automatically be bound to an initial value of
3841 @code{nil}, as in the following expression:
3843 @smallexample
3844 @group
3845 (let ((birch 3)
3846       pine
3847       fir
3848       (oak 'some))
3849   (message
3850    "Here are %d variables with %s, %s, and %s value."
3851    birch pine fir oak))
3852 @end group
3853 @end smallexample
3855 @noindent
3856 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
3858 @need 1250
3859 If you evaluate this expression in the usual way, the following will
3860 appear in your echo area:
3862 @smallexample
3863 "Here are 3 variables with nil, nil, and some value."
3864 @end smallexample
3866 @noindent
3867 In this example, Emacs binds the symbol @code{birch} to the number 3,
3868 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
3869 the symbol @code{oak} to the value @code{some}.
3871 Note that in the first part of the @code{let}, the variables @code{pine}
3872 and @code{fir} stand alone as atoms that are not surrounded by
3873 parentheses; this is because they are being bound to @code{nil}, the
3874 empty list.  But @code{oak} is bound to @code{some} and so is a part of
3875 the list @code{(oak 'some)}.  Similarly, @code{birch} is bound to the
3876 number 3 and so is in a list with that number.  (Since a number
3877 evaluates to itself, the number does not need to be quoted.  Also, the
3878 number is printed in the message using a @samp{%d} rather than a
3879 @samp{%s}.)  The four variables as a group are put into a list to
3880 delimit them from the body of the @code{let}.
3882 @node if, else, let, Writing Defuns
3883 @comment  node-name,  next,  previous,  up
3884 @section The @code{if} Special Form
3885 @findex if
3886 @cindex Conditional with @code{if}
3888 A third special form, in addition to @code{defun} and @code{let}, is the
3889 conditional @code{if}.  This form is used to instruct the computer to
3890 make decisions.  You can write function definitions without using
3891 @code{if}, but it is used often enough, and is important enough, to be
3892 included here.  It is used, for example, in the code for the
3893 function @code{beginning-of-buffer}.
3895 The basic idea behind an @code{if}, is that ``@emph{if} a test is true,
3896 @emph{then} an expression is evaluated.''  If the test is not true, the
3897 expression is not evaluated.  For example, you might make a decision
3898 such as, ``if it is warm and sunny, then go to the beach!''
3900 @menu
3901 * if in more detail::
3902 * type-of-animal in detail::    An example of an @code{if} expression.
3903 @end menu
3905 @node if in more detail, type-of-animal in detail, if, if
3906 @ifnottex
3907 @unnumberedsubsec @code{if} in more detail
3908 @end ifnottex
3910 @cindex @samp{if-part} defined
3911 @cindex @samp{then-part} defined
3912 An @code{if} expression written in Lisp does not use the word `then';
3913 the test and the action are the second and third elements of the list
3914 whose first element is @code{if}.  Nonetheless, the test part of an
3915 @code{if} expression is often called the @dfn{if-part} and the second
3916 argument is often called the @dfn{then-part}.
3918 Also, when an @code{if} expression is written, the true-or-false-test
3919 is usually written on the same line as the symbol @code{if}, but the
3920 action to carry out if the test is true, the ``then-part'', is written
3921 on the second and subsequent lines.  This makes the @code{if}
3922 expression easier to read.
3924 @smallexample
3925 @group
3926 (if @var{true-or-false-test}
3927     @var{action-to-carry-out-if-test-is-true})
3928 @end group
3929 @end smallexample
3931 @noindent
3932 The true-or-false-test will be an expression that
3933 is evaluated by the Lisp interpreter.
3935 Here is an example that you can evaluate in the usual manner.  The test
3936 is whether the number 5 is greater than the number 4.  Since it is, the
3937 message @samp{5 is greater than 4!} will be printed.
3939 @smallexample
3940 @group
3941 (if (> 5 4)                             ; @r{if-part}
3942     (message "5 is greater than 4!"))   ; @r{then-part}
3943 @end group
3944 @end smallexample
3946 @noindent
3947 (The function @code{>} tests whether its first argument is greater than
3948 its second argument and returns true if it is.)
3949 @findex > (greater than)
3951 Of course, in actual use, the test in an @code{if} expression will not
3952 be fixed for all time as it is by the expression @code{(> 5 4)}.
3953 Instead, at least one of the variables used in the test will be bound to
3954 a value that is not known ahead of time.  (If the value were known ahead
3955 of time, we would not need to run the test!)
3957 For example, the value may be bound to an argument of a function
3958 definition.  In the following function definition, the character of the
3959 animal is a value that is passed to the function.  If the value bound to
3960 @code{characteristic} is @code{fierce}, then the message, @samp{It's a
3961 tiger!} will be printed; otherwise, @code{nil} will be returned.
3963 @smallexample
3964 @group
3965 (defun type-of-animal (characteristic)
3966   "Print message in echo area depending on CHARACTERISTIC.
3967 If the CHARACTERISTIC is the symbol `fierce',
3968 then warn of a tiger."
3969   (if (equal characteristic 'fierce)
3970       (message "It's a tiger!")))
3971 @end group
3972 @end smallexample
3974 @need 1500
3975 @noindent
3976 If you are reading this inside of GNU Emacs, you can evaluate the
3977 function definition in the usual way to install it in Emacs, and then you
3978 can evaluate the following two expressions to see the results:
3980 @smallexample
3981 @group
3982 (type-of-animal 'fierce)
3984 (type-of-animal 'zebra)
3986 @end group
3987 @end smallexample
3989 @c Following sentences rewritten to prevent overfull hbox.
3990 @noindent
3991 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
3992 following message printed in the echo area: @code{"It's a tiger!"}; and
3993 when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil}
3994 printed in the echo area.
3996 @node type-of-animal in detail,  , if in more detail, if
3997 @comment  node-name,  next,  previous,  up
3998 @subsection The @code{type-of-animal} Function in Detail
4000 Let's look at the @code{type-of-animal} function in detail.
4002 The function definition for @code{type-of-animal} was written by filling
4003 the slots of two templates, one for a function definition as a whole, and
4004 a second for an @code{if} expression.
4006 @need 1250
4007 The template for every function that is not interactive is:
4009 @smallexample
4010 @group
4011 (defun @var{name-of-function} (@var{argument-list})
4012   "@var{documentation}@dots{}"
4013   @var{body}@dots{})
4014 @end group
4015 @end smallexample
4017 @need 800
4018 The parts of the function that match this template look like this:
4020 @smallexample
4021 @group
4022 (defun type-of-animal (characteristic)
4023   "Print message in echo area depending on CHARACTERISTIC.
4024 If the CHARACTERISTIC is the symbol `fierce',
4025 then warn of a tiger."
4026   @var{body: the} @code{if} @var{expression})
4027 @end group
4028 @end smallexample
4030 The name of function is @code{type-of-animal}; it is passed the value
4031 of one argument.  The argument list is followed by a multi-line
4032 documentation string.  The documentation string is included in the
4033 example because it is a good habit to write documentation string for
4034 every function definition.  The body of the function definition
4035 consists of the @code{if} expression.
4037 @need 800
4038 The template for an @code{if} expression looks like this:
4040 @smallexample
4041 @group
4042 (if @var{true-or-false-test}
4043     @var{action-to-carry-out-if-the-test-returns-true})
4044 @end group
4045 @end smallexample
4047 @need 1250
4048 In the @code{type-of-animal} function, the code for the @code{if}
4049 looks like this:
4051 @smallexample
4052 @group
4053 (if (equal characteristic 'fierce)
4054     (message "It's a tiger!")))
4055 @end group
4056 @end smallexample
4058 @need 800
4059 Here, the true-or-false-test is the expression:
4061 @smallexample
4062 (equal characteristic 'fierce)
4063 @end smallexample
4065 @noindent
4066 In Lisp, @code{equal} is a function that determines whether its first
4067 argument is equal to its second argument.  The second argument is the
4068 quoted symbol @code{'fierce} and the first argument is the value of the
4069 symbol @code{characteristic}---in other words, the argument passed to
4070 this function.
4072 In the first exercise of @code{type-of-animal}, the argument
4073 @code{fierce} is passed to @code{type-of-animal}.  Since @code{fierce}
4074 is equal to @code{fierce}, the expression, @code{(equal characteristic
4075 'fierce)}, returns a value of true.  When this happens, the @code{if}
4076 evaluates the second argument or then-part of the @code{if}:
4077 @code{(message "It's tiger!")}.
4079 On the other hand, in the second exercise of @code{type-of-animal}, the
4080 argument @code{zebra} is passed to @code{type-of-animal}.  @code{zebra}
4081 is not equal to @code{fierce}, so the then-part is not evaluated and
4082 @code{nil} is returned by the @code{if} expression.
4084 @node else, Truth & Falsehood, if, Writing Defuns
4085 @comment  node-name,  next,  previous,  up
4086 @section If--then--else Expressions
4087 @cindex Else
4089 An @code{if} expression may have an optional third argument, called
4090 the @dfn{else-part}, for the case when the true-or-false-test returns
4091 false.  When this happens, the second argument or then-part of the
4092 overall @code{if} expression is @emph{not} evaluated, but the third or
4093 else-part @emph{is} evaluated.  You might think of this as the cloudy
4094 day alternative for the decision ``if it is warm and sunny, then go to
4095 the beach, else read a book!''.
4097 The word ``else'' is not written in the Lisp code; the else-part of an
4098 @code{if} expression comes after the then-part.  In the written Lisp, the
4099 else-part is usually written to start on a line of its own and is
4100 indented less than the then-part:
4102 @smallexample
4103 @group
4104 (if @var{true-or-false-test}
4105     @var{action-to-carry-out-if-the-test-returns-true}
4106   @var{action-to-carry-out-if-the-test-returns-false})
4107 @end group
4108 @end smallexample
4110 For example, the following @code{if} expression prints the message @samp{4
4111 is not greater than 5!} when you evaluate it in the usual way:
4113 @smallexample
4114 @group
4115 (if (> 4 5)                               ; @r{if-part}
4116     (message "4 falsely greater than 5!") ; @r{then-part}
4117   (message "4 is not greater than 5!"))   ; @r{else-part}
4118 @end group
4119 @end smallexample
4121 @noindent
4122 Note that the different levels of indentation make it easy to
4123 distinguish the then-part from the else-part.  (GNU Emacs has several
4124 commands that automatically indent @code{if} expressions correctly.
4125 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
4127 We can extend the @code{type-of-animal} function to include an
4128 else-part by simply incorporating an additional part to the @code{if}
4129 expression.
4131 @need 1500
4132 You can see the consequences of doing this if you evaluate the following
4133 version of the @code{type-of-animal} function definition to install it
4134 and then evaluate the two subsequent expressions to pass different
4135 arguments to the function.
4137 @smallexample
4138 @group
4139 (defun type-of-animal (characteristic)  ; @r{Second version.}
4140   "Print message in echo area depending on CHARACTERISTIC.
4141 If the CHARACTERISTIC is the symbol `fierce',
4142 then warn of a tiger;
4143 else say it's not fierce."
4144   (if (equal characteristic 'fierce)
4145       (message "It's a tiger!")
4146     (message "It's not fierce!")))
4147 @end group
4148 @end smallexample
4149 @sp 1
4151 @smallexample
4152 @group
4153 (type-of-animal 'fierce)
4155 (type-of-animal 'zebra)
4157 @end group
4158 @end smallexample
4160 @c Following sentence rewritten to prevent overfull hbox.
4161 @noindent
4162 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
4163 following message printed in the echo area: @code{"It's a tiger!"}; but
4164 when you evaluate @code{(type-of-animal 'zebra)}, you will see
4165 @code{"It's not fierce!"}.
4167 (Of course, if the @var{characteristic} were @code{ferocious}, the
4168 message @code{"It's not fierce!"} would be printed; and it would be
4169 misleading!  When you write code, you need to take into account the
4170 possibility that some such argument will be tested by the @code{if}
4171 and write your program accordingly.)
4173 @node Truth & Falsehood, save-excursion, else, Writing Defuns
4174 @comment  node-name,  next,  previous,  up
4175 @section Truth and Falsehood in Emacs Lisp
4176 @cindex Truth and falsehood in Emacs Lisp
4177 @cindex Falsehood and truth in Emacs Lisp
4178 @findex nil
4180 There is an important aspect to the truth test in an @code{if}
4181 expression.  So far, we have spoken of `true' and `false' as values of
4182 predicates as if they were new kinds of Emacs Lisp objects.  In fact,
4183 `false' is just our old friend @code{nil}.  Anything else---anything
4184 at all---is `true'.
4186 The expression that tests for truth is interpreted as @dfn{true}
4187 if the result of evaluating it is a value that is not @code{nil}.  In
4188 other words, the result of the test is considered true if the value
4189 returned is a number such as 47, a string such as @code{"hello"}, or a
4190 symbol (other than @code{nil}) such as @code{flowers}, or a list (so
4191 long as it is not empty), or even a buffer!
4193 @menu
4194 * nil explained::               @code{nil} has two meanings.
4195 @end menu
4197 @node nil explained,  , Truth & Falsehood, Truth & Falsehood
4198 @ifnottex
4199 @unnumberedsubsec An explanation of @code{nil}
4200 @end ifnottex
4202 Before illustrating a test for truth, we need an explanation of @code{nil}.
4204 In Emacs Lisp, the symbol @code{nil} has two meanings.  First, it means the
4205 empty list.  Second, it means false and is the value returned when a
4206 true-or-false-test tests false.  @code{nil} can be written as an empty
4207 list, @code{()}, or as @code{nil}.  As far as the Lisp interpreter is
4208 concerned, @code{()} and @code{nil} are the same.  Humans, however, tend
4209 to use @code{nil} for false and @code{()} for the empty list.
4211 In Emacs Lisp, any value that is not @code{nil}---is not the empty
4212 list---is considered true.  This means that if an evaluation returns
4213 something that is not an empty list, an @code{if} expression will test
4214 true.  For example, if a number is put in the slot for the test, it
4215 will be evaluated and will return itself, since that is what numbers
4216 do when evaluated.  In this conditional, the @code{if} expression will
4217 test true.  The expression tests false only when @code{nil}, an empty
4218 list, is returned by evaluating the expression.
4220 You can see this by evaluating the two expressions in the following examples.
4222 In the first example, the number 4 is evaluated as the test in the
4223 @code{if} expression and returns itself; consequently, the then-part
4224 of the expression is evaluated and returned: @samp{true} appears in
4225 the echo area.  In the second example, the @code{nil} indicates false;
4226 consequently, the else-part of the expression is evaluated and
4227 returned: @samp{false} appears in the echo area.
4229 @smallexample
4230 @group
4231 (if 4
4232     'true
4233   'false)
4234 @end group
4236 @group
4237 (if nil
4238     'true
4239   'false)
4240 @end group
4241 @end smallexample
4243 @need 1250
4244 Incidentally, if some other useful value is not available for a test that
4245 returns true, then the Lisp interpreter will return the symbol @code{t}
4246 for true.  For example, the expression @code{(> 5 4)} returns @code{t}
4247 when evaluated, as you can see by evaluating it in the usual way:
4249 @smallexample
4250 (> 5 4)
4251 @end smallexample
4253 @need 1250
4254 @noindent
4255 On the other hand, this function returns @code{nil} if the test is false.
4257 @smallexample
4258 (> 4 5)
4259 @end smallexample
4261 @node save-excursion, Review, Truth & Falsehood, Writing Defuns
4262 @comment  node-name,  next,  previous,  up
4263 @section @code{save-excursion}
4264 @findex save-excursion
4265 @cindex Region, what it is
4266 @cindex Preserving point, mark, and buffer
4267 @cindex Point, mark, buffer preservation
4268 @findex point
4269 @findex mark
4271 The @code{save-excursion} function is the fourth and final special form
4272 that we will discuss in this chapter.
4274 In Emacs Lisp programs used for editing, the @code{save-excursion}
4275 function is very common.  It saves the location of point and mark,
4276 executes the body of the function, and then restores point and mark to
4277 their previous positions if their locations were changed.  Its primary
4278 purpose is to keep the user from being surprised and disturbed by
4279 unexpected movement of point or mark.
4281 @menu
4282 * Point and mark::              A review of various locations.
4283 * Template for save-excursion::
4284 @end menu
4286 @node Point and mark, Template for save-excursion, save-excursion, save-excursion
4287 @ifnottex
4288 @unnumberedsubsec Point and Mark
4289 @end ifnottex
4291 Before discussing @code{save-excursion}, however, it may be useful
4292 first to review what point and mark are in GNU Emacs.  @dfn{Point} is
4293 the current location of the cursor.  Wherever the cursor
4294 is, that is point.  More precisely, on terminals where the cursor
4295 appears to be on top of a character, point is immediately before the
4296 character.  In Emacs Lisp, point is an integer.  The first character in
4297 a buffer is number one, the second is number two, and so on.  The
4298 function @code{point} returns the current position of the cursor as a
4299 number.  Each buffer has its own value for point.
4301 The @dfn{mark} is another position in the buffer; its value can be set
4302 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}).  If
4303 a mark has been set, you can use the command @kbd{C-x C-x}
4304 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
4305 and set the mark to be the previous position of point.  In addition, if
4306 you set another mark, the position of the previous mark is saved in the
4307 mark ring.  Many mark positions can be saved this way.  You can jump the
4308 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
4309 times.
4311 The part of the buffer between point and mark is called @dfn{the
4312 region}.  Numerous commands work on the region, including
4313 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
4314 @code{print-region}.
4316 The @code{save-excursion} special form saves the locations of point and
4317 mark and restores those positions after the code within the body of the
4318 special form is evaluated by the Lisp interpreter.  Thus, if point were
4319 in the beginning of a piece of text and some code moved point to the end
4320 of the buffer, the @code{save-excursion} would put point back to where
4321 it was before, after the expressions in the body of the function were
4322 evaluated.
4324 In Emacs, a function frequently moves point as part of its internal
4325 workings even though a user would not expect this.  For example,
4326 @code{count-lines-region} moves point.  To prevent the user from being
4327 bothered by jumps that are both unexpected and (from the user's point of
4328 view) unnecessary, @code{save-excursion} is often used to keep point and
4329 mark in the location expected by the user.  The use of
4330 @code{save-excursion} is good housekeeping.
4332 To make sure the house stays clean, @code{save-excursion} restores the
4333 values of point and mark even if something goes wrong in the code inside
4334 of it (or, to be more precise and to use the proper jargon, ``in case of
4335 abnormal exit'').  This feature is very helpful.
4337 In addition to recording the values of point and mark,
4338 @code{save-excursion} keeps track of the current buffer, and restores
4339 it, too.  This means you can write code that will change the buffer and
4340 have @code{save-excursion} switch you back to the original buffer.
4341 This is how @code{save-excursion} is used in @code{append-to-buffer}.
4342 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
4344 @node Template for save-excursion,  , Point and mark, save-excursion
4345 @comment  node-name,  next,  previous,  up
4346 @subsection Template for a @code{save-excursion} Expression
4348 @need 800
4349 The template for code using @code{save-excursion} is simple:
4351 @smallexample
4352 @group
4353 (save-excursion
4354   @var{body}@dots{})
4355 @end group
4356 @end smallexample
4358 @noindent
4359 The body of the function is one or more expressions that will be
4360 evaluated in sequence by the Lisp interpreter.  If there is more than
4361 one expression in the body, the value of the last one will be returned
4362 as the value of the @code{save-excursion} function.  The other
4363 expressions in the body are evaluated only for their side effects; and
4364 @code{save-excursion} itself is used only for its side effect (which
4365 is restoring the positions of point and mark).
4367 @need 1250
4368 In more detail, the template for a @code{save-excursion} expression
4369 looks like this:
4371 @smallexample
4372 @group
4373 (save-excursion
4374   @var{first-expression-in-body}
4375   @var{second-expression-in-body}
4376   @var{third-expression-in-body}
4377    @dots{}
4378   @var{last-expression-in-body})
4379 @end group
4380 @end smallexample
4382 @noindent
4383 An expression, of course, may be a symbol on its own or a list.
4385 In Emacs Lisp code, a @code{save-excursion} expression often occurs
4386 within the body of a @code{let} expression.  It looks like this:
4388 @smallexample
4389 @group
4390 (let @var{varlist}
4391   (save-excursion
4392     @var{body}@dots{}))
4393 @end group
4394 @end smallexample
4396 @node Review, defun Exercises, save-excursion, Writing Defuns
4397 @comment  node-name,  next,  previous,  up
4398 @section Review
4400 In the last few chapters we have introduced a fair number of functions
4401 and special forms.  Here they are described in brief, along with a few
4402 similar functions that have not been mentioned yet.
4404 @table @code
4405 @item eval-last-sexp
4406 Evaluate the last symbolic expression before the current location of
4407 point.  The value is printed in the echo area unless the function is
4408 invoked with an argument; in that case, the output is printed in the
4409 current buffer.  This command is normally bound to @kbd{C-x C-e}.
4411 @item defun
4412 Define function.  This special form has up to five parts: the name,
4413 a template for the arguments that will be passed to the function,
4414 documentation, an optional interactive declaration, and the body of the
4415 definition.
4417 @need 1250
4418 For example, in an early version of Emacs, the function definition was
4419 as follows.  (It is slightly more complex now that it seeks the first
4420 non-whitespace character rather than the first visible character.)
4422 @smallexample
4423 @group
4424 (defun back-to-indentation ()
4425   "Move point to first visible character on line."
4426   (interactive)
4427   (beginning-of-line 1)
4428   (skip-chars-forward " \t"))
4429 @end group
4430 @end smallexample
4432 @ignore
4433 In GNU Emacs 22,
4435 (defun backward-to-indentation (&optional arg)
4436   "Move backward ARG lines and position at first nonblank character."
4437   (interactive "p")
4438   (forward-line (- (or arg 1)))
4439   (skip-chars-forward " \t"))
4441 (defun back-to-indentation ()
4442   "Move point to the first non-whitespace character on this line."
4443   (interactive)
4444   (beginning-of-line 1)
4445   (skip-syntax-forward " " (line-end-position))
4446   ;; Move back over chars that have whitespace syntax but have the p flag.
4447   (backward-prefix-chars))
4448 @end ignore
4450 @item interactive
4451 Declare to the interpreter that the function can be used
4452 interactively.  This special form may be followed by a string with one
4453 or more parts that pass the information to the arguments of the
4454 function, in sequence.  These parts may also tell the interpreter to
4455 prompt for information.  Parts of the string are separated by
4456 newlines, @samp{\n}.
4458 @need 1000
4459 Common code characters are:
4461 @table @code
4462 @item b
4463 The name of an existing buffer.
4465 @item f
4466 The name of an existing file.
4468 @item p
4469 The numeric prefix argument.  (Note that this `p' is lower case.)
4471 @item r
4472 Point and the mark, as two numeric arguments, smallest first.  This
4473 is the only code letter that specifies two successive arguments
4474 rather than one.
4475 @end table
4477 @xref{Interactive Codes, , Code Characters for @samp{interactive},
4478 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
4479 code characters.
4481 @item let
4482 Declare that a list of variables is for use within the body of the
4483 @code{let} and give them an initial value, either @code{nil} or a
4484 specified value; then evaluate the rest of the expressions in the body
4485 of the @code{let} and return the value of the last one.  Inside the
4486 body of the @code{let}, the Lisp interpreter does not see the values of
4487 the variables of the same names that are bound outside of the
4488 @code{let}.
4490 @need 1250
4491 For example,
4493 @smallexample
4494 @group
4495 (let ((foo (buffer-name))
4496       (bar (buffer-size)))
4497   (message
4498    "This buffer is %s and has %d characters."
4499    foo bar))
4500 @end group
4501 @end smallexample
4503 @item save-excursion
4504 Record the values of point and mark and the current buffer before
4505 evaluating the body of this special form.  Restore the values of point
4506 and mark and buffer afterward.
4508 @need 1250
4509 For example,
4511 @smallexample
4512 @group
4513 (message "We are %d characters into this buffer."
4514          (- (point)
4515             (save-excursion
4516               (goto-char (point-min)) (point))))
4517 @end group
4518 @end smallexample
4520 @item if
4521 Evaluate the first argument to the function; if it is true, evaluate
4522 the second argument; else evaluate the third argument, if there is one.
4524 The @code{if} special form is called a @dfn{conditional}.  There are
4525 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
4526 commonly used.
4528 @need 1250
4529 For example,
4531 @smallexample
4532 @group
4533 (if (= 22 emacs-major-version)
4534     (message "This is version 22 Emacs")
4535   (message "This is not version 22 Emacs"))
4536 @end group
4537 @end smallexample
4539 @need 1250
4540 @item <
4541 @itemx >
4542 @itemx <=
4543 @itemx >=
4544 The @code{<} function tests whether its first argument is smaller than
4545 its second argument.  A corresponding function, @code{>}, tests whether
4546 the first argument is greater than the second.  Likewise, @code{<=}
4547 tests whether the first argument is less than or equal to the second and
4548 @code{>=} tests whether the first argument is greater than or equal to
4549 the second.  In all cases, both arguments must be numbers or markers
4550 (markers indicate positions in buffers).
4552 @need 800
4553 @item =
4554 The @code{=} function tests whether two arguments, both numbers or
4555 markers, are equal.
4557 @need 1250
4558 @item equal
4559 @itemx eq
4560 Test whether two objects are the same.  @code{equal} uses one meaning
4561 of the word `same' and @code{eq} uses another:  @code{equal} returns
4562 true if the two objects have a similar structure and contents, such as
4563 two copies of the same book.  On the other hand, @code{eq}, returns
4564 true if both arguments are actually the same object.
4565 @findex equal
4566 @findex eq
4568 @need 1250
4569 @item string<
4570 @itemx string-lessp
4571 @itemx string=
4572 @itemx string-equal
4573 The @code{string-lessp} function tests whether its first argument is
4574 smaller than the second argument.  A shorter, alternative name for the
4575 same function (a @code{defalias}) is @code{string<}.
4577 The arguments to @code{string-lessp} must be strings or symbols; the
4578 ordering is lexicographic, so case is significant.  The print names of
4579 symbols are used instead of the symbols themselves.
4581 @cindex @samp{empty string} defined
4582 An empty string, @samp{""}, a string with no characters in it, is
4583 smaller than any string of characters.
4585 @code{string-equal} provides the corresponding test for equality.  Its
4586 shorter, alternative name is @code{string=}.  There are no string test
4587 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
4589 @item message
4590 Print a message in the echo area. The first argument is a string that
4591 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
4592 arguments that follow the string.  The argument used by @samp{%s} must
4593 be a string or a symbol; the argument used by @samp{%d} must be a
4594 number.  The argument used by @samp{%c} must be an @sc{ascii} code
4595 number; it will be printed as the character with that @sc{ascii} code.
4596 (Various other %-sequences have not been mentioned.)
4598 @item setq
4599 @itemx set
4600 The @code{setq} function sets the value of its first argument to the
4601 value of the second argument.  The first argument is automatically
4602 quoted by @code{setq}.  It does the same for succeeding pairs of
4603 arguments.  Another function, @code{set}, takes only two arguments and
4604 evaluates both of them before setting the value returned by its first
4605 argument to the value returned by its second argument.
4607 @item buffer-name
4608 Without an argument, return the name of the buffer, as a string.
4610 @itemx buffer-file-name
4611 Without an argument, return the name of the file the buffer is
4612 visiting.
4614 @item current-buffer
4615 Return the buffer in which Emacs is active; it may not be
4616 the buffer that is visible on the screen.
4618 @item other-buffer
4619 Return the most recently selected buffer (other than the buffer passed
4620 to @code{other-buffer} as an argument and other than the current
4621 buffer).
4623 @item switch-to-buffer
4624 Select a buffer for Emacs to be active in and display it in the current
4625 window so users can look at it.  Usually bound to @kbd{C-x b}.
4627 @item set-buffer
4628 Switch Emacs' attention to a buffer on which programs will run.  Don't
4629 alter what the window is showing.
4631 @item buffer-size
4632 Return the number of characters in the current buffer.
4634 @item point
4635 Return the value of the current position of the cursor, as an
4636 integer counting the number of characters from the beginning of the
4637 buffer.
4639 @item point-min
4640 Return the minimum permissible value of point in
4641 the current buffer.  This is 1, unless narrowing is in effect.
4643 @item point-max
4644 Return the value of the maximum permissible value of point in the
4645 current buffer.  This is the end of the buffer, unless narrowing is in
4646 effect.
4647 @end table
4649 @need 1500
4650 @node defun Exercises,  , Review, Writing Defuns
4651 @section Exercises
4653 @itemize @bullet
4654 @item
4655 Write a non-interactive function that doubles the value of its
4656 argument, a number.  Make that function interactive.
4658 @item
4659 Write a function that tests whether the current value of
4660 @code{fill-column} is greater than the argument passed to the function,
4661 and if so, prints an appropriate message.
4662 @end itemize
4664 @node Buffer Walk Through, More Complex, Writing Defuns, Top
4665 @comment  node-name,  next,  previous,  up
4666 @chapter A Few Buffer--Related Functions
4668 In this chapter we study in detail several of the functions used in GNU
4669 Emacs.  This is called a ``walk-through''.  These functions are used as
4670 examples of Lisp code, but are not imaginary examples; with the
4671 exception of the first, simplified function definition, these functions
4672 show the actual code used in GNU Emacs.  You can learn a great deal from
4673 these definitions.  The functions described here are all related to
4674 buffers.  Later, we will study other functions.
4676 @menu
4677 * Finding More::                How to find more information.
4678 * simplified-beginning-of-buffer::  Shows @code{goto-char},
4679                                 @code{point-min}, and @code{push-mark}.
4680 * mark-whole-buffer::           Almost the same as @code{beginning-of-buffer}.
4681 * append-to-buffer::            Uses @code{save-excursion} and
4682                                 @code{insert-buffer-substring}.
4683 * Buffer Related Review::       Review.
4684 * Buffer Exercises::
4685 @end menu
4687 @node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
4688 @section Finding More Information
4690 @findex describe-function, @r{introduced}
4691 @cindex Find function documentation
4692 In this walk-through, I will describe each new function as we come to
4693 it, sometimes in detail and sometimes briefly.  If you are interested,
4694 you can get the full documentation of any Emacs Lisp function at any
4695 time by typing @kbd{C-h f} and then the name of the function (and then
4696 @key{RET}).  Similarly, you can get the full documentation for a
4697 variable by typing @kbd{C-h v} and then the name of the variable (and
4698 then @key{RET}).
4700 @cindex Find source of function
4701 @c In version 22, tells location both of C and of Emacs Lisp
4702 Also, @code{describe-function} will tell you the location of the
4703 function definition.
4705 Put point into the name of the file that contains the function and
4706 press the @key{RET} key.  In this case, @key{RET} means
4707 @code{push-button} rather than `return' or `enter'.  Emacs will take
4708 you directly to the function definition.
4710 @ignore
4711 Not In version 22
4713 If you move point over the file name and press
4714 the @key{RET} key, which in this case means @code{help-follow} rather
4715 than `return' or `enter', Emacs will take you directly to the function
4716 definition.
4717 @end ignore
4719 More generally, if you want to see a function in its original source
4720 file, you can use the @code{find-tags} function to jump to it.
4721 @code{find-tags} works with a wide variety of languages, not just
4722 Lisp, and C, and it works with non-programming text as well.  For
4723 example, @code{find-tags} will jump to the various nodes in the
4724 Texinfo source file of this document.
4725 The @code{find-tags} function depends on `tags tables' that record
4726 the locations of the functions, variables, and other items to which
4727 @code{find-tags} jumps.
4729 To use the @code{find-tags} command, type @kbd{M-.}  (i.e., press the
4730 period key while holding down the @key{META} key, or else type the
4731 @key{ESC} key and then type the period key), and then, at the prompt,
4732 type in the name of the function whose source code you want to see,
4733 such as @code{mark-whole-buffer}, and then type @key{RET}.  Emacs will
4734 switch buffers and display the source code for the function on your
4735 screen.  To switch back to your current buffer, type @kbd{C-x b
4736 @key{RET}}.  (On some keyboards, the @key{META} key is labelled
4737 @key{ALT}.)
4739 @c !!! 22.1.1 tags table location in this paragraph
4740 @cindex TAGS table, specifying
4741 @findex find-tags
4742 Depending on how the initial default values of your copy of Emacs are
4743 set, you may also need to specify the location of your `tags table',
4744 which is a file called @file{TAGS}.  For example, if you are
4745 interested in Emacs sources, the tags table you will most likely want,
4746 if it has already been created for you, will be in a subdirectory of
4747 the @file{/usr/local/share/emacs/} directory; thus you would use the
4748 @code{M-x visit-tags-table} command and specify a pathname such as
4749 @file{/usr/local/share/emacs/22.1.1/lisp/TAGS}.  If the tags table
4750 has not already been created, you will have to create it yourself.  It
4751 will in a file such as @file{/usr/local/src/emacs/src/TAGS}.
4753 @need 1250
4754 To create a @file{TAGS} file in a specific directory, switch to that
4755 directory in Emacs using @kbd{M-x cd} command, or list the directory
4756 with @kbd{C-x d} (@code{dired}).  Then run the compile command, with
4757 @w{@code{etags *.el}} as the command to execute:
4759 @smallexample
4760 M-x compile RET etags *.el RET
4761 @end smallexample
4763 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
4765 After you become more familiar with Emacs Lisp, you will find that you will
4766 frequently use @code{find-tags} to navigate your way around source code;
4767 and you will create your own @file{TAGS} tables.
4769 @cindex Library, as term for `file'
4770 Incidentally, the files that contain Lisp code are conventionally
4771 called @dfn{libraries}.  The metaphor is derived from that of a
4772 specialized library, such as a law library or an engineering library,
4773 rather than a general library.  Each library, or file, contains
4774 functions that relate to a particular topic or activity, such as
4775 @file{abbrev.el} for handling abbreviations and other typing
4776 shortcuts, and @file{help.el} for on-line help.  (Sometimes several
4777 libraries provide code for a single activity, as the various
4778 @file{rmail@dots{}} files provide code for reading electronic mail.)
4779 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
4780 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
4781 by topic keywords.''
4783 @node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through
4784 @comment  node-name,  next,  previous,  up
4785 @section A Simplified @code{beginning-of-buffer} Definition
4786 @findex simplified-beginning-of-buffer
4788 The @code{beginning-of-buffer} command is a good function to start with
4789 since you are likely to be familiar with it and it is easy to
4790 understand.  Used as an interactive command, @code{beginning-of-buffer}
4791 moves the cursor to the beginning of the buffer, leaving the mark at the
4792 previous position.  It is generally bound to @kbd{M-<}.
4794 In this section, we will discuss a shortened version of the function
4795 that shows how it is most frequently used.  This shortened function
4796 works as written, but it does not contain the code for a complex option.
4797 In another section, we will describe the entire function.
4798 (@xref{beginning-of-buffer, , Complete Definition of
4799 @code{beginning-of-buffer}}.)
4801 Before looking at the code, let's consider what the function
4802 definition has to contain: it must include an expression that makes
4803 the function interactive so it can be called by typing @kbd{M-x
4804 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
4805 must include code to leave a mark at the original position in the
4806 buffer; and it must include code to move the cursor to the beginning
4807 of the buffer.
4809 @need 1250
4810 Here is the complete text of the shortened version of the function:
4812 @smallexample
4813 @group
4814 (defun simplified-beginning-of-buffer ()
4815   "Move point to the beginning of the buffer;
4816 leave mark at previous position."
4817   (interactive)
4818   (push-mark)
4819   (goto-char (point-min)))
4820 @end group
4821 @end smallexample
4823 Like all function definitions, this definition has five parts following
4824 the special form @code{defun}:
4826 @enumerate
4827 @item
4828 The name: in this example, @code{simplified-beginning-of-buffer}.
4830 @item
4831 A list of the arguments: in this example, an empty list, @code{()},
4833 @item
4834 The documentation string.
4836 @item
4837 The interactive expression.
4839 @item
4840 The body.
4841 @end enumerate
4843 @noindent
4844 In this function definition, the argument list is empty; this means that
4845 this function does not require any arguments.  (When we look at the
4846 definition for the complete function, we will see that it may be passed
4847 an optional argument.)
4849 The interactive expression tells Emacs that the function is intended to
4850 be used interactively.  In this example, @code{interactive} does not have
4851 an argument because @code{simplified-beginning-of-buffer} does not
4852 require one.
4854 @need 800
4855 The body of the function consists of the two lines:
4857 @smallexample
4858 @group
4859 (push-mark)
4860 (goto-char (point-min))
4861 @end group
4862 @end smallexample
4864 The first of these lines is the expression, @code{(push-mark)}.  When
4865 this expression is evaluated by the Lisp interpreter, it sets a mark at
4866 the current position of the cursor, wherever that may be.  The position
4867 of this mark is saved in the mark ring.
4869 The next line is @code{(goto-char (point-min))}.  This expression
4870 jumps the cursor to the minimum point in the buffer, that is, to the
4871 beginning of the buffer (or to the beginning of the accessible portion
4872 of the buffer if it is narrowed.  @xref{Narrowing & Widening, ,
4873 Narrowing and Widening}.)
4875 The @code{push-mark} command sets a mark at the place where the cursor
4876 was located before it was moved to the beginning of the buffer by the
4877 @code{(goto-char (point-min))} expression.  Consequently, you can, if
4878 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
4880 That is all there is to the function definition!
4882 @findex describe-function
4883 When you are reading code such as this and come upon an unfamiliar
4884 function, such as @code{goto-char}, you can find out what it does by
4885 using the @code{describe-function} command.  To use this command, type
4886 @kbd{C-h f} and then type in the name of the function and press
4887 @key{RET}.  The @code{describe-function} command will print the
4888 function's documentation string in a @file{*Help*} window.  For
4889 example, the documentation for @code{goto-char} is:
4891 @smallexample
4892 @group
4893 Set point to POSITION, a number or marker.
4894 Beginning of buffer is position (point-min), end is (point-max).
4895 @end group
4896 @end smallexample
4898 @noindent
4899 The function's one argument is the desired position.
4901 @noindent
4902 (The prompt for @code{describe-function} will offer you the symbol
4903 under or preceding the cursor, so you can save typing by positioning
4904 the cursor right over or after the function and then typing @kbd{C-h f
4905 @key{RET}}.)
4907 The @code{end-of-buffer} function definition is written in the same way as
4908 the @code{beginning-of-buffer} definition except that the body of the
4909 function contains the expression @code{(goto-char (point-max))} in place
4910 of @code{(goto-char (point-min))}.
4912 @node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through
4913 @comment  node-name,  next,  previous,  up
4914 @section The Definition of @code{mark-whole-buffer}
4915 @findex mark-whole-buffer
4917 The @code{mark-whole-buffer} function is no harder to understand than the
4918 @code{simplified-beginning-of-buffer} function.  In this case, however,
4919 we will look at the complete function, not a shortened version.
4921 The @code{mark-whole-buffer} function is not as commonly used as the
4922 @code{beginning-of-buffer} function, but is useful nonetheless: it
4923 marks a whole buffer as a region by putting point at the beginning and
4924 a mark at the end of the buffer.  It is generally bound to @kbd{C-x
4927 @menu
4928 * mark-whole-buffer overview::
4929 * Body of mark-whole-buffer::   Only three lines of code.
4930 @end menu
4932 @node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
4933 @ifnottex
4934 @unnumberedsubsec An overview of @code{mark-whole-buffer}
4935 @end ifnottex
4937 @need 1250
4938 In GNU Emacs 22, the code for the complete function looks like this:
4940 @smallexample
4941 @group
4942 (defun mark-whole-buffer ()
4943   "Put point at beginning and mark at end of buffer.
4944 You probably should not use this function in Lisp programs;
4945 it is usually a mistake for a Lisp function to use any subroutine
4946 that uses or sets the mark."
4947   (interactive)
4948   (push-mark (point))
4949   (push-mark (point-max) nil t)
4950   (goto-char (point-min)))
4951 @end group
4952 @end smallexample
4954 @need 1250
4955 Like all other functions, the @code{mark-whole-buffer} function fits
4956 into the template for a function definition.  The template looks like
4957 this:
4959 @smallexample
4960 @group
4961 (defun @var{name-of-function} (@var{argument-list})
4962   "@var{documentation}@dots{}"
4963   (@var{interactive-expression}@dots{})
4964   @var{body}@dots{})
4965 @end group
4966 @end smallexample
4968 Here is how the function works: the name of the function is
4969 @code{mark-whole-buffer}; it is followed by an empty argument list,
4970 @samp{()}, which means that the function does not require arguments.
4971 The documentation comes next.
4973 The next line is an @code{(interactive)} expression that tells Emacs
4974 that the function will be used interactively.  These details are similar
4975 to the @code{simplified-beginning-of-buffer} function described in the
4976 previous section.
4978 @need 1250
4979 @node Body of mark-whole-buffer,  , mark-whole-buffer overview, mark-whole-buffer
4980 @comment  node-name,  next,  previous,  up
4981 @subsection Body of @code{mark-whole-buffer}
4983 The body of the @code{mark-whole-buffer} function consists of three
4984 lines of code:
4986 @c GNU Emacs 22
4987 @smallexample
4988 @group
4989 (push-mark (point))
4990 (push-mark (point-max) nil t)
4991 (goto-char (point-min))
4992 @end group
4993 @end smallexample
4995 The first of these lines is the expression, @code{(push-mark (point))}.
4997 This line does exactly the same job as the first line of the body of
4998 the @code{simplified-beginning-of-buffer} function, which is written
4999 @code{(push-mark)}.  In both cases, the Lisp interpreter sets a mark
5000 at the current position of the cursor.
5002 I don't know why the expression in @code{mark-whole-buffer} is written
5003 @code{(push-mark (point))} and the expression in
5004 @code{beginning-of-buffer} is written @code{(push-mark)}.  Perhaps
5005 whoever wrote the code did not know that the arguments for
5006 @code{push-mark} are optional and that if @code{push-mark} is not
5007 passed an argument, the function automatically sets mark at the
5008 location of point by default.  Or perhaps the expression was written
5009 so as to parallel the structure of the next line.  In any case, the
5010 line causes Emacs to determine the position of point and set a mark
5011 there.
5013 In earlier versions of GNU Emacs, the next line of
5014 @code{mark-whole-buffer} was @code{(push-mark (point-max))}.  This
5015 expression sets a mark at the point in the buffer that has the highest
5016 number.  This will be the end of the buffer (or, if the buffer is
5017 narrowed, the end of the accessible portion of the buffer.
5018 @xref{Narrowing & Widening, , Narrowing and Widening}, for more about
5019 narrowing.)  After this mark has been set, the previous mark, the one
5020 set at point, is no longer set, but Emacs remembers its position, just
5021 as all other recent marks are always remembered.  This means that you
5022 can, if you wish, go back to that position by typing @kbd{C-u
5023 C-@key{SPC}} twice.
5025 @need 1250
5026 In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
5027 The line reads
5029 @smallexample
5030 (push-mark (point-max) nil t)
5031 @end smallexample
5033 @noindent
5034 The expression works nearly the same as before.  It sets a mark at the
5035 highest numbered place in the buffer that it can.  However, in this
5036 version, @code{push-mark} has two additional arguments.  The second
5037 argument to @code{push-mark} is @code{nil}.  This tells the function
5038 it @emph{should} display a message that says `Mark set' when it pushes
5039 the mark.  The third argument is @code{t}.  This tells
5040 @code{push-mark} to activate the mark when Transient Mark mode is
5041 turned on.  Transient Mark mode highlights the currently active
5042 region.  It is often turned off.
5044 Finally, the last line of the function is @code{(goto-char
5045 (point-min)))}.  This is written exactly the same way as it is written
5046 in @code{beginning-of-buffer}.  The expression moves the cursor to
5047 the minimum point in the buffer, that is, to the beginning of the buffer
5048 (or to the beginning of the accessible portion of the buffer).  As a
5049 result of this, point is placed at the beginning of the buffer and mark
5050 is set at the end of the buffer.  The whole buffer is, therefore, the
5051 region.
5053 @node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through
5054 @comment  node-name,  next,  previous,  up
5055 @section The Definition of @code{append-to-buffer}
5056 @findex append-to-buffer
5058 The @code{append-to-buffer} command is more complex than the
5059 @code{mark-whole-buffer} command.  What it does is copy the region
5060 (that is, the part of the buffer between point and mark) from the
5061 current buffer to a specified buffer.
5063 @menu
5064 * append-to-buffer overview::
5065 * append interactive::          A two part interactive expression.
5066 * append-to-buffer body::       Incorporates a @code{let} expression.
5067 * append save-excursion::       How the @code{save-excursion} works.
5068 @end menu
5070 @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
5071 @ifnottex
5072 @unnumberedsubsec An Overview of @code{append-to-buffer}
5073 @end ifnottex
5075 @findex insert-buffer-substring
5076 The @code{append-to-buffer} command uses the
5077 @code{insert-buffer-substring} function to copy the region.
5078 @code{insert-buffer-substring} is described by its name: it takes a
5079 string of characters from part of a buffer, a ``substring'', and
5080 inserts them into another buffer.
5082 Most of @code{append-to-buffer} is
5083 concerned with setting up the conditions for
5084 @code{insert-buffer-substring} to work: the code must specify both the
5085 buffer to which the text will go, the window it comes from and goes
5086 to, and the region that will be copied.
5088 @need 1250
5089 Here is the complete text of the function:
5091 @smallexample
5092 @group
5093 (defun append-to-buffer (buffer start end)
5094   "Append to specified buffer the text of the region.
5095 It is inserted into that buffer before its point.
5096 @end group
5098 @group
5099 When calling from a program, give three arguments:
5100 BUFFER (or buffer name), START and END.
5101 START and END specify the portion of the current buffer to be copied."
5102   (interactive
5103    (list (read-buffer "Append to buffer: " (other-buffer
5104                                             (current-buffer) t))
5105          (region-beginning) (region-end)))
5106 @end group
5107 @group
5108   (let ((oldbuf (current-buffer)))
5109     (save-excursion
5110       (let* ((append-to (get-buffer-create buffer))
5111              (windows (get-buffer-window-list append-to t t))
5112              point)
5113         (set-buffer append-to)
5114         (setq point (point))
5115         (barf-if-buffer-read-only)
5116         (insert-buffer-substring oldbuf start end)
5117         (dolist (window windows)
5118           (when (= (window-point window) point)
5119             (set-window-point window (point))))))))
5120 @end group
5121 @end smallexample
5123 The function can be understood by looking at it as a series of
5124 filled-in templates.
5126 The outermost template is for the function definition.  In this
5127 function, it looks like this (with several slots filled in):
5129 @smallexample
5130 @group
5131 (defun append-to-buffer (buffer start end)
5132   "@var{documentation}@dots{}"
5133   (interactive @dots{})
5134   @var{body}@dots{})
5135 @end group
5136 @end smallexample
5138 The first line of the function includes its name and three arguments.
5139 The arguments are the @code{buffer} to which the text will be copied, and
5140 the @code{start} and @code{end} of the region in the current buffer that
5141 will be copied.
5143 The next part of the function is the documentation, which is clear and
5144 complete.  As is conventional, the three arguments are written in
5145 upper case so you will notice them easily.  Even better, they are
5146 described in the same order as in the argument list.
5148 Note that the documentation distinguishes between a buffer and its
5149 name.  (The function can handle either.)
5151 @node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
5152 @comment  node-name,  next,  previous,  up
5153 @subsection The @code{append-to-buffer} Interactive Expression
5155 Since the @code{append-to-buffer} function will be used interactively,
5156 the function must have an @code{interactive} expression.  (For a
5157 review of @code{interactive}, see @ref{Interactive, , Making a
5158 Function Interactive}.)  The expression reads as follows:
5160 @smallexample
5161 @group
5162 (interactive
5163  (list (read-buffer
5164         "Append to buffer: "
5165         (other-buffer (current-buffer) t))
5166        (region-beginning)
5167        (region-end)))
5168 @end group
5169 @end smallexample
5171 @noindent
5172 This expression is not one with letters standing for parts, as
5173 described earlier.  Instead, it starts a list with thee parts.
5175 The first part of the list is an expression to read the name of a
5176 buffer and return it as a string.  That is @code{read-buffer}.  The
5177 function requires a prompt as its first argument, @samp{"Append to
5178 buffer: "}.  Its second argument tells the command what value to
5179 provide if you don't specify anything.
5181 In this case that second argument is an expression containing the
5182 function @code{other-buffer}, an exception, and a @samp{t}, standing
5183 for true.
5185 The first argument to @code{other-buffer}, the exception, is yet
5186 another function, @code{current-buffer}.  That is not going to be
5187 returned.  The second argument is the symbol for true, @code{t}. that
5188 tells @code{other-buffer} that it may show visible buffers (except in
5189 this case, it will not show the current buffer, which makes sense).
5191 @need 1250
5192 The expression looks like this:
5194 @smallexample
5195 (other-buffer (current-buffer) t)
5196 @end smallexample
5198 The second and third arguments to the @code{list} expression are
5199 @code{(region-beginning)} and @code{(region-end)}.  These two
5200 functions specify the beginning and end of the text to be appended.
5202 @need 1250
5203 Originally, the command used the letters @samp{B} and @samp{r}.
5204 The whole @code{interactive} expression looked like this:
5206 @smallexample
5207 (interactive "BAppend to buffer:@: \nr")
5208 @end smallexample
5210 @noindent
5211 But when that was done, the default value of the buffer switched to
5212 was invisible.  That was not wanted.
5214 (The prompt was separated from the second argument with a newline,
5215 @samp{\n}.  It was followed by an @samp{r} that told Emacs to bind the
5216 two arguments that follow the symbol @code{buffer} in the function's
5217 argument list (that is, @code{start} and @code{end}) to the values of
5218 point and mark.  That argument worked fine.)
5220 @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
5221 @comment  node-name,  next,  previous,  up
5222 @subsection The Body of @code{append-to-buffer}
5224 @ignore
5225 in GNU Emacs 22   in    /usr/local/src/emacs/lisp/simple.el
5227 (defun append-to-buffer (buffer start end)
5228   "Append to specified buffer the text of the region.
5229 It is inserted into that buffer before its point.
5231 When calling from a program, give three arguments:
5232 BUFFER (or buffer name), START and END.
5233 START and END specify the portion of the current buffer to be copied."
5234   (interactive
5235    (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
5236          (region-beginning) (region-end)))
5237   (let ((oldbuf (current-buffer)))
5238     (save-excursion
5239       (let* ((append-to (get-buffer-create buffer))
5240              (windows (get-buffer-window-list append-to t t))
5241              point)
5242         (set-buffer append-to)
5243         (setq point (point))
5244         (barf-if-buffer-read-only)
5245         (insert-buffer-substring oldbuf start end)
5246         (dolist (window windows)
5247           (when (= (window-point window) point)
5248             (set-window-point window (point))))))))
5249 @end ignore
5251 The body of the @code{append-to-buffer} function begins with @code{let}.
5253 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
5254 @code{let} expression is to create and give initial values to one or
5255 more variables that will only be used within the body of the
5256 @code{let}.  This means that such a variable will not be confused with
5257 any variable of the same name outside the @code{let} expression.
5259 We can see how the @code{let} expression fits into the function as a
5260 whole by showing a template for @code{append-to-buffer} with the
5261 @code{let} expression in outline:
5263 @smallexample
5264 @group
5265 (defun append-to-buffer (buffer start end)
5266   "@var{documentation}@dots{}"
5267   (interactive @dots{})
5268   (let ((@var{variable} @var{value}))
5269         @var{body}@dots{})
5270 @end group
5271 @end smallexample
5273 The @code{let} expression has three elements:
5275 @enumerate
5276 @item
5277 The symbol @code{let};
5279 @item
5280 A varlist containing, in this case, a single two-element list,
5281 @code{(@var{variable} @var{value})};
5283 @item
5284 The body of the @code{let} expression.
5285 @end enumerate
5287 @need 800
5288 In the @code{append-to-buffer} function, the varlist looks like this:
5290 @smallexample
5291 (oldbuf (current-buffer))
5292 @end smallexample
5294 @noindent
5295 In this part of the @code{let} expression, the one variable,
5296 @code{oldbuf}, is bound to the value returned by the
5297 @code{(current-buffer)} expression.  The variable, @code{oldbuf}, is
5298 used to keep track of the buffer in which you are working and from
5299 which you will copy.
5301 The element or elements of a varlist are surrounded by a set of
5302 parentheses so the Lisp interpreter can distinguish the varlist from
5303 the body of the @code{let}.  As a consequence, the two-element list
5304 within the varlist is surrounded by a circumscribing set of parentheses.
5305 The line looks like this:
5307 @smallexample
5308 @group
5309 (let ((oldbuf (current-buffer)))
5310   @dots{} )
5311 @end group
5312 @end smallexample
5314 @noindent
5315 The two parentheses before @code{oldbuf} might surprise you if you did
5316 not realize that the first parenthesis before @code{oldbuf} marks the
5317 boundary of the varlist and the second parenthesis marks the beginning
5318 of the two-element list, @code{(oldbuf (current-buffer))}.
5320 @node append save-excursion,  , append-to-buffer body, append-to-buffer
5321 @comment  node-name,  next,  previous,  up
5322 @subsection @code{save-excursion} in @code{append-to-buffer}
5324 The body of the @code{let} expression in @code{append-to-buffer}
5325 consists of a @code{save-excursion} expression.
5327 The @code{save-excursion} function saves the locations of point and
5328 mark, and restores them to those positions after the expressions in the
5329 body of the @code{save-excursion} complete execution.  In addition,
5330 @code{save-excursion} keeps track of the original buffer, and
5331 restores it.  This is how @code{save-excursion} is used in
5332 @code{append-to-buffer}.
5334 @need 1500
5335 @cindex Indentation for formatting
5336 @cindex Formatting convention
5337 Incidentally, it is worth noting here that a Lisp function is normally
5338 formatted so that everything that is enclosed in a multi-line spread is
5339 indented more to the right than the first symbol.  In this function
5340 definition, the @code{let} is indented more than the @code{defun}, and
5341 the @code{save-excursion} is indented more than the @code{let}, like
5342 this:
5344 @smallexample
5345 @group
5346 (defun @dots{}
5347   @dots{}
5348   @dots{}
5349   (let@dots{}
5350     (save-excursion
5351       @dots{}
5352 @end group
5353 @end smallexample
5355 @need 1500
5356 @noindent
5357 This formatting convention makes it easy to see that the lines in
5358 the body of the @code{save-excursion} are enclosed by the parentheses
5359 associated with @code{save-excursion}, just as the
5360 @code{save-excursion} itself is enclosed by the parentheses associated
5361 with the @code{let}:
5363 @smallexample
5364 @group
5365 (let ((oldbuf (current-buffer)))
5366   (save-excursion
5367     @dots{}
5368     (set-buffer @dots{})
5369     (insert-buffer-substring oldbuf start end)
5370     @dots{}))
5371 @end group
5372 @end smallexample
5374 @need 1200
5375 The use of the @code{save-excursion} function can be viewed as a process
5376 of filling in the slots of a template:
5378 @smallexample
5379 @group
5380 (save-excursion
5381   @var{first-expression-in-body}
5382   @var{second-expression-in-body}
5383    @dots{}
5384   @var{last-expression-in-body})
5385 @end group
5386 @end smallexample
5388 @need 1200
5389 @noindent
5390 In this function, the body of the @code{save-excursion} contains only
5391 one expression, the @code{let*} expression.  You know about a
5392 @code{let} function.  The @code{let*} function is different.  It has a
5393 @samp{*} in its name.  It enables Emacs to set each variable in its
5394 varlist in sequence, one after another.
5396 Its critical feature is that variables later in the varlist can make
5397 use of the values to which Emacs set variables earlier in the varlist.
5398 @xref{fwd-para let, , The @code{let*} expression}.
5400 We will skip functions like @code{let*} and focus on two: the
5401 @code{set-buffer} function and the @code{insert-buffer-substring}
5402 function.
5404 @need 1250
5405 In the old days, the @code{set-buffer} expression was simply
5407 @smallexample
5408 (set-buffer (get-buffer-create buffer))
5409 @end smallexample
5411 @need 1250
5412 @noindent
5413 but now it is
5415 @smallexample
5416 (set-buffer append-to)
5417 @end smallexample
5419 @noindent
5420 @code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
5421 on in the @code{let*} expression.  That extra binding would not be
5422 necessary except for that @code{append-to} is used later in the
5423 varlist as an argument to @code{get-buffer-window-list}.
5425 @ignore
5426 in GNU Emacs 22
5428   (let ((oldbuf (current-buffer)))
5429     (save-excursion
5430       (let* ((append-to (get-buffer-create buffer))
5431              (windows (get-buffer-window-list append-to t t))
5432              point)
5433         (set-buffer append-to)
5434         (setq point (point))
5435         (barf-if-buffer-read-only)
5436         (insert-buffer-substring oldbuf start end)
5437         (dolist (window windows)
5438           (when (= (window-point window) point)
5439             (set-window-point window (point))))))))
5440 @end ignore
5442 The @code{append-to-buffer} function definition inserts text from the
5443 buffer in which you are currently to a named buffer.  It happens that
5444 @code{insert-buffer-substring} copies text from another buffer to the
5445 current buffer, just the reverse---that is why the
5446 @code{append-to-buffer} definition starts out with a @code{let} that
5447 binds the local symbol @code{oldbuf} to the value returned by
5448 @code{current-buffer}.
5450 @need 1250
5451 The @code{insert-buffer-substring} expression looks like this:
5453 @smallexample
5454 (insert-buffer-substring oldbuf start end)
5455 @end smallexample
5457 @noindent
5458 The @code{insert-buffer-substring} function copies a string
5459 @emph{from} the buffer specified as its first argument and inserts the
5460 string into the present buffer.  In this case, the argument to
5461 @code{insert-buffer-substring} is the value of the variable created
5462 and bound by the @code{let}, namely the value of @code{oldbuf}, which
5463 was the current buffer when you gave the @code{append-to-buffer}
5464 command.
5466 After @code{insert-buffer-substring} has done its work,
5467 @code{save-excursion} will restore the action to the original buffer
5468 and @code{append-to-buffer} will have done its job.
5470 @need 800
5471 Written in skeletal form, the workings of the body look like this:
5473 @smallexample
5474 @group
5475 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5476   (save-excursion                       ; @r{Keep track of buffer.}
5477     @var{change-buffer}
5478     @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
5480   @var{change-back-to-original-buffer-when-finished}
5481 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
5482 @end group
5483 @end smallexample
5485 In summary, @code{append-to-buffer} works as follows: it saves the
5486 value of the current buffer in the variable called @code{oldbuf}.  It
5487 gets the new buffer (creating one if need be) and switches Emacs'
5488 attention to it.  Using the value of @code{oldbuf}, it inserts the
5489 region of text from the old buffer into the new buffer; and then using
5490 @code{save-excursion}, it brings you back to your original buffer.
5492 In looking at @code{append-to-buffer}, you have explored a fairly
5493 complex function.  It shows how to use @code{let} and
5494 @code{save-excursion}, and how to change to and come back from another
5495 buffer.  Many function definitions use @code{let},
5496 @code{save-excursion}, and @code{set-buffer} this way.
5498 @node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through
5499 @comment  node-name,  next,  previous,  up
5500 @section Review
5502 Here is a brief summary of the various functions discussed in this chapter.
5504 @table @code
5505 @item describe-function
5506 @itemx describe-variable
5507 Print the documentation for a function or variable.
5508 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
5510 @item find-tag
5511 Find the file containing the source for a function or variable and
5512 switch buffers to it, positioning point at the beginning of the item.
5513 Conventionally bound to @kbd{M-.} (that's a period following the
5514 @key{META} key).
5516 @item save-excursion
5517 Save the location of point and mark and restore their values after the
5518 arguments to @code{save-excursion} have been evaluated.  Also, remember
5519 the current buffer and return to it.
5521 @item push-mark
5522 Set mark at a location and record the value of the previous mark on the
5523 mark ring.  The mark is a location in the buffer that will keep its
5524 relative position even if text is added to or removed from the buffer.
5526 @item goto-char
5527 Set point to the location specified by the value of the argument, which
5528 can be a number, a marker,  or an expression that returns the number of
5529 a position, such as @code{(point-min)}.
5531 @item insert-buffer-substring
5532 Copy a region of text from a buffer that is passed to the function as
5533 an argument and insert the region into the current buffer.
5535 @item mark-whole-buffer
5536 Mark the whole buffer as a region.  Normally bound to @kbd{C-x h}.
5538 @item set-buffer
5539 Switch the attention of Emacs to another buffer, but do not change the
5540 window being displayed.  Used when the program rather than a human is
5541 to work on a different buffer.
5543 @item get-buffer-create
5544 @itemx get-buffer
5545 Find a named buffer or create one if a buffer of that name does not
5546 exist.  The @code{get-buffer} function returns @code{nil} if the named
5547 buffer does not exist.
5548 @end table
5550 @need 1500
5551 @node Buffer Exercises,  , Buffer Related Review, Buffer Walk Through
5552 @section Exercises
5554 @itemize @bullet
5555 @item
5556 Write your own @code{simplified-end-of-buffer} function definition;
5557 then test it to see whether it works.
5559 @item
5560 Use @code{if} and @code{get-buffer} to write a function that prints a
5561 message telling you whether a buffer exists.
5563 @item
5564 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
5565 function.
5566 @end itemize
5568 @node More Complex, Narrowing & Widening, Buffer Walk Through, Top
5569 @comment  node-name,  next,  previous,  up
5570 @chapter A Few More Complex Functions
5572 In this chapter, we build on what we have learned in previous chapters
5573 by looking at more complex functions.  The @code{copy-to-buffer}
5574 function illustrates use of two @code{save-excursion} expressions in
5575 one definition, while the @code{insert-buffer} function illustrates
5576 use of an asterisk in an @code{interactive} expression, use of
5577 @code{or}, and the important distinction between a name and the object
5578 to which the name refers.
5580 @menu
5581 * copy-to-buffer::              With @code{set-buffer}, @code{get-buffer-create}.
5582 * insert-buffer::               Read-only, and with @code{or}.
5583 * beginning-of-buffer::         Shows @code{goto-char},
5584                                 @code{point-min}, and @code{push-mark}.
5585 * Second Buffer Related Review::
5586 * optional Exercise::
5587 @end menu
5589 @node copy-to-buffer, insert-buffer, More Complex, More Complex
5590 @comment  node-name,  next,  previous,  up
5591 @section The Definition of @code{copy-to-buffer}
5592 @findex copy-to-buffer
5594 After understanding how @code{append-to-buffer} works, it is easy to
5595 understand @code{copy-to-buffer}.  This function copies text into a
5596 buffer, but instead of adding to the second buffer, it replaces all the
5597 previous text in the second buffer.
5599 @need 800
5600 The body of @code{copy-to-buffer} looks like this,
5602 @smallexample
5603 @group
5604 @dots{}
5605 (interactive "BCopy to buffer: \nr")
5606 (let ((oldbuf (current-buffer)))
5607   (with-current-buffer (get-buffer-create buffer)
5608     (barf-if-buffer-read-only)
5609     (erase-buffer)
5610     (save-excursion
5611       (insert-buffer-substring oldbuf start end)))))
5612 @end group
5613 @end smallexample
5615 The @code{copy-to-buffer} function has a simpler @code{interactive}
5616 expression than @code{append-to-buffer}.
5618 @need 800
5619 The definition then says
5621 @smallexample
5622 (with-current-buffer (get-buffer-create buffer) @dots{}
5623 @end smallexample
5625 First, look at the earliest inner expression; that is evaluated first.
5626 That expression starts with @code{get-buffer-create buffer}.  The
5627 function tells the computer to use the buffer with the name specified
5628 as the one to which you are copying, or if such a buffer does not
5629 exist, to create it.  Then, the @code{with-current-buffer} function
5630 evaluates its body with that buffer temporarily current.
5632 (This demonstrates another way to shift the computer's attention but
5633 not the user's.  The @code{append-to-buffer} function showed how to do
5634 the same with @code{save-excursion} and @code{set-buffer}.
5635 @code{with-current-buffer} is a newer, and arguably easier,
5636 mechanism.)
5638 The @code{barf-if-buffer-read-only} function sends you an error
5639 message saying the buffer is read-only if you cannot modify it.
5641 The next line has the @code{erase-buffer} function as its sole
5642 contents.  That function erases the buffer.
5644 Finally, the last two lines contain the @code{save-excursion}
5645 expression with @code{insert-buffer-substring} as its body.
5646 The  @code{insert-buffer-substring} expression copies the text from
5647 the buffer you are in (and you have not seen the computer shift its
5648 attention, so you don't know that that buffer is now called
5649 @code{oldbuf}).
5651 Incidentally, this is what is meant by `replacement'.  To replace text,
5652 Emacs erases the previous text and then inserts new text.
5654 @need 1250
5655 In outline, the body of @code{copy-to-buffer} looks like this:
5657 @smallexample
5658 @group
5659 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5660     (@var{with-the-buffer-you-are-copying-to}
5661       (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
5662       (erase-buffer)
5663       (save-excursion
5664         @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
5665 @end group
5666 @end smallexample
5668 @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
5669 @comment  node-name,  next,  previous,  up
5670 @section The Definition of @code{insert-buffer}
5671 @findex insert-buffer
5673 @code{insert-buffer} is yet another buffer-related function.  This
5674 command copies another buffer @emph{into} the current buffer.  It is the
5675 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
5676 copy a region of text @emph{from} the current buffer to another buffer.
5678 Here is a discussion based on the original code.  The code was
5679 simplified in 2003 and is harder to understand.
5681 (@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
5682 a discussion of the new body.)
5684 In addition, this code illustrates the use of @code{interactive} with a
5685 buffer that might be @dfn{read-only} and the important distinction
5686 between the name of an object and the object actually referred to.
5688 @menu
5689 * insert-buffer code::
5690 * insert-buffer interactive::   When you can read, but not write.
5691 * insert-buffer body::          The body has an @code{or} and a @code{let}.
5692 * if & or::                     Using an @code{if} instead of an @code{or}.
5693 * Insert or::                   How the @code{or} expression works.
5694 * Insert let::                  Two @code{save-excursion} expressions.
5695 * New insert-buffer::
5696 @end menu
5698 @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
5699 @ifnottex
5700 @unnumberedsubsec The Code for @code{insert-buffer}
5701 @end ifnottex
5703 @need 800
5704 Here is the earlier code:
5706 @smallexample
5707 @group
5708 (defun insert-buffer (buffer)
5709   "Insert after point the contents of BUFFER.
5710 Puts mark after the inserted text.
5711 BUFFER may be a buffer or a buffer name."
5712   (interactive "*bInsert buffer:@: ")
5713 @end group
5714 @group
5715   (or (bufferp buffer)
5716       (setq buffer (get-buffer buffer)))
5717   (let (start end newmark)
5718     (save-excursion
5719       (save-excursion
5720         (set-buffer buffer)
5721         (setq start (point-min) end (point-max)))
5722 @end group
5723 @group
5724       (insert-buffer-substring buffer start end)
5725       (setq newmark (point)))
5726     (push-mark newmark)))
5727 @end group
5728 @end smallexample
5730 @need 1200
5731 As with other function definitions, you can use a template to see an
5732 outline of the function:
5734 @smallexample
5735 @group
5736 (defun insert-buffer (buffer)
5737   "@var{documentation}@dots{}"
5738   (interactive "*bInsert buffer:@: ")
5739   @var{body}@dots{})
5740 @end group
5741 @end smallexample
5743 @node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer
5744 @comment  node-name,  next,  previous,  up
5745 @subsection The Interactive Expression in @code{insert-buffer}
5746 @findex interactive, @r{example use of}
5748 In @code{insert-buffer}, the argument to the @code{interactive}
5749 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
5750 buffer:@: }.
5752 @menu
5753 * Read-only buffer::            When a buffer cannot be modified.
5754 * b for interactive::           An existing buffer or else its name.
5755 @end menu
5757 @node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
5758 @comment  node-name,  next,  previous,  up
5759 @unnumberedsubsubsec A Read-only Buffer
5760 @cindex Read-only buffer
5761 @cindex Asterisk for read-only buffer
5762 @findex * @r{for read-only buffer}
5764 The asterisk is for the situation when the current buffer is a
5765 read-only buffer---a buffer that cannot be modified.  If
5766 @code{insert-buffer} is called when the current buffer is read-only, a
5767 message to this effect is printed in the echo area and the terminal
5768 may beep or blink at you; you will not be permitted to insert anything
5769 into current buffer.  The asterisk does not need to be followed by a
5770 newline to separate it from the next argument.
5772 @node b for interactive,  , Read-only buffer, insert-buffer interactive
5773 @comment  node-name,  next,  previous,  up
5774 @unnumberedsubsubsec @samp{b} in an Interactive Expression
5776 The next argument in the interactive expression starts with a lower
5777 case @samp{b}.  (This is different from the code for
5778 @code{append-to-buffer}, which uses an upper-case @samp{B}.
5779 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
5780 The lower-case @samp{b} tells the Lisp interpreter that the argument
5781 for @code{insert-buffer} should be an existing buffer or else its
5782 name.  (The upper-case @samp{B} option provides for the possibility
5783 that the buffer does not exist.)  Emacs will prompt you for the name
5784 of the buffer, offering you a default buffer, with name completion
5785 enabled.  If the buffer does not exist, you receive a message that
5786 says ``No match''; your terminal may beep at you as well.
5788 The new and simplified code generates a list for @code{interactive}.
5789 It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
5790 functions with which we are already familiar and the @code{progn}
5791 special form with which we are not.  (It will be described later.)
5793 @node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
5794 @comment  node-name,  next,  previous,  up
5795 @subsection The Body of the @code{insert-buffer} Function
5797 The body of the @code{insert-buffer} function has two major parts: an
5798 @code{or} expression and a @code{let} expression.  The purpose of the
5799 @code{or} expression is to ensure that the argument @code{buffer} is
5800 bound to a buffer and not just the name of a buffer.  The body of the
5801 @code{let} expression contains the code which copies the other buffer
5802 into the current buffer.
5804 @need 1250
5805 In outline, the two expressions fit into the @code{insert-buffer}
5806 function like this:
5808 @smallexample
5809 @group
5810 (defun insert-buffer (buffer)
5811   "@var{documentation}@dots{}"
5812   (interactive "*bInsert buffer:@: ")
5813   (or @dots{}
5814       @dots{}
5815 @end group
5816 @group
5817   (let (@var{varlist})
5818       @var{body-of-}@code{let}@dots{} )
5819 @end group
5820 @end smallexample
5822 To understand how the @code{or} expression ensures that the argument
5823 @code{buffer} is bound to a buffer and not to the name of a buffer, it
5824 is first necessary to understand the @code{or} function.
5826 Before doing this, let me rewrite this part of the function using
5827 @code{if} so that you can see what is done in a manner that will be familiar.
5829 @node if & or, Insert or, insert-buffer body, insert-buffer
5830 @comment  node-name,  next,  previous,  up
5831 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
5833 The job to be done is to make sure the value of @code{buffer} is a
5834 buffer itself and not the name of a buffer.  If the value is the name,
5835 then the buffer itself must be got.
5837 You can imagine yourself at a conference where an usher is wandering
5838 around holding a list with your name on it and looking for you: the
5839 usher is ``bound'' to your name, not to you; but when the usher finds
5840 you and takes your arm, the usher becomes ``bound'' to you.
5842 @need 800
5843 In Lisp, you might describe this situation like this:
5845 @smallexample
5846 @group
5847 (if (not (holding-on-to-guest))
5848     (find-and-take-arm-of-guest))
5849 @end group
5850 @end smallexample
5852 We want to do the same thing with a buffer---if we do not have the
5853 buffer itself, we want to get it.
5855 @need 1200
5856 Using a predicate called @code{bufferp} that tells us whether we have a
5857 buffer (rather than its name), we can write the code like this:
5859 @smallexample
5860 @group
5861 (if (not (bufferp buffer))              ; @r{if-part}
5862     (setq buffer (get-buffer buffer)))  ; @r{then-part}
5863 @end group
5864 @end smallexample
5866 @noindent
5867 Here, the true-or-false-test of the @code{if} expression is
5868 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
5869 @w{@code{(setq buffer (get-buffer buffer))}}.
5871 In the test, the function @code{bufferp} returns true if its argument is
5872 a buffer---but false if its argument is the name of the buffer.  (The
5873 last character of the function name @code{bufferp} is the character
5874 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
5875 indicates that the function is a predicate, which is a term that means
5876 that the function will determine whether some property is true or false.
5877 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
5878 Argument}.)
5880 @need 1200
5881 The function @code{not} precedes the expression @code{(bufferp buffer)},
5882 so the true-or-false-test looks like this:
5884 @smallexample
5885 (not (bufferp buffer))
5886 @end smallexample
5888 @noindent
5889 @code{not} is a function that returns true if its argument is false
5890 and false if its argument is true.  So if @code{(bufferp buffer)}
5891 returns true, the @code{not} expression returns false and vice-verse:
5892 what is ``not true'' is false and what is ``not false'' is true.
5894 Using this test, the @code{if} expression works as follows: when the
5895 value of the variable @code{buffer} is actually a buffer rather than
5896 its name, the true-or-false-test returns false and the @code{if}
5897 expression does not evaluate the then-part.  This is fine, since we do
5898 not need to do anything to the variable @code{buffer} if it really is
5899 a buffer.
5901 On the other hand, when the value of @code{buffer} is not a buffer
5902 itself, but the name of a buffer, the true-or-false-test returns true
5903 and the then-part of the expression is evaluated.  In this case, the
5904 then-part is @code{(setq buffer (get-buffer buffer))}.  This
5905 expression uses the @code{get-buffer} function to return an actual
5906 buffer itself, given its name.  The @code{setq} then sets the variable
5907 @code{buffer} to the value of the buffer itself, replacing its previous
5908 value (which was the name of the buffer).
5910 @node Insert or, Insert let, if & or, insert-buffer
5911 @comment  node-name,  next,  previous,  up
5912 @subsection The @code{or} in the Body
5914 The purpose of the @code{or} expression in the @code{insert-buffer}
5915 function is to ensure that the argument @code{buffer} is bound to a
5916 buffer and not just to the name of a buffer.  The previous section shows
5917 how the job could have been done using an @code{if} expression.
5918 However, the @code{insert-buffer} function actually uses @code{or}.
5919 To understand this, it is necessary to understand how @code{or} works.
5921 @findex or
5922 An @code{or} function can have any number of arguments.  It evaluates
5923 each argument in turn and returns the value of the first of its
5924 arguments that is not @code{nil}.  Also, and this is a crucial feature
5925 of @code{or}, it does not evaluate any subsequent arguments after
5926 returning the first non-@code{nil} value.
5928 @need 800
5929 The @code{or} expression looks like this:
5931 @smallexample
5932 @group
5933 (or (bufferp buffer)
5934     (setq buffer (get-buffer buffer)))
5935 @end group
5936 @end smallexample
5938 @noindent
5939 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
5940 This expression returns true (a non-@code{nil} value) if the buffer is
5941 actually a buffer, and not just the name of a buffer.  In the @code{or}
5942 expression, if this is the case, the @code{or} expression returns this
5943 true value and does not evaluate the next expression---and this is fine
5944 with us, since we do not want to do anything to the value of
5945 @code{buffer} if it really is a buffer.
5947 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
5948 which it will be if the value of @code{buffer} is the name of a buffer,
5949 the Lisp interpreter evaluates the next element of the @code{or}
5950 expression.  This is the expression @code{(setq buffer (get-buffer
5951 buffer))}.  This expression returns a non-@code{nil} value, which
5952 is the value to which it sets the variable @code{buffer}---and this
5953 value is a buffer itself, not the name of a buffer.
5955 The result of all this is that the symbol @code{buffer} is always
5956 bound to a buffer itself rather than to the name of a buffer.  All
5957 this is necessary because the @code{set-buffer} function in a
5958 following line only works with a buffer itself, not with the name to a
5959 buffer.
5961 @need 1250
5962 Incidentally, using @code{or}, the situation with the usher would be
5963 written like this:
5965 @smallexample
5966 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
5967 @end smallexample
5969 @node Insert let, New insert-buffer, Insert or, insert-buffer
5970 @comment  node-name,  next,  previous,  up
5971 @subsection The @code{let} Expression in @code{insert-buffer}
5973 After ensuring that the variable @code{buffer} refers to a buffer itself
5974 and not just to the name of a buffer, the @code{insert-buffer function}
5975 continues with a @code{let} expression.  This specifies three local
5976 variables, @code{start}, @code{end}, and @code{newmark} and binds them
5977 to the initial value @code{nil}.  These variables are used inside the
5978 remainder of the @code{let} and temporarily hide any other occurrence of
5979 variables of the same name in Emacs until the end of the @code{let}.
5981 @need 1200
5982 The body of the @code{let} contains two @code{save-excursion}
5983 expressions.  First, we will look at the inner @code{save-excursion}
5984 expression in detail.  The expression looks like this:
5986 @smallexample
5987 @group
5988 (save-excursion
5989   (set-buffer buffer)
5990   (setq start (point-min) end (point-max)))
5991 @end group
5992 @end smallexample
5994 @noindent
5995 The expression @code{(set-buffer buffer)} changes Emacs' attention
5996 from the current buffer to the one from which the text will copied.
5997 In that buffer, the variables @code{start} and @code{end} are set to
5998 the beginning and end of the buffer, using the commands
5999 @code{point-min} and @code{point-max}.  Note that we have here an
6000 illustration of how @code{setq} is able to set two variables in the
6001 same expression.  The first argument of @code{setq} is set to the
6002 value of its second, and its third argument is set to the value of its
6003 fourth.
6005 After the body of the inner @code{save-excursion} is evaluated, the
6006 @code{save-excursion} restores the original buffer, but @code{start} and
6007 @code{end} remain set to the values of the beginning and end of the
6008 buffer from which the text will be copied.
6010 @need 1250
6011 The outer @code{save-excursion} expression looks like this:
6013 @smallexample
6014 @group
6015 (save-excursion
6016   (@var{inner-}@code{save-excursion}@var{-expression}
6017      (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
6018   (insert-buffer-substring buffer start end)
6019   (setq newmark (point)))
6020 @end group
6021 @end smallexample
6023 @noindent
6024 The @code{insert-buffer-substring} function copies the text
6025 @emph{into} the current buffer @emph{from} the region indicated by
6026 @code{start} and @code{end} in @code{buffer}.  Since the whole of the
6027 second buffer lies between @code{start} and @code{end}, the whole of
6028 the second buffer is copied into the buffer you are editing.  Next,
6029 the value of point, which will be at the end of the inserted text, is
6030 recorded in the variable @code{newmark}.
6032 After the body of the outer @code{save-excursion} is evaluated, point
6033 and mark are relocated to their original places.
6035 However, it is convenient to locate a mark at the end of the newly
6036 inserted text and locate point at its beginning.  The @code{newmark}
6037 variable records the end of the inserted text.  In the last line of
6038 the @code{let} expression, the @code{(push-mark newmark)} expression
6039 function sets a mark to this location.  (The previous location of the
6040 mark is still accessible; it is recorded on the mark ring and you can
6041 go back to it with @kbd{C-u C-@key{SPC}}.)  Meanwhile, point is
6042 located at the beginning of the inserted text, which is where it was
6043 before you called the insert function, the position of which was saved
6044 by the first @code{save-excursion}.
6046 @need 1250
6047 The whole @code{let} expression looks like this:
6049 @smallexample
6050 @group
6051 (let (start end newmark)
6052   (save-excursion
6053     (save-excursion
6054       (set-buffer buffer)
6055       (setq start (point-min) end (point-max)))
6056     (insert-buffer-substring buffer start end)
6057     (setq newmark (point)))
6058   (push-mark newmark))
6059 @end group
6060 @end smallexample
6062 Like the @code{append-to-buffer} function, the @code{insert-buffer}
6063 function uses @code{let}, @code{save-excursion}, and
6064 @code{set-buffer}.  In addition, the function illustrates one way to
6065 use @code{or}.  All these functions are building blocks that we will
6066 find and use again and again.
6068 @node New insert-buffer,  , Insert let, insert-buffer
6069 @comment  node-name,  next,  previous,  up
6070 @subsection New Body for @code{insert-buffer}
6071 @findex insert-buffer, new version body
6072 @findex new version body for insert-buffer
6074 The body in the GNU Emacs 22 version is more confusing than the original.
6076 @need 1250
6077 It consists of two expressions,
6079 @smallexample
6080 @group
6081   (push-mark
6082    (save-excursion
6083      (insert-buffer-substring (get-buffer buffer))
6084      (point)))
6086    nil
6087 @end group
6088 @end smallexample
6090 @noindent
6091 except, and this is what confuses novices, very important work is done
6092 inside the @code{push-mark} expression.
6094 The @code{get-buffer} function returns a buffer with the name
6095 provided.  You will note that the function is @emph{not} called
6096 @code{get-buffer-create}; it does not create a buffer if one does not
6097 already exist.  The buffer returned by @code{get-buffer}, an existing
6098 buffer, is passed to @code{insert-buffer-substring}, which inserts the
6099 whole of the buffer (since you did not specify anything else).
6101 The location into which the buffer is inserted is recorded by
6102 @code{push-mark}.  Then the function returns @code{nil}, the value of
6103 its last command.  Put another way, the @code{insert-buffer} function
6104 exists only to produce a side effect, inserting another buffer, not to
6105 return any value.
6107 @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
6108 @comment  node-name,  next,  previous,  up
6109 @section Complete Definition of @code{beginning-of-buffer}
6110 @findex beginning-of-buffer
6112 The basic structure of the @code{beginning-of-buffer} function has
6113 already been discussed.  (@xref{simplified-beginning-of-buffer, , A
6114 Simplified @code{beginning-of-buffer} Definition}.)
6115 This section describes the complex part of the definition.
6117 As previously described, when invoked without an argument,
6118 @code{beginning-of-buffer} moves the cursor to the beginning of the
6119 buffer (in truth, the beginning of the accessible portion of the
6120 buffer), leaving the mark at the previous position.  However, when the
6121 command is invoked with a number between one and ten, the function
6122 considers that number to be a fraction of the length of the buffer,
6123 measured in tenths, and Emacs moves the cursor that fraction of the
6124 way from the beginning of the buffer.  Thus, you can either call this
6125 function with the key command @kbd{M-<}, which will move the cursor to
6126 the beginning of the buffer, or with a key command such as @kbd{C-u 7
6127 M-<} which will move the cursor to a point 70% of the way through the
6128 buffer.  If a number bigger than ten is used for the argument, it
6129 moves to the end of the buffer.
6131 The @code{beginning-of-buffer} function can be called with or without an
6132 argument.  The use of the argument is optional.
6134 @menu
6135 * Optional Arguments::
6136 * beginning-of-buffer opt arg::  Example with optional argument.
6137 * beginning-of-buffer complete::
6138 @end menu
6140 @node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
6141 @subsection Optional Arguments
6143 Unless told otherwise, Lisp expects that a function with an argument in
6144 its function definition will be called with a value for that argument.
6145 If that does not happen, you get an error and a message that says
6146 @samp{Wrong number of arguments}.
6148 @cindex Optional arguments
6149 @cindex Keyword
6150 @findex optional
6151 However, optional arguments are a feature of Lisp: a particular
6152 @dfn{keyword} is used to tell the Lisp interpreter that an argument is
6153 optional.  The keyword is @code{&optional}.  (The @samp{&} in front of
6154 @samp{optional} is part of the keyword.)  In a function definition, if
6155 an argument follows the keyword @code{&optional}, no value need be
6156 passed to that argument when the function is called.
6158 @need 1200
6159 The first line of the function definition of @code{beginning-of-buffer}
6160 therefore looks like this:
6162 @smallexample
6163 (defun beginning-of-buffer (&optional arg)
6164 @end smallexample
6166 @need 1250
6167 In outline, the whole function looks like this:
6169 @smallexample
6170 @group
6171 (defun beginning-of-buffer (&optional arg)
6172   "@var{documentation}@dots{}"
6173   (interactive "P")
6174   (or (@var{is-the-argument-a-cons-cell} arg)
6175       (and @var{are-both-transient-mark-mode-and-mark-active-true})
6176       (push-mark))
6177   (let (@var{determine-size-and-set-it})
6178   (goto-char
6179     (@var{if-there-is-an-argument}
6180         @var{figure-out-where-to-go}
6181       @var{else-go-to}
6182       (point-min))))
6183    @var{do-nicety}
6184 @end group
6185 @end smallexample
6187 The function is similar to the @code{simplified-beginning-of-buffer}
6188 function except that the @code{interactive} expression has @code{"P"}
6189 as an argument and the @code{goto-char} function is followed by an
6190 if-then-else expression that figures out where to put the cursor if
6191 there is an argument that is not a cons cell.
6193 (Since I do not explain a cons cell for many more chapters, please
6194 consider ignoring the function @code{consp}.  @xref{List
6195 Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
6196 , Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
6197 Manual}.)
6199 The @code{"P"} in the @code{interactive} expression tells Emacs to
6200 pass a prefix argument, if there is one, to the function in raw form.
6201 A prefix argument is made by typing the @key{META} key followed by a
6202 number, or by typing @kbd{C-u} and then a number.  (If you don't type
6203 a number, @kbd{C-u} defaults to a cons cell with a 4.  A lowercase
6204 @code{"p"} in the @code{interactive} expression causes the function to
6205 convert a prefix arg to a number.)
6207 The true-or-false-test of the @code{if} expression looks complex, but
6208 it is not: it checks whether @code{arg} has a value that is not
6209 @code{nil} and whether it is a cons cell.  (That is what @code{consp}
6210 does; it checks whether its argument is a cons cell.)  If @code{arg}
6211 has a value that is not @code{nil} (and is not a cons cell), which
6212 will be the case if @code{beginning-of-buffer} is called with a
6213 numeric argument, then this true-or-false-test will return true and
6214 the then-part of the @code{if} expression will be evaluated.  On the
6215 other hand, if @code{beginning-of-buffer} is not called with an
6216 argument, the value of @code{arg} will be @code{nil} and the else-part
6217 of the @code{if} expression will be evaluated.  The else-part is
6218 simply @code{point-min}, and when this is the outcome, the whole
6219 @code{goto-char} expression is @code{(goto-char (point-min))}, which
6220 is how we saw the @code{beginning-of-buffer} function in its
6221 simplified form.
6223 @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
6224 @subsection @code{beginning-of-buffer} with an Argument
6226 When @code{beginning-of-buffer} is called with an argument, an
6227 expression is evaluated which calculates what value to pass to
6228 @code{goto-char}.  This expression is rather complicated at first sight.
6229 It includes an inner @code{if} expression and much arithmetic.  It looks
6230 like this:
6232 @smallexample
6233 @group
6234 (if (> (buffer-size) 10000)
6235     ;; @r{Avoid overflow for large buffer sizes!}
6236                           (* (prefix-numeric-value arg)
6237                              (/ size 10))
6238   (/
6239    (+ 10
6240       (*
6241        size (prefix-numeric-value arg))) 10)))
6242 @end group
6243 @end smallexample
6245 @menu
6246 * Disentangle beginning-of-buffer::
6247 * Large buffer case::
6248 * Small buffer case::
6249 @end menu
6251 @node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg
6252 @ifnottex
6253 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
6254 @end ifnottex
6256 Like other complex-looking expressions, the conditional expression
6257 within @code{beginning-of-buffer} can be disentangled by looking at it
6258 as parts of a template, in this case, the template for an if-then-else
6259 expression.  In skeletal form, the expression looks like this:
6261 @smallexample
6262 @group
6263 (if (@var{buffer-is-large}
6264     @var{divide-buffer-size-by-10-and-multiply-by-arg}
6265   @var{else-use-alternate-calculation}
6266 @end group
6267 @end smallexample
6269 The true-or-false-test of this inner @code{if} expression checks the
6270 size of the buffer.  The reason for this is that the old version 18
6271 Emacs used numbers that are no bigger than eight million or so and in
6272 the computation that followed, the programmer feared that Emacs might
6273 try to use over-large numbers if the buffer were large.  The term
6274 `overflow', mentioned in the comment, means numbers that are over
6275 large.  More recent versions of Emacs use larger numbers, but this
6276 code has not been touched, if only because people now look at buffers
6277 that are far, far larger than ever before.
6279 There are two cases:  if the buffer is large and if it is not.
6281 @node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg
6282 @comment  node-name,  next,  previous,  up
6283 @unnumberedsubsubsec What happens in a large buffer
6285 In @code{beginning-of-buffer}, the inner @code{if} expression tests
6286 whether the size of the buffer is greater than 10,000 characters.  To do
6287 this, it uses the @code{>} function and the computation of @code{size}
6288 that comes from the let expression.
6290 In the old days, the function @code{buffer-size} was used.  Not only
6291 was that function called several times, it gave the size of the whole
6292 buffer, not the accessible part.  The computation makes much more
6293 sense when it handles just the accessible part.  (@xref{Narrowing &
6294 Widening, , Narrowing and Widening}, for more information on focusing
6295 attention to an `accessible' part.)
6297 @need 800
6298 The line looks like this:
6300 @smallexample
6301 (if (> size 10000)
6302 @end smallexample
6304 @need 1200
6305 @noindent
6306 When the buffer is large, the then-part of the @code{if} expression is
6307 evaluated.  It reads like this (after formatting for easy reading):
6309 @smallexample
6310 @group
6312   (prefix-numeric-value arg)
6313   (/ size 10))
6314 @end group
6315 @end smallexample
6317 @noindent
6318 This expression is a multiplication, with two arguments to the function
6319 @code{*}.
6321 The first argument is @code{(prefix-numeric-value arg)}.  When
6322 @code{"P"} is used as the argument for @code{interactive}, the value
6323 passed to the function as its argument is passed a ``raw prefix
6324 argument'', and not a number.  (It is a number in a list.)  To perform
6325 the arithmetic, a conversion is necessary, and
6326 @code{prefix-numeric-value} does the job.
6328 @findex / @r{(division)}
6329 @cindex Division
6330 The second argument is @code{(/ size 10)}.  This expression divides
6331 the numeric value by ten --- the numeric value of the size of the
6332 accessible portion of the buffer.  This produces a number that tells
6333 how many characters make up one tenth of the buffer size.  (In Lisp,
6334 @code{/} is used for division, just as @code{*} is used for
6335 multiplication.)
6337 @need 1200
6338 In the multiplication expression as a whole, this amount is multiplied
6339 by the value of the prefix argument---the multiplication looks like this:
6341 @smallexample
6342 @group
6343 (* @var{numeric-value-of-prefix-arg}
6344    @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
6345 @end group
6346 @end smallexample
6348 @noindent
6349 If, for example, the prefix argument is @samp{7}, the one-tenth value
6350 will be multiplied by 7 to give a position 70% of the way through.
6352 @need 1200
6353 The result of all this is that if the accessible portion of the buffer
6354 is large, the @code{goto-char} expression reads like this:
6356 @smallexample
6357 @group
6358 (goto-char (* (prefix-numeric-value arg)
6359               (/ size 10)))
6360 @end group
6361 @end smallexample
6363 This puts the cursor where we want it.
6365 @node Small buffer case,  , Large buffer case, beginning-of-buffer opt arg
6366 @comment  node-name,  next,  previous,  up
6367 @unnumberedsubsubsec What happens in a small buffer
6369 If the buffer contains fewer than 10,000 characters, a slightly
6370 different computation is performed.  You might think this is not
6371 necessary, since the first computation could do the job.  However, in
6372 a small buffer, the first method may not put the cursor on exactly the
6373 desired line; the second method does a better job.
6375 @need 800
6376 The code looks like this:
6378 @c Keep this on one line.
6379 @smallexample
6380 (/ (+ 10 (* size (prefix-numeric-value arg))) 10))
6381 @end smallexample
6383 @need 1200
6384 @noindent
6385 This is code in which you figure out what happens by discovering how the
6386 functions are embedded in parentheses.  It is easier to read if you
6387 reformat it with each expression indented more deeply than its
6388 enclosing expression:
6390 @smallexample
6391 @group
6392   (/
6393    (+ 10
6394       (*
6395        size
6396        (prefix-numeric-value arg)))
6397    10))
6398 @end group
6399 @end smallexample
6401 @need 1200
6402 @noindent
6403 Looking at parentheses, we see that the innermost operation is
6404 @code{(prefix-numeric-value arg)}, which converts the raw argument to
6405 a number.  In the following expression, this number is multiplied by
6406 the size of the accessible portion of the buffer:
6408 @smallexample
6409 (* size (prefix-numeric-value arg))
6410 @end smallexample
6412 @noindent
6413 This multiplication creates a number that may be larger than the size of
6414 the buffer---seven times larger if the argument is 7, for example.  Ten
6415 is then added to this number and finally the large number is divided by
6416 ten to provide a value that is one character larger than the percentage
6417 position in the buffer.
6419 The number that results from all this is passed to @code{goto-char} and
6420 the cursor is moved to that point.
6422 @need 1500
6423 @node beginning-of-buffer complete,  , beginning-of-buffer opt arg, beginning-of-buffer
6424 @comment  node-name,  next,  previous,  up
6425 @subsection The Complete @code{beginning-of-buffer}
6427 @need 1000
6428 Here is the complete text of the @code{beginning-of-buffer} function:
6429 @sp 1
6431 @c In GNU Emacs 22
6432 @smallexample
6433 @group
6434 (defun beginning-of-buffer (&optional arg)
6435   "Move point to the beginning of the buffer;
6436 leave mark at previous position.
6437 With \\[universal-argument] prefix,
6438 do not set mark at previous position.
6439 With numeric arg N,
6440 put point N/10 of the way from the beginning.
6442 If the buffer is narrowed,
6443 this command uses the beginning and size
6444 of the accessible part of the buffer.
6445 @end group
6447 @group
6448 Don't use this command in Lisp programs!
6449 \(goto-char (point-min)) is faster
6450 and avoids clobbering the mark."
6451   (interactive "P")
6452   (or (consp arg)
6453       (and transient-mark-mode mark-active)
6454       (push-mark))
6455 @end group
6456 @group
6457   (let ((size (- (point-max) (point-min))))
6458     (goto-char (if (and arg (not (consp arg)))
6459                    (+ (point-min)
6460                       (if (> size 10000)
6461                           ;; Avoid overflow for large buffer sizes!
6462                           (* (prefix-numeric-value arg)
6463                              (/ size 10))
6464                         (/ (+ 10 (* size (prefix-numeric-value arg))) 10)))
6465                  (point-min))))
6466   (if arg (forward-line 1)))
6467 @end group
6468 @end smallexample
6470 @ignore
6471 From before GNU Emacs 22
6472 @smallexample
6473 @group
6474 (defun beginning-of-buffer (&optional arg)
6475   "Move point to the beginning of the buffer;
6476 leave mark at previous position.
6477 With arg N, put point N/10 of the way
6478 from the true beginning.
6479 @end group
6480 @group
6481 Don't use this in Lisp programs!
6482 \(goto-char (point-min)) is faster
6483 and does not set the mark."
6484   (interactive "P")
6485   (push-mark)
6486 @end group
6487 @group
6488   (goto-char
6489    (if arg
6490        (if (> (buffer-size) 10000)
6491            ;; @r{Avoid overflow for large buffer sizes!}
6492            (* (prefix-numeric-value arg)
6493               (/ (buffer-size) 10))
6494 @end group
6495 @group
6496          (/ (+ 10 (* (buffer-size)
6497                      (prefix-numeric-value arg)))
6498             10))
6499      (point-min)))
6500   (if arg (forward-line 1)))
6501 @end group
6502 @end smallexample
6503 @end ignore
6505 @noindent
6506 Except for two small points, the previous discussion shows how this
6507 function works.  The first point deals with a detail in the
6508 documentation string, and the second point concerns the last line of
6509 the function.
6511 @need 800
6512 In the documentation string, there is reference to an expression:
6514 @smallexample
6515 \\[universal-argument]
6516 @end smallexample
6518 @noindent
6519 A @samp{\\} is used before the first square bracket of this
6520 expression.  This @samp{\\} tells the Lisp interpreter to substitute
6521 whatever key is currently bound to the @samp{[@dots{}]}.  In the case
6522 of @code{universal-argument}, that is usually @kbd{C-u}, but it might
6523 be different.  (@xref{Documentation Tips, , Tips for Documentation
6524 Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
6525 information.)
6527 @need 1200
6528 Finally, the last line of the @code{beginning-of-buffer} command says
6529 to move point to the beginning of the next line if the command is
6530 invoked with an argument:
6532 @smallexample
6533 (if arg (forward-line 1)))
6534 @end smallexample
6536 @noindent
6537 This puts the cursor at the beginning of the first line after the
6538 appropriate tenths position in the buffer.  This is a flourish that
6539 means that the cursor is always located @emph{at least} the requested
6540 tenths of the way through the buffer, which is a nicety that is,
6541 perhaps, not necessary, but which, if it did not occur, would be sure
6542 to draw complaints.
6544 On the other hand, it also means that if you specify the command with
6545 a @kbd{C-u}, but without a number, that is to say, if the `raw prefix
6546 argument' is simply a cons cell, then the command puts you at the
6547 beginning of the second line @dots{}  I don't know whether this is
6548 intended or whether no one has dealt with the code to avoid this
6549 happening.
6551 @node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
6552 @comment  node-name,  next,  previous,  up
6553 @section Review
6555 Here is a brief summary of some of the topics covered in this chapter.
6557 @table @code
6558 @item or
6559 Evaluate each argument in sequence, and return the value of the first
6560 argument that is not @code{nil}; if none return a value that is not
6561 @code{nil}, return @code{nil}.  In brief, return the first true value
6562 of the arguments; return a true value if one @emph{or} any of the
6563 others are true.
6565 @item and
6566 Evaluate each argument in sequence, and if any are @code{nil}, return
6567 @code{nil}; if none are @code{nil}, return the value of the last
6568 argument.  In brief, return a true value only if all the arguments are
6569 true; return a true value if one @emph{and} each of the others is
6570 true.
6572 @item &optional
6573 A keyword used to indicate that an argument to a function definition
6574 is optional; this means that the function can be evaluated without the
6575 argument, if desired.
6577 @item prefix-numeric-value
6578 Convert the `raw prefix argument' produced by @code{(interactive
6579 "P")} to a numeric value.
6581 @item forward-line
6582 Move point forward to the beginning of the next line, or if the argument
6583 is greater than one, forward that many lines.  If it can't move as far
6584 forward as it is supposed to, @code{forward-line} goes forward as far as
6585 it can and then returns a count of the number of additional lines it was
6586 supposed to move but couldn't.
6588 @item erase-buffer
6589 Delete the entire contents of the current buffer.
6591 @item bufferp
6592 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
6593 @end table
6595 @node optional Exercise,  , Second Buffer Related Review, More Complex
6596 @section @code{optional} Argument Exercise
6598 Write an interactive function with an optional argument that tests
6599 whether its argument, a number, is greater than or equal to, or else,
6600 less than the value of @code{fill-column}, and tells you which, in a
6601 message.  However, if you do not pass an argument to the function, use
6602 56 as a default value.
6604 @node Narrowing & Widening, car cdr & cons, More Complex, Top
6605 @comment  node-name,  next,  previous,  up
6606 @chapter Narrowing and Widening
6607 @cindex Focusing attention (narrowing)
6608 @cindex Narrowing
6609 @cindex Widening
6611 Narrowing is a feature of Emacs that makes it possible for you to focus
6612 on a specific part of a buffer, and work without accidentally changing
6613 other parts.  Narrowing is normally disabled since it can confuse
6614 novices.
6616 @menu
6617 * Narrowing advantages::        The advantages of narrowing
6618 * save-restriction::            The @code{save-restriction} special form.
6619 * what-line::                   The number of the line that point is on.
6620 * narrow Exercise::
6621 @end menu
6623 @node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
6624 @ifnottex
6625 @unnumberedsec The Advantages of Narrowing
6626 @end ifnottex
6628 With narrowing, the rest of a buffer is made invisible, as if it weren't
6629 there.  This is an advantage if, for example, you want to replace a word
6630 in one part of a buffer but not in another: you narrow to the part you want
6631 and the replacement is carried out only in that section, not in the rest
6632 of the buffer.  Searches will only work within a narrowed region, not
6633 outside of one, so if you are fixing a part of a document, you can keep
6634 yourself from accidentally finding parts you do not need to fix by
6635 narrowing just to the region you want.
6636 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
6638 However, narrowing does make the rest of the buffer invisible, which
6639 can scare people who inadvertently invoke narrowing and think they
6640 have deleted a part of their file.  Moreover, the @code{undo} command
6641 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
6642 (nor should it), so people can become quite desperate if they do not
6643 know that they can return the rest of a buffer to visibility with the
6644 @code{widen} command.
6645 (The key binding for @code{widen} is @kbd{C-x n w}.)
6647 Narrowing is just as useful to the Lisp interpreter as to a human.
6648 Often, an Emacs Lisp function is designed to work on just part of a
6649 buffer; or conversely, an Emacs Lisp function needs to work on all of a
6650 buffer that has been narrowed.  The @code{what-line} function, for
6651 example, removes the narrowing from a buffer, if it has any narrowing
6652 and when it has finished its job, restores the narrowing to what it was.
6653 On the other hand, the @code{count-lines} function, which is called by
6654 @code{what-line}, uses narrowing to restrict itself to just that portion
6655 of the buffer in which it is interested and then restores the previous
6656 situation.
6658 @node save-restriction, what-line, Narrowing advantages, Narrowing & Widening
6659 @comment  node-name,  next,  previous,  up
6660 @section The @code{save-restriction} Special Form
6661 @findex save-restriction
6663 In Emacs Lisp, you can use the @code{save-restriction} special form to
6664 keep track of whatever narrowing is in effect, if any.  When the Lisp
6665 interpreter meets with @code{save-restriction}, it executes the code
6666 in the body of the @code{save-restriction} expression, and then undoes
6667 any changes to narrowing that the code caused.  If, for example, the
6668 buffer is narrowed and the code that follows @code{save-restriction}
6669 gets rid of the narrowing, @code{save-restriction} returns the buffer
6670 to its narrowed region afterwards.  In the @code{what-line} command,
6671 any narrowing the buffer may have is undone by the @code{widen}
6672 command that immediately follows the @code{save-restriction} command.
6673 Any original narrowing is restored just before the completion of the
6674 function.
6676 @need 1250
6677 The template for a @code{save-restriction} expression is simple:
6679 @smallexample
6680 @group
6681 (save-restriction
6682   @var{body}@dots{} )
6683 @end group
6684 @end smallexample
6686 @noindent
6687 The body of the @code{save-restriction} is one or more expressions that
6688 will be evaluated in sequence by the Lisp interpreter.
6690 Finally, a point to note: when you use both @code{save-excursion} and
6691 @code{save-restriction}, one right after the other, you should use
6692 @code{save-excursion} outermost.  If you write them in reverse order,
6693 you may fail to record narrowing in the buffer to which Emacs switches
6694 after calling @code{save-excursion}.  Thus, when written together,
6695 @code{save-excursion} and @code{save-restriction} should be written
6696 like this:
6698 @smallexample
6699 @group
6700 (save-excursion
6701   (save-restriction
6702     @var{body}@dots{}))
6703 @end group
6704 @end smallexample
6706 In other circumstances, when not written together, the
6707 @code{save-excursion} and @code{save-restriction} special forms must
6708 be written in the order appropriate to the function.
6710 @need 1250
6711 For example,
6713 @smallexample
6714 @group
6715   (save-restriction
6716     (widen)
6717     (save-excursion
6718     @var{body}@dots{}))
6719 @end group
6720 @end smallexample
6722 @ignore
6723 Emacs 22
6724 /usr/local/src/emacs/lisp/simple.el
6726 (defun what-line ()
6727   "Print the current buffer line number and narrowed line number of point."
6728   (interactive)
6729   (let ((start (point-min))
6730         (n (line-number-at-pos)))
6731     (if (= start 1)
6732         (message "Line %d" n)
6733       (save-excursion
6734         (save-restriction
6735           (widen)
6736           (message "line %d (narrowed line %d)"
6737                    (+ n (line-number-at-pos start) -1) n))))))
6739 (defun line-number-at-pos (&optional pos)
6740   "Return (narrowed) buffer line number at position POS.
6741 If POS is nil, use current buffer location.
6742 Counting starts at (point-min), so the value refers
6743 to the contents of the accessible portion of the buffer."
6744   (let ((opoint (or pos (point))) start)
6745     (save-excursion
6746       (goto-char (point-min))
6747       (setq start (point))
6748       (goto-char opoint)
6749       (forward-line 0)
6750       (1+ (count-lines start (point))))))
6752 (defun count-lines (start end)
6753   "Return number of lines between START and END.
6754 This is usually the number of newlines between them,
6755 but can be one more if START is not equal to END
6756 and the greater of them is not at the start of a line."
6757   (save-excursion
6758     (save-restriction
6759       (narrow-to-region start end)
6760       (goto-char (point-min))
6761       (if (eq selective-display t)
6762           (save-match-data
6763             (let ((done 0))
6764               (while (re-search-forward "[\n\C-m]" nil t 40)
6765                 (setq done (+ 40 done)))
6766               (while (re-search-forward "[\n\C-m]" nil t 1)
6767                 (setq done (+ 1 done)))
6768               (goto-char (point-max))
6769               (if (and (/= start end)
6770                        (not (bolp)))
6771                   (1+ done)
6772                 done)))
6773         (- (buffer-size) (forward-line (buffer-size)))))))
6774 @end ignore
6776 @node what-line, narrow Exercise, save-restriction, Narrowing & Widening
6777 @comment  node-name,  next,  previous,  up
6778 @section @code{what-line}
6779 @findex what-line
6780 @cindex Widening, example of
6782 The @code{what-line} command tells you the number of the line in which
6783 the cursor is located.  The function illustrates the use of the
6784 @code{save-restriction} and @code{save-excursion} commands.  Here is the
6785 original text of the function:
6787 @smallexample
6788 @group
6789 (defun what-line ()
6790   "Print the current line number (in the buffer) of point."
6791   (interactive)
6792   (save-restriction
6793     (widen)
6794     (save-excursion
6795       (beginning-of-line)
6796       (message "Line %d"
6797                (1+ (count-lines 1 (point)))))))
6798 @end group
6799 @end smallexample
6801 (In recent versions of GNU Emacs, the @code{what-line} function has
6802 been expanded to tell you your line number in a narrowed buffer as
6803 well as your line number in a widened buffer.  The recent version is
6804 more complex than the version shown here.  If you feel adventurous,
6805 you might want to look at it after figuring out how this version
6806 works.  You will probably need to use @kbd{C-h f}
6807 (@code{describe-function}).  The newer version uses a conditional to
6808 determine whether the buffer has been narrowed.
6810 (Also, it uses @code{line-number-at-pos}, which among other simple
6811 expressions, such as @code{(goto-char (point-min))}, moves point to
6812 the beginning of the current line with @code{(forward-line 0)} rather
6813 than @code{beginning-of-line}.)
6815 The @code{what-line} function as shown here has a documentation line
6816 and is interactive, as you would expect.  The next two lines use the
6817 functions @code{save-restriction} and @code{widen}.
6819 The @code{save-restriction} special form notes whatever narrowing is in
6820 effect, if any, in the current buffer and restores that narrowing after
6821 the code in the body of the @code{save-restriction} has been evaluated.
6823 The @code{save-restriction} special form is followed by @code{widen}.
6824 This function undoes any narrowing the current buffer may have had
6825 when @code{what-line} was called.  (The narrowing that was there is
6826 the narrowing that @code{save-restriction} remembers.)  This widening
6827 makes it possible for the line counting commands to count from the
6828 beginning of the buffer.  Otherwise, they would have been limited to
6829 counting within the accessible region.  Any original narrowing is
6830 restored just before the completion of the function by the
6831 @code{save-restriction} special form.
6833 The call to @code{widen} is followed by @code{save-excursion}, which
6834 saves the location of the cursor (i.e., of point) and of the mark, and
6835 restores them after the code in the body of the @code{save-excursion}
6836 uses the @code{beginning-of-line} function to move point.
6838 (Note that the @code{(widen)} expression comes between the
6839 @code{save-restriction} and @code{save-excursion} special forms.  When
6840 you write the two @code{save- @dots{}} expressions in sequence, write
6841 @code{save-excursion} outermost.)
6843 @need 1200
6844 The last two lines of the @code{what-line} function are functions to
6845 count the number of lines in the buffer and then print the number in the
6846 echo area.
6848 @smallexample
6849 @group
6850 (message "Line %d"
6851          (1+ (count-lines 1 (point)))))))
6852 @end group
6853 @end smallexample
6855 The @code{message} function prints a one-line message at the bottom of
6856 the Emacs screen.  The first argument is inside of quotation marks and
6857 is printed as a string of characters.  However, it may contain a
6858 @samp{%d} expression to print a following argument.  @samp{%d} prints
6859 the argument as a decimal, so the message will say something such as
6860 @samp{Line 243}.
6862 @need 1200
6863 The number that is printed in place of the @samp{%d} is computed by the
6864 last line of the function:
6866 @smallexample
6867 (1+ (count-lines 1 (point)))
6868 @end smallexample
6870 @ignore
6871 GNU Emacs 22
6873 (defun count-lines (start end)
6874   "Return number of lines between START and END.
6875 This is usually the number of newlines between them,
6876 but can be one more if START is not equal to END
6877 and the greater of them is not at the start of a line."
6878   (save-excursion
6879     (save-restriction
6880       (narrow-to-region start end)
6881       (goto-char (point-min))
6882       (if (eq selective-display t)
6883           (save-match-data
6884             (let ((done 0))
6885               (while (re-search-forward "[\n\C-m]" nil t 40)
6886                 (setq done (+ 40 done)))
6887               (while (re-search-forward "[\n\C-m]" nil t 1)
6888                 (setq done (+ 1 done)))
6889               (goto-char (point-max))
6890               (if (and (/= start end)
6891                        (not (bolp)))
6892                   (1+ done)
6893                 done)))
6894         (- (buffer-size) (forward-line (buffer-size)))))))
6895 @end ignore
6897 @noindent
6898 What this does is count the lines from the first position of the
6899 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
6900 one to that number.  (The @code{1+} function adds one to its
6901 argument.)  We add one to it because line 2 has only one line before
6902 it, and @code{count-lines} counts only the lines @emph{before} the
6903 current line.
6905 After @code{count-lines} has done its job, and the message has been
6906 printed in the echo area, the @code{save-excursion} restores point and
6907 mark to their original positions; and @code{save-restriction} restores
6908 the original narrowing, if any.
6910 @node narrow Exercise,  , what-line, Narrowing & Widening
6911 @section Exercise with Narrowing
6913 Write a function that will display the first 60 characters of the
6914 current buffer, even if you have narrowed the buffer to its latter
6915 half so that the first line is inaccessible.  Restore point, mark, and
6916 narrowing.  For this exercise, you need to use a whole potpourri of
6917 functions, including @code{save-restriction}, @code{widen},
6918 @code{goto-char}, @code{point-min}, @code{message}, and
6919 @code{buffer-substring}.
6921 @cindex Properties, mention of @code{buffer-substring-no-properties}
6922 (@code{buffer-substring} is a previously unmentioned function you will
6923 have to investigate yourself; or perhaps you will have to use
6924 @code{buffer-substring-no-properties} or
6925 @code{filter-buffer-substring} @dots{}, yet other functions.  Text
6926 properties are a feature otherwise not discussed here.  @xref{Text
6927 Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
6928 Manual}.)
6930 Additionally, do you really need @code{goto-char} or @code{point-min}?
6931 Or can you write the function without them?
6933 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
6934 @comment  node-name,  next,  previous,  up
6935 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
6936 @findex car, @r{introduced}
6937 @findex cdr, @r{introduced}
6939 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
6940 functions.  The @code{cons} function is used to construct lists, and
6941 the @code{car} and @code{cdr} functions are used to take them apart.
6943 In the walk through of the @code{copy-region-as-kill} function, we
6944 will see @code{cons} as well as two variants on @code{cdr},
6945 namely, @code{setcdr} and @code{nthcdr}.  (@xref{copy-region-as-kill}.)
6947 @menu
6948 * Strange Names::               An historical aside: why the strange names?
6949 * car & cdr::                   Functions for extracting part of a list.
6950 * cons::                        Constructing a list.
6951 * nthcdr::                      Calling @code{cdr} repeatedly.
6952 * nth::
6953 * setcar::                      Changing the first element of a list.
6954 * setcdr::                      Changing the rest of a list.
6955 * cons Exercise::
6956 @end menu
6958 @node Strange Names, car & cdr, car cdr & cons, car cdr & cons
6959 @ifnottex
6960 @unnumberedsec Strange Names
6961 @end ifnottex
6963 The name of the @code{cons} function is not unreasonable: it is an
6964 abbreviation of the word `construct'.  The origins of the names for
6965 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
6966 is an acronym from the phrase `Contents of the Address part of the
6967 Register'; and @code{cdr} (pronounced `could-er') is an acronym from
6968 the phrase `Contents of the Decrement part of the Register'.  These
6969 phrases refer to specific pieces of hardware on the very early
6970 computer on which the original Lisp was developed.  Besides being
6971 obsolete, the phrases have been completely irrelevant for more than 25
6972 years to anyone thinking about Lisp.  Nonetheless, although a few
6973 brave scholars have begun to use more reasonable names for these
6974 functions, the old terms are still in use.  In particular, since the
6975 terms are used in the Emacs Lisp source code, we will use them in this
6976 introduction.
6978 @node car & cdr, cons, Strange Names, car cdr & cons
6979 @comment  node-name,  next,  previous,  up
6980 @section @code{car} and @code{cdr}
6982 The @sc{car} of a list is, quite simply, the first item in the list.
6983 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
6984 @code{rose}.
6986 @need 1200
6987 If you are reading this in Info in GNU Emacs, you can see this by
6988 evaluating the following:
6990 @smallexample
6991 (car '(rose violet daisy buttercup))
6992 @end smallexample
6994 @noindent
6995 After evaluating the expression, @code{rose} will appear in the echo
6996 area.
6998 Clearly, a more reasonable name for the @code{car} function would be
6999 @code{first} and this is often suggested.
7001 @code{car} does not remove the first item from the list; it only reports
7002 what it is.  After @code{car} has been applied to a list, the list is
7003 still the same as it was.  In the jargon, @code{car} is
7004 `non-destructive'.  This feature turns out to be important.
7006 The @sc{cdr} of a list is the rest of the list, that is, the
7007 @code{cdr} function returns the part of the list that follows the
7008 first item.  Thus, while the @sc{car} of the list @code{'(rose violet
7009 daisy buttercup)} is @code{rose}, the rest of the list, the value
7010 returned by the @code{cdr} function, is @code{(violet daisy
7011 buttercup)}.
7013 @need 800
7014 You can see this by evaluating the following in the usual way:
7016 @smallexample
7017 (cdr '(rose violet daisy buttercup))
7018 @end smallexample
7020 @noindent
7021 When you evaluate this, @code{(violet daisy buttercup)} will appear in
7022 the echo area.
7024 Like @code{car}, @code{cdr} does not remove any elements from the
7025 list---it just returns a report of what the second and subsequent
7026 elements are.
7028 Incidentally, in the example, the list of flowers is quoted.  If it were
7029 not, the Lisp interpreter would try to evaluate the list by calling
7030 @code{rose} as a function.  In this example, we do not want to do that.
7032 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
7034 (There is a lesson here: when you name new functions, consider very
7035 carefully what you are doing, since you may be stuck with the names
7036 for far longer than you expect.  The reason this document perpetuates
7037 these names is that the Emacs Lisp source code uses them, and if I did
7038 not use them, you would have a hard time reading the code; but do,
7039 please, try to avoid using these terms yourself.  The people who come
7040 after you will be grateful to you.)
7042 When @code{car} and @code{cdr} are applied to a list made up of symbols,
7043 such as the list @code{(pine fir oak maple)}, the element of the list
7044 returned by the function @code{car} is the symbol @code{pine} without
7045 any parentheses around it.  @code{pine} is the first element in the
7046 list.  However, the @sc{cdr} of the list is a list itself, @code{(fir
7047 oak maple)}, as you can see by evaluating the following expressions in
7048 the usual way:
7050 @smallexample
7051 @group
7052 (car '(pine fir oak maple))
7054 (cdr '(pine fir oak maple))
7055 @end group
7056 @end smallexample
7058 On the other hand, in a list of lists, the first element is itself a
7059 list.  @code{car} returns this first element as a list.  For example,
7060 the following list contains three sub-lists, a list of carnivores, a
7061 list of herbivores and a list of sea mammals:
7063 @smallexample
7064 @group
7065 (car '((lion tiger cheetah)
7066        (gazelle antelope zebra)
7067        (whale dolphin seal)))
7068 @end group
7069 @end smallexample
7071 @noindent
7072 In this example, the first element or @sc{car} of the list is the list of
7073 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
7074 @code{((gazelle antelope zebra) (whale dolphin seal))}.
7076 @smallexample
7077 @group
7078 (cdr '((lion tiger cheetah)
7079        (gazelle antelope zebra)
7080        (whale dolphin seal)))
7081 @end group
7082 @end smallexample
7084 It is worth saying again that @code{car} and @code{cdr} are
7085 non-destructive---that is, they do not modify or change lists to which
7086 they are applied.  This is very important for how they are used.
7088 Also, in the first chapter, in the discussion about atoms, I said that
7089 in Lisp, ``certain kinds of atom, such as an array, can be separated
7090 into parts; but the mechanism for doing this is different from the
7091 mechanism for splitting a list.  As far as Lisp is concerned, the
7092 atoms of a list are unsplittable.''  (@xref{Lisp Atoms}.)  The
7093 @code{car} and @code{cdr} functions are used for splitting lists and
7094 are considered fundamental to Lisp.  Since they cannot split or gain
7095 access to the parts of an array, an array is considered an atom.
7096 Conversely, the other fundamental function, @code{cons}, can put
7097 together or construct a list, but not an array.  (Arrays are handled
7098 by array-specific functions.  @xref{Arrays, , Arrays, elisp, The GNU
7099 Emacs Lisp Reference Manual}.)
7101 @node cons, nthcdr, car & cdr, car cdr & cons
7102 @comment  node-name,  next,  previous,  up
7103 @section @code{cons}
7104 @findex cons, @r{introduced}
7106 The @code{cons} function constructs lists; it is the inverse of
7107 @code{car} and @code{cdr}.  For example, @code{cons} can be used to make
7108 a four element list from the three element list, @code{(fir oak maple)}:
7110 @smallexample
7111 (cons 'pine '(fir oak maple))
7112 @end smallexample
7114 @need 800
7115 @noindent
7116 After evaluating this list, you will see
7118 @smallexample
7119 (pine fir oak maple)
7120 @end smallexample
7122 @noindent
7123 appear in the echo area.  @code{cons} causes the creation of a new
7124 list in which the element is followed by the elements of the original
7125 list.
7127 We often say that `@code{cons} puts a new element at the beginning of
7128 a list; it attaches or pushes elements onto the list', but this
7129 phrasing can be misleading, since @code{cons} does not change an
7130 existing list, but creates a new one.
7132 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
7134 @menu
7135 * Build a list::
7136 * length::                      How to find the length of a list.
7137 @end menu
7139 @node Build a list, length, cons, cons
7140 @ifnottex
7141 @unnumberedsubsec Build a list
7142 @end ifnottex
7144 @code{cons} must have a list to attach to.@footnote{Actually, you can
7145 @code{cons} an element to an atom to produce a dotted pair.  Dotted
7146 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
7147 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.}  You
7148 cannot start from absolutely nothing.  If you are building a list, you
7149 need to provide at least an empty list at the beginning.  Here is a
7150 series of @code{cons} expressions that build up a list of flowers.  If
7151 you are reading this in Info in GNU Emacs, you can evaluate each of
7152 the expressions in the usual way; the value is printed in this text
7153 after @samp{@result{}}, which you may read as `evaluates to'.
7155 @smallexample
7156 @group
7157 (cons 'buttercup ())
7158      @result{} (buttercup)
7159 @end group
7161 @group
7162 (cons 'daisy '(buttercup))
7163      @result{} (daisy buttercup)
7164 @end group
7166 @group
7167 (cons 'violet '(daisy buttercup))
7168      @result{} (violet daisy buttercup)
7169 @end group
7171 @group
7172 (cons 'rose '(violet daisy buttercup))
7173      @result{} (rose violet daisy buttercup)
7174 @end group
7175 @end smallexample
7177 @noindent
7178 In the first example, the empty list is shown as @code{()} and a list
7179 made up of @code{buttercup} followed by the empty list is constructed.
7180 As you can see, the empty list is not shown in the list that was
7181 constructed.  All that you see is @code{(buttercup)}.  The empty list is
7182 not counted as an element of a list because there is nothing in an empty
7183 list.  Generally speaking, an empty list is invisible.
7185 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
7186 two element list by putting @code{daisy} in front of @code{buttercup};
7187 and the third example constructs a three element list by putting
7188 @code{violet} in front of @code{daisy} and @code{buttercup}.
7190 @node length,  , Build a list, cons
7191 @comment  node-name,  next,  previous,  up
7192 @subsection Find the Length of a List: @code{length}
7193 @findex length
7195 You can find out how many elements there are in a list by using the Lisp
7196 function @code{length}, as in the following examples:
7198 @smallexample
7199 @group
7200 (length '(buttercup))
7201      @result{} 1
7202 @end group
7204 @group
7205 (length '(daisy buttercup))
7206      @result{} 2
7207 @end group
7209 @group
7210 (length (cons 'violet '(daisy buttercup)))
7211      @result{} 3
7212 @end group
7213 @end smallexample
7215 @noindent
7216 In the third example, the @code{cons} function is used to construct a
7217 three element list which is then passed to the @code{length} function as
7218 its argument.
7220 @need 1200
7221 We can also use @code{length} to count the number of elements in an
7222 empty list:
7224 @smallexample
7225 @group
7226 (length ())
7227      @result{} 0
7228 @end group
7229 @end smallexample
7231 @noindent
7232 As you would expect, the number of elements in an empty list is zero.
7234 An interesting experiment is to find out what happens if you try to find
7235 the length of no list at all; that is, if you try to call @code{length}
7236 without giving it an argument, not even an empty list:
7238 @smallexample
7239 (length )
7240 @end smallexample
7242 @need 800
7243 @noindent
7244 What you see, if you evaluate this, is the error message
7246 @smallexample
7247 Lisp error: (wrong-number-of-arguments length 0)
7248 @end smallexample
7250 @noindent
7251 This means that the function receives the wrong number of
7252 arguments, zero, when it expects some other number of arguments.  In
7253 this case, one argument is expected, the argument being a list whose
7254 length the function is measuring.  (Note that @emph{one} list is
7255 @emph{one} argument, even if the list has many elements inside it.)
7257 The part of the error message that says @samp{length} is the name of
7258 the function.
7260 @ignore
7261 @code{length} is still a subroutine, but you need C-h f to discover that.
7263 In an earlier version:
7264     This is written with a special notation, @samp{#<subr},
7265     that indicates that the function @code{length} is one of the primitive
7266     functions written in C rather than in Emacs Lisp.  (@samp{subr} is an
7267     abbreviation for `subroutine'.)  @xref{What Is a Function, , What Is a
7268     Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
7269     about subroutines.
7270 @end ignore
7272 @node nthcdr, nth, cons, car cdr & cons
7273 @comment  node-name,  next,  previous,  up
7274 @section @code{nthcdr}
7275 @findex nthcdr
7277 The @code{nthcdr} function is associated with the @code{cdr} function.
7278 What it does is take the @sc{cdr} of a list repeatedly.
7280 If you take the @sc{cdr} of the list @code{(pine fir
7281 oak maple)}, you will be returned the list @code{(fir oak maple)}.  If you
7282 repeat this on what was returned, you will be returned the list
7283 @code{(oak maple)}.  (Of course, repeated @sc{cdr}ing on the original
7284 list will just give you the original @sc{cdr} since the function does
7285 not change the list.  You need to evaluate the @sc{cdr} of the
7286 @sc{cdr} and so on.)  If you continue this, eventually you will be
7287 returned an empty list, which in this case, instead of being shown as
7288 @code{()} is shown as @code{nil}.
7290 @need 1200
7291 For review, here is a series of repeated @sc{cdr}s, the text following
7292 the @samp{@result{}} shows what is returned.
7294 @smallexample
7295 @group
7296 (cdr '(pine fir oak maple))
7297      @result{}(fir oak maple)
7298 @end group
7300 @group
7301 (cdr '(fir oak maple))
7302      @result{} (oak maple)
7303 @end group
7305 @group
7306 (cdr '(oak maple))
7307      @result{}(maple)
7308 @end group
7310 @group
7311 (cdr '(maple))
7312      @result{} nil
7313 @end group
7315 @group
7316 (cdr 'nil)
7317      @result{} nil
7318 @end group
7320 @group
7321 (cdr ())
7322      @result{} nil
7323 @end group
7324 @end smallexample
7326 @need 1200
7327 You can also do several @sc{cdr}s without printing the values in
7328 between, like this:
7330 @smallexample
7331 @group
7332 (cdr (cdr '(pine fir oak maple)))
7333      @result{} (oak maple)
7334 @end group
7335 @end smallexample
7337 @noindent
7338 In this example, the Lisp interpreter evaluates the innermost list first.
7339 The innermost list is quoted, so it just passes the list as it is to the
7340 innermost @code{cdr}.  This @code{cdr} passes a list made up of the
7341 second and subsequent elements of the list to the outermost @code{cdr},
7342 which produces a list composed of the third and subsequent elements of
7343 the original list.  In this example, the @code{cdr} function is repeated
7344 and returns a list that consists of the original list without its
7345 first two elements.
7347 The @code{nthcdr} function does the same as repeating the call to
7348 @code{cdr}.  In the following example, the argument 2 is passed to the
7349 function @code{nthcdr}, along with the list, and the value returned is
7350 the list without its first two items, which is exactly the same
7351 as repeating @code{cdr} twice on the list:
7353 @smallexample
7354 @group
7355 (nthcdr 2 '(pine fir oak maple))
7356      @result{} (oak maple)
7357 @end group
7358 @end smallexample
7360 @need 1200
7361 Using the original four element list, we can see what happens when
7362 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
7363 and 5:
7365 @smallexample
7366 @group
7367 ;; @r{Leave the list as it was.}
7368 (nthcdr 0 '(pine fir oak maple))
7369      @result{} (pine fir oak maple)
7370 @end group
7372 @group
7373 ;; @r{Return a copy without the first element.}
7374 (nthcdr 1 '(pine fir oak maple))
7375      @result{} (fir oak maple)
7376 @end group
7378 @group
7379 ;; @r{Return a copy of the list without three elements.}
7380 (nthcdr 3 '(pine fir oak maple))
7381      @result{} (maple)
7382 @end group
7384 @group
7385 ;; @r{Return a copy lacking all four elements.}
7386 (nthcdr 4 '(pine fir oak maple))
7387      @result{} nil
7388 @end group
7390 @group
7391 ;; @r{Return a copy lacking all elements.}
7392 (nthcdr 5 '(pine fir oak maple))
7393      @result{} nil
7394 @end group
7395 @end smallexample
7397 @node nth, setcar, nthcdr, car cdr & cons
7398 @comment  node-name,  next,  previous,  up
7399 @section @code{nth}
7400 @findex nth
7402 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
7403 The @code{nth} function takes the @sc{car} of the result returned by
7404 @code{nthcdr}.  It returns the Nth element of the list.
7406 @need 1500
7407 Thus, if it were not defined in C for speed, the definition of
7408 @code{nth} would be:
7410 @smallexample
7411 @group
7412 (defun nth (n list)
7413   "Returns the Nth element of LIST.
7414 N counts from zero.  If LIST is not that long, nil is returned."
7415   (car (nthcdr n list)))
7416 @end group
7417 @end smallexample
7419 @noindent
7420 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
7421 but its definition was redone in C in the 1980s.)
7423 The @code{nth} function returns a single element of a list.
7424 This can be very convenient.
7426 Note that the elements are numbered from zero, not one.  That is to
7427 say, the first element of a list, its @sc{car} is the zeroth element.
7428 This is called `zero-based' counting and often bothers people who
7429 are accustomed to the first element in a list being number one, which
7430 is `one-based'.
7432 @need 1250
7433 For example:
7435 @smallexample
7436 @group
7437 (nth 0 '("one" "two" "three"))
7438     @result{} "one"
7440 (nth 1 '("one" "two" "three"))
7441     @result{} "two"
7442 @end group
7443 @end smallexample
7445 It is worth mentioning that @code{nth}, like @code{nthcdr} and
7446 @code{cdr}, does not change the original list---the function is
7447 non-destructive.  This is in sharp contrast to the @code{setcar} and
7448 @code{setcdr} functions.
7450 @node setcar, setcdr, nth, car cdr & cons
7451 @comment  node-name,  next,  previous,  up
7452 @section @code{setcar}
7453 @findex setcar
7455 As you might guess from their names, the @code{setcar} and @code{setcdr}
7456 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
7457 They actually change the original list, unlike @code{car} and @code{cdr}
7458 which leave the original list as it was.  One way to find out how this
7459 works is to experiment.  We will start with the @code{setcar} function.
7461 @need 1200
7462 First, we can make a list and then set the value of a variable to the
7463 list, using the @code{setq} function.  Here is a list of animals:
7465 @smallexample
7466 (setq animals '(antelope giraffe lion tiger))
7467 @end smallexample
7469 @noindent
7470 If you are reading this in Info inside of GNU Emacs, you can evaluate
7471 this expression in the usual fashion, by positioning the cursor after
7472 the expression and typing @kbd{C-x C-e}.  (I'm doing this right here
7473 as I write this.  This is one of the advantages of having the
7474 interpreter built into the computing environment.  Incidentally, when
7475 there is nothing on the line after the final parentheses, such as a
7476 comment, point can be on the next line.  Thus, if your cursor is in
7477 the first column of the next line, you do not need to move it.
7478 Indeed, Emacs permits any amount of white space after the final
7479 parenthesis.)
7481 @need 1200
7482 When we evaluate the variable @code{animals}, we see that it is bound to
7483 the list @code{(antelope giraffe lion tiger)}:
7485 @smallexample
7486 @group
7487 animals
7488      @result{} (antelope giraffe lion tiger)
7489 @end group
7490 @end smallexample
7492 @noindent
7493 Put another way, the variable @code{animals} points to the list
7494 @code{(antelope giraffe lion tiger)}.
7496 Next, evaluate the function @code{setcar} while passing it two
7497 arguments, the variable @code{animals} and the quoted symbol
7498 @code{hippopotamus}; this is done by writing the three element list
7499 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
7500 usual fashion:
7502 @smallexample
7503 (setcar animals 'hippopotamus)
7504 @end smallexample
7506 @need 1200
7507 @noindent
7508 After evaluating this expression, evaluate the variable @code{animals}
7509 again.  You will see that the list of animals has changed:
7511 @smallexample
7512 @group
7513 animals
7514      @result{} (hippopotamus giraffe lion tiger)
7515 @end group
7516 @end smallexample
7518 @noindent
7519 The first element on the list, @code{antelope} is replaced by
7520 @code{hippopotamus}.
7522 So we can see that @code{setcar} did not add a new element to the list
7523 as @code{cons} would have; it replaced @code{antelope} with
7524 @code{hippopotamus}; it @emph{changed} the list.
7526 @node setcdr, cons Exercise, setcar, car cdr & cons
7527 @comment  node-name,  next,  previous,  up
7528 @section @code{setcdr}
7529 @findex setcdr
7531 The @code{setcdr} function is similar to the @code{setcar} function,
7532 except that the function replaces the second and subsequent elements of
7533 a list rather than the first element.
7535 (To see how to change the last element of a list, look ahead to
7536 @ref{kill-new function, , The @code{kill-new} function}, which uses
7537 the @code{nthcdr} and @code{setcdr} functions.)
7539 @need 1200
7540 To see how this works, set the value of the variable to a list of
7541 domesticated animals by evaluating the following expression:
7543 @smallexample
7544 (setq domesticated-animals '(horse cow sheep goat))
7545 @end smallexample
7547 @need 1200
7548 @noindent
7549 If you now evaluate the list, you will be returned the list
7550 @code{(horse cow sheep goat)}:
7552 @smallexample
7553 @group
7554 domesticated-animals
7555      @result{} (horse cow sheep goat)
7556 @end group
7557 @end smallexample
7559 @need 1200
7560 Next, evaluate @code{setcdr} with two arguments, the name of the
7561 variable which has a list as its value, and the list to which the
7562 @sc{cdr} of the first list will be set;
7564 @smallexample
7565 (setcdr domesticated-animals '(cat dog))
7566 @end smallexample
7568 @noindent
7569 If you evaluate this expression, the list @code{(cat dog)} will appear
7570 in the echo area.  This is the value returned by the function.  The
7571 result we are interested in is the ``side effect'', which we can see by
7572 evaluating the variable @code{domesticated-animals}:
7574 @smallexample
7575 @group
7576 domesticated-animals
7577      @result{} (horse cat dog)
7578 @end group
7579 @end smallexample
7581 @noindent
7582 Indeed, the list is changed from @code{(horse cow sheep goat)} to
7583 @code{(horse cat dog)}.  The @sc{cdr} of the list is changed from
7584 @code{(cow sheep goat)} to @code{(cat dog)}.
7586 @node cons Exercise,  , setcdr, car cdr & cons
7587 @section Exercise
7589 Construct a list of four birds by evaluating several expressions with
7590 @code{cons}.  Find out what happens when you @code{cons} a list onto
7591 itself.  Replace the first element of the list of four birds with a
7592 fish.  Replace the rest of that list with a list of other fish.
7594 @node Cutting & Storing Text, List Implementation, car cdr & cons, Top
7595 @comment  node-name,  next,  previous,  up
7596 @chapter Cutting and Storing Text
7597 @cindex Cutting and storing text
7598 @cindex Storing and cutting text
7599 @cindex Killing text
7600 @cindex Clipping text
7601 @cindex Erasing text
7602 @cindex Deleting text
7604 Whenever you cut or clip text out of a buffer with a `kill' command in
7605 GNU Emacs, it is stored in a list and you can bring it back with a
7606 `yank' command.
7608 (The use of the word `kill' in Emacs for processes which specifically
7609 @emph{do not} destroy the values of the entities is an unfortunate
7610 historical accident.  A much more appropriate word would be `clip' since
7611 that is what the kill commands do; they clip text out of a buffer and
7612 put it into storage from which it can be brought back.  I have often
7613 been tempted to replace globally all occurrences of `kill' in the Emacs
7614 sources with `clip' and all occurrences of `killed' with `clipped'.)
7616 @menu
7617 * Storing Text::                Text is stored in a list.
7618 * zap-to-char::                 Cutting out text up to a character.
7619 * kill-region::                 Cutting text out of a region.
7620 * copy-region-as-kill::         A definition for copying text.
7621 * Digression into C::           Minor note on C programming language macros.
7622 * defvar::                      How to give a variable an initial value.
7623 * cons & search-fwd Review::
7624 * search Exercises::
7625 @end menu
7627 @node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text
7628 @ifnottex
7629 @unnumberedsec Storing Text in a List
7630 @end ifnottex
7632 When text is cut out of a buffer, it is stored on a list.  Successive
7633 pieces of text are stored on the list successively, so the list might
7634 look like this:
7636 @smallexample
7637 ("a piece of text" "previous piece")
7638 @end smallexample
7640 @need 1200
7641 @noindent
7642 The function @code{cons} can be used to create a new list from a piece
7643 of text (an `atom', to use the jargon) and an existing list, like
7644 this:
7646 @smallexample
7647 @group
7648 (cons "another piece"
7649       '("a piece of text" "previous piece"))
7650 @end group
7651 @end smallexample
7653 @need 1200
7654 @noindent
7655 If you evaluate this expression, a list of three elements will appear in
7656 the echo area:
7658 @smallexample
7659 ("another piece" "a piece of text" "previous piece")
7660 @end smallexample
7662 With the @code{car} and @code{nthcdr} functions, you can retrieve
7663 whichever piece of text you want.  For example, in the following code,
7664 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
7665 and the @code{car} returns the first element of that remainder---the
7666 second element of the original list:
7668 @smallexample
7669 @group
7670 (car (nthcdr 1 '("another piece"
7671                  "a piece of text"
7672                  "previous piece")))
7673      @result{} "a piece of text"
7674 @end group
7675 @end smallexample
7677 The actual functions in Emacs are more complex than this, of course.
7678 The code for cutting and retrieving text has to be written so that
7679 Emacs can figure out which element in the list you want---the first,
7680 second, third, or whatever.  In addition, when you get to the end of
7681 the list, Emacs should give you the first element of the list, rather
7682 than nothing at all.
7684 The list that holds the pieces of text is called the @dfn{kill ring}.
7685 This chapter leads up to a description of the kill ring and how it is
7686 used by first tracing how the @code{zap-to-char} function works.  This
7687 function uses (or `calls') a function that invokes a function that
7688 manipulates the kill ring.  Thus, before reaching the mountains, we
7689 climb the foothills.
7691 A subsequent chapter describes how text that is cut from the buffer is
7692 retrieved.  @xref{Yanking, , Yanking Text Back}.
7694 @node zap-to-char, kill-region, Storing Text, Cutting & Storing Text
7695 @comment  node-name,  next,  previous,  up
7696 @section @code{zap-to-char}
7697 @findex zap-to-char
7699 The @code{zap-to-char} function changed little between GNU Emacs
7700 version 19 and GNU Emacs version 22.  However, @code{zap-to-char}
7701 calls another function, @code{kill-region}, which enjoyed a major
7702 rewrite.
7704 The @code{kill-region} function in Emacs 19 is complex, but does not
7705 use code that is important at this time.  We will skip it.
7707 The @code{kill-region} function in Emacs 22 is easier to read than the
7708 same function in Emacs 19 and introduces a very important concept,
7709 that of error handling.  We will walk through the function.
7711 But first, let us look at the interactive @code{zap-to-char} function.
7713 @menu
7714 * Complete zap-to-char::        The complete implementation.
7715 * zap-to-char interactive::     A three part interactive expression.
7716 * zap-to-char body::            A short overview.
7717 * search-forward::              How to search for a string.
7718 * progn::                       The @code{progn} special form.
7719 * Summing up zap-to-char::      Using @code{point} and @code{search-forward}.
7720 @end menu
7722 @node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
7723 @ifnottex
7724 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
7725 @end ifnottex
7727 The @code{zap-to-char} function removes the text in the region between
7728 the location of the cursor (i.e., of point) up to and including the
7729 next occurrence of a specified character.  The text that
7730 @code{zap-to-char} removes is put in the kill ring; and it can be
7731 retrieved from the kill ring by typing @kbd{C-y} (@code{yank}).  If
7732 the command is given an argument, it removes text through that number
7733 of occurrences.  Thus, if the cursor were at the beginning of this
7734 sentence and the character were @samp{s}, @samp{Thus} would be
7735 removed.  If the argument were two, @samp{Thus, if the curs} would be
7736 removed, up to and including the @samp{s} in @samp{cursor}.
7738 If the specified character is not found, @code{zap-to-char} will say
7739 ``Search failed'', tell you the character you typed, and not remove
7740 any text.
7742 In order to determine how much text to remove, @code{zap-to-char} uses
7743 a search function.  Searches are used extensively in code that
7744 manipulates text, and we will focus attention on them as well as on the
7745 deletion command.
7747 @ignore
7748 @c GNU Emacs version 19
7749 (defun zap-to-char (arg char)  ; version 19 implementation
7750   "Kill up to and including ARG'th occurrence of CHAR.
7751 Goes backward if ARG is negative; error if CHAR not found."
7752   (interactive "*p\ncZap to char: ")
7753   (kill-region (point)
7754                (progn
7755                  (search-forward
7756                   (char-to-string char) nil nil arg)
7757                  (point))))
7758 @end ignore
7760 @need 1250
7761 Here is the complete text of the version 22 implementation of the function:
7763 @c GNU Emacs 22
7764 @smallexample
7765 @group
7766 (defun zap-to-char (arg char)
7767   "Kill up to and including ARG'th occurrence of CHAR.
7768 Case is ignored if `case-fold-search' is non-nil in the current buffer.
7769 Goes backward if ARG is negative; error if CHAR not found."
7770   (interactive "p\ncZap to char: ")
7771   (if (char-table-p translation-table-for-input)
7772       (setq char (or (aref translation-table-for-input char) char)))
7773   (kill-region (point) (progn
7774                          (search-forward (char-to-string char) nil nil arg)
7775                          (point))))
7776 @end group
7777 @end smallexample
7779 The documentation is thorough.  You do need to know the jargon meaning
7780 of the word `kill'.
7782 @node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char
7783 @comment  node-name,  next,  previous,  up
7784 @subsection The @code{interactive} Expression
7786 @need 800
7787 The interactive expression in the @code{zap-to-char} command looks like
7788 this:
7790 @smallexample
7791 (interactive "p\ncZap to char: ")
7792 @end smallexample
7794 The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
7795 two different things.  First, and most simply, is the @samp{p}.
7796 This part is separated from the next part by a newline, @samp{\n}.
7797 The @samp{p} means that the first argument to the function will be
7798 passed the value of a `processed prefix'.  The prefix argument is
7799 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number.  If
7800 the function is called interactively without a prefix, 1 is passed to
7801 this argument.
7803 The second part of @code{"p\ncZap to char:@: "} is
7804 @samp{cZap to char:@:  }.  In this part, the lower case @samp{c}
7805 indicates that @code{interactive} expects a prompt and that the
7806 argument will be a character.  The prompt follows the @samp{c} and is
7807 the string @samp{Zap to char:@: } (with a space after the colon to
7808 make it look good).
7810 What all this does is prepare the arguments to @code{zap-to-char} so they
7811 are of the right type, and give the user a prompt.
7813 In a read-only buffer, the @code{zap-to-char} function copies the text
7814 to the kill ring, but does not remove it.  The echo area displays a
7815 message saying that the buffer is read-only.  Also, the terminal may
7816 beep or blink at you.
7818 @node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
7819 @comment  node-name,  next,  previous,  up
7820 @subsection The Body of @code{zap-to-char}
7822 The body of the @code{zap-to-char} function contains the code that
7823 kills (that is, removes) the text in the region from the current
7824 position of the cursor up to and including the specified character.
7826 The first part of the code looks like this:
7828 @smallexample
7829 (if (char-table-p translation-table-for-input)
7830     (setq char (or (aref translation-table-for-input char) char)))
7831 (kill-region (point) (progn
7832                        (search-forward (char-to-string char) nil nil arg)
7833                        (point)))
7834 @end smallexample
7836 @noindent
7837 @code{char-table-p} is an hitherto unseen function.  It determines
7838 whether its argument is a character table.  When it is, it sets the
7839 character passed to @code{zap-to-char} to one of them, if that
7840 character exists, or to the character itself.  (This becomes important
7841 for certain characters in non-European languages.  The @code{aref}
7842 function extracts an element from an array.  It is an array-specific
7843 function that is not described in this document.  @xref{Arrays, ,
7844 Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
7846 @noindent
7847 @code{(point)} is the current position of the cursor.
7849 The next part of the code is an expression using @code{progn}.  The body
7850 of the @code{progn} consists of calls to @code{search-forward} and
7851 @code{point}.
7853 It is easier to understand how @code{progn} works after learning about
7854 @code{search-forward}, so we will look at @code{search-forward} and
7855 then at @code{progn}.
7857 @node search-forward, progn, zap-to-char body, zap-to-char
7858 @comment  node-name,  next,  previous,  up
7859 @subsection The @code{search-forward} Function
7860 @findex search-forward
7862 The @code{search-forward} function is used to locate the
7863 zapped-for-character in @code{zap-to-char}.  If the search is
7864 successful, @code{search-forward} leaves point immediately after the
7865 last character in the target string.  (In @code{zap-to-char}, the
7866 target string is just one character long.  @code{zap-to-char} uses the
7867 function @code{char-to-string} to ensure that the computer treats that
7868 character as a string.)  If the search is backwards,
7869 @code{search-forward} leaves point just before the first character in
7870 the target.  Also, @code{search-forward} returns @code{t} for true.
7871 (Moving point is therefore a `side effect'.)
7873 @need 1250
7874 In @code{zap-to-char}, the @code{search-forward} function looks like this:
7876 @smallexample
7877 (search-forward (char-to-string char) nil nil arg)
7878 @end smallexample
7880 The @code{search-forward} function takes four arguments:
7882 @enumerate
7883 @item
7884 The first argument is the target, what is searched for.  This must be a
7885 string, such as @samp{"z"}.
7887 As it happens, the argument passed to @code{zap-to-char} is a single
7888 character.  Because of the way computers are built, the Lisp
7889 interpreter may treat a single character as being different from a
7890 string of characters.  Inside the computer, a single character has a
7891 different electronic format than a string of one character.  (A single
7892 character can often be recorded in the computer using exactly one
7893 byte; but a string may be longer, and the computer needs to be ready
7894 for this.)  Since the @code{search-forward} function searches for a
7895 string, the character that the @code{zap-to-char} function receives as
7896 its argument must be converted inside the computer from one format to
7897 the other; otherwise the @code{search-forward} function will fail.
7898 The @code{char-to-string} function is used to make this conversion.
7900 @item
7901 The second argument bounds the search; it is specified as a position in
7902 the buffer.  In this case, the search can go to the end of the buffer,
7903 so no bound is set and the second argument is @code{nil}.
7905 @item
7906 The third argument tells the function what it should do if the search
7907 fails---it can signal an error (and print a message) or it can return
7908 @code{nil}.  A @code{nil} as the third argument causes the function to
7909 signal an error when the search fails.
7911 @item
7912 The fourth argument to @code{search-forward} is the repeat count---how
7913 many occurrences of the string to look for.  This argument is optional
7914 and if the function is called without a repeat count, this argument is
7915 passed the value 1.  If this argument is negative, the search goes
7916 backwards.
7917 @end enumerate
7919 @need 800
7920 In template form, a @code{search-forward} expression looks like this:
7922 @smallexample
7923 @group
7924 (search-forward "@var{target-string}"
7925                 @var{limit-of-search}
7926                 @var{what-to-do-if-search-fails}
7927                 @var{repeat-count})
7928 @end group
7929 @end smallexample
7931 We will look at @code{progn} next.
7933 @node progn, Summing up zap-to-char, search-forward, zap-to-char
7934 @comment  node-name,  next,  previous,  up
7935 @subsection The @code{progn} Special Form
7936 @findex progn
7938 @code{progn} is a special form that causes each of its arguments to be
7939 evaluated in sequence and then returns the value of the last one.  The
7940 preceding expressions are evaluated only for the side effects they
7941 perform.  The values produced by them are discarded.
7943 @need 800
7944 The template for a @code{progn} expression is very simple:
7946 @smallexample
7947 @group
7948 (progn
7949   @var{body}@dots{})
7950 @end group
7951 @end smallexample
7953 In @code{zap-to-char}, the @code{progn} expression has to do two things:
7954 put point in exactly the right position; and return the location of
7955 point so that @code{kill-region} will know how far to kill to.
7957 The first argument to the @code{progn} is @code{search-forward}.  When
7958 @code{search-forward} finds the string, the function leaves point
7959 immediately after the last character in the target string.  (In this
7960 case the target string is just one character long.)  If the search is
7961 backwards, @code{search-forward} leaves point just before the first
7962 character in the target.  The movement of point is a side effect.
7964 The second and last argument to @code{progn} is the expression
7965 @code{(point)}.  This expression returns the value of point, which in
7966 this case will be the location to which it has been moved by
7967 @code{search-forward}.  (In the source, a line that tells the function
7968 to go to the previous character, if it is going forward, was commented
7969 out in 1999; I don't remember whether that feature or mis-feature was
7970 ever a part of the distributed source.)  The value of @code{point} is
7971 returned by the @code{progn} expression and is passed to
7972 @code{kill-region} as @code{kill-region}'s second argument.
7974 @node Summing up zap-to-char,  , progn, zap-to-char
7975 @comment  node-name,  next,  previous,  up
7976 @subsection Summing up @code{zap-to-char}
7978 Now that we have seen how @code{search-forward} and @code{progn} work,
7979 we can see how the @code{zap-to-char} function works as a whole.
7981 The first argument to @code{kill-region} is the position of the cursor
7982 when the @code{zap-to-char} command is given---the value of point at
7983 that time.  Within the @code{progn}, the search function then moves
7984 point to just after the zapped-to-character and @code{point} returns the
7985 value of this location.  The @code{kill-region} function puts together
7986 these two values of point, the first one as the beginning of the region
7987 and the second one as the end of the region, and removes the region.
7989 The @code{progn} special form is necessary because the
7990 @code{kill-region} command takes two arguments; and it would fail if
7991 @code{search-forward} and @code{point} expressions were written in
7992 sequence as two additional arguments.  The @code{progn} expression is
7993 a single argument to @code{kill-region} and returns the one value that
7994 @code{kill-region} needs for its second argument.
7996 @node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text
7997 @comment  node-name,  next,  previous,  up
7998 @section @code{kill-region}
7999 @findex kill-region
8001 The @code{zap-to-char} function uses the @code{kill-region} function.
8002 This function clips text from a region and copies that text to
8003 the kill ring, from which it may be retrieved.
8005 @ignore
8006 GNU Emacs 22:
8008 (defun kill-region (beg end &optional yank-handler)
8009   "Kill (\"cut\") text between point and mark.
8010 This deletes the text from the buffer and saves it in the kill ring.
8011 The command \\[yank] can retrieve it from there.
8012 \(If you want to kill and then yank immediately, use \\[kill-ring-save].)
8014 If you want to append the killed region to the last killed text,
8015 use \\[append-next-kill] before \\[kill-region].
8017 If the buffer is read-only, Emacs will beep and refrain from deleting
8018 the text, but put the text in the kill ring anyway.  This means that
8019 you can use the killing commands to copy text from a read-only buffer.
8021 This is the primitive for programs to kill text (as opposed to deleting it).
8022 Supply two arguments, character positions indicating the stretch of text
8023  to be killed.
8024 Any command that calls this function is a \"kill command\".
8025 If the previous command was also a kill command,
8026 the text killed this time appends to the text killed last time
8027 to make one entry in the kill ring.
8029 In Lisp code, optional third arg YANK-HANDLER, if non-nil,
8030 specifies the yank-handler text property to be set on the killed
8031 text.  See `insert-for-yank'."
8032   ;; Pass point first, then mark, because the order matters
8033   ;; when calling kill-append.
8034   (interactive (list (point) (mark)))
8035   (unless (and beg end)
8036     (error "The mark is not set now, so there is no region"))
8037   (condition-case nil
8038       (let ((string (filter-buffer-substring beg end t)))
8039         (when string                        ;STRING is nil if BEG = END
8040           ;; Add that string to the kill ring, one way or another.
8041           (if (eq last-command 'kill-region)
8042               (kill-append string (< end beg) yank-handler)
8043             (kill-new string nil yank-handler)))
8044         (when (or string (eq last-command 'kill-region))
8045           (setq this-command 'kill-region))
8046         nil)
8047     ((buffer-read-only text-read-only)
8048      ;; The code above failed because the buffer, or some of the characters
8049      ;; in the region, are read-only.
8050      ;; We should beep, in case the user just isn't aware of this.
8051      ;; However, there's no harm in putting
8052      ;; the region's text in the kill ring, anyway.
8053      (copy-region-as-kill beg end)
8054      ;; Set this-command now, so it will be set even if we get an error.
8055      (setq this-command 'kill-region)
8056      ;; This should barf, if appropriate, and give us the correct error.
8057      (if kill-read-only-ok
8058          (progn (message "Read only text copied to kill ring") nil)
8059        ;; Signal an error if the buffer is read-only.
8060        (barf-if-buffer-read-only)
8061        ;; If the buffer isn't read-only, the text is.
8062        (signal 'text-read-only (list (current-buffer)))))))
8063 @end ignore
8065 The Emacs 22 version of that function uses @code{condition-case} and
8066 @code{copy-region-as-kill}, both of which we will explain.
8067 @code{condition-case} is an important special form.
8069 In essence, the @code{kill-region} function calls
8070 @code{condition-case}, which takes three arguments.  In this function,
8071 the first argument does nothing.  The second argument contains the
8072 code that does the work when all goes well.  The third argument
8073 contains the code that is called in the event of an error.
8075 @menu
8076 * Complete kill-region::        The function definition.
8077 * condition-case::              Dealing with a problem.
8078 * Lisp macro::
8079 @end menu
8081 @node Complete kill-region, condition-case, kill-region, kill-region
8082 @ifnottex
8083 @unnumberedsubsec The Complete @code{kill-region} Definition
8084 @end ifnottex
8086 @need 1200
8087 We will go through the @code{condition-case} code in a moment.  First,
8088 let us look at the definition of @code{kill-region}, with comments
8089 added:
8091 @c GNU Emacs 22:
8092 @smallexample
8093 @group
8094 (defun kill-region (beg end)
8095   "Kill (\"cut\") text between point and mark.
8096 This deletes the text from the buffer and saves it in the kill ring.
8097 The command \\[yank] can retrieve it from there. @dots{} "
8098 @end group
8100 @group
8101   ;; @bullet{} Since order matters, pass point first.
8102   (interactive (list (point) (mark)))
8103   ;; @bullet{} And tell us if we cannot cut the text.
8104   ;; `unless' is an `if' without a then-part.
8105   (unless (and beg end)
8106     (error "The mark is not set now, so there is no region"))
8107 @end group
8109 @group
8110   ;; @bullet{} `condition-case' takes three arguments.
8111   ;;    If the first argument is nil, as it is here,
8112   ;;    information about the error signal is not
8113   ;;    stored for use by another function.
8114   (condition-case nil
8115 @end group
8117 @group
8118       ;; @bullet{} The second argument to `condition-case' tells the
8119       ;;    Lisp interpreter what to do when all goes well.
8120 @end group
8122 @group
8123       ;;    It starts with a `let' function that extracts the string
8124       ;;    and tests whether it exists.  If so (that is what the
8125       ;;    `when' checks), it calls an `if' function that determines
8126       ;;    whether the previous command was another call to
8127       ;;    `kill-region'; if it was, then the new text is appended to
8128       ;;    the previous text; if not, then a different function,
8129       ;;    `kill-new', is called.
8130 @end group
8132 @group
8133       ;;    The `kill-append' function concatenates the new string and
8134       ;;    the old.  The `kill-new' function inserts text into a new
8135       ;;    item in the kill ring.
8136 @end group
8138 @group
8139       ;;    `when' is an `if' without an else-part.  The second `when'
8140       ;;    again checks whether the current string exists; in
8141       ;;    addition, it checks whether the previous command was
8142       ;;    another call to `kill-region'.  If one or the other
8143       ;;    condition is true, then it sets the current command to
8144       ;;    be `kill-region'.
8145 @end group
8146 @group
8147       (let ((string (filter-buffer-substring beg end t)))
8148         (when string                    ;STRING is nil if BEG = END
8149           ;; Add that string to the kill ring, one way or another.
8150           (if (eq last-command 'kill-region)
8151 @end group
8152 @group
8153               ;;    @minus{} `yank-handler' is an optional argument to
8154               ;;    `kill-region' that tells the `kill-append' and
8155               ;;    `kill-new' functions how deal with properties
8156               ;;    added to the text, such as `bold' or `italics'.
8157               (kill-append string (< end beg) yank-handler)
8158             (kill-new string nil yank-handler)))
8159         (when (or string (eq last-command 'kill-region))
8160           (setq this-command 'kill-region))
8161         nil)
8162 @end group
8164 @group
8165     ;;  @bullet{} The third argument to `condition-case' tells the interpreter
8166     ;;    what to do with an error.
8167 @end group
8168 @group
8169     ;;    The third argument has a conditions part and a body part.
8170     ;;    If the conditions are met (in this case,
8171     ;;             if text or buffer are read-only)
8172     ;;    then the body is executed.
8173 @end group
8174 @group
8175     ;;    The first part of the third argument is the following:
8176     ((buffer-read-only text-read-only) ;; the if-part
8177      ;; @dots{}  the then-part
8178      (copy-region-as-kill beg end)
8179 @end group
8180 @group
8181      ;;    Next, also as part of the then-part, set this-command, so
8182      ;;    it will be set in an error
8183      (setq this-command 'kill-region)
8184      ;;    Finally, in the then-part, send a message if you may copy
8185      ;;    the text to the kill ring without signally an error, but
8186      ;;    don't if you may not.
8187 @end group
8188 @group
8189      (if kill-read-only-ok
8190          (progn (message "Read only text copied to kill ring") nil)
8191        (barf-if-buffer-read-only)
8192        ;; If the buffer isn't read-only, the text is.
8193        (signal 'text-read-only (list (current-buffer)))))
8194 @end group
8195 @end smallexample
8197 @ignore
8198 @c v 21
8199 @smallexample
8200 @group
8201 (defun kill-region (beg end)
8202   "Kill between point and mark.
8203 The text is deleted but saved in the kill ring."
8204   (interactive "r")
8205 @end group
8207 @group
8208   ;; 1. `condition-case' takes three arguments.
8209   ;;    If the first argument is nil, as it is here,
8210   ;;    information about the error signal is not
8211   ;;    stored for use by another function.
8212   (condition-case nil
8213 @end group
8215 @group
8216       ;; 2. The second argument to `condition-case'
8217       ;;    tells the Lisp interpreter what to do when all goes well.
8218 @end group
8220 @group
8221       ;;    The `delete-and-extract-region' function usually does the
8222       ;;    work.  If the beginning and ending of the region are both
8223       ;;    the same, then the variable `string' will be empty, or nil
8224       (let ((string (delete-and-extract-region beg end)))
8225 @end group
8227 @group
8228         ;; `when' is an `if' clause that cannot take an `else-part'.
8229         ;; Emacs normally sets the value of `last-command' to the
8230         ;; previous command.
8231 @end group
8232 @group
8233         ;; `kill-append' concatenates the new string and the old.
8234         ;; `kill-new' inserts text into a new item in the kill ring.
8235         (when string
8236           (if (eq last-command 'kill-region)
8237               ;; if true, prepend string
8238               (kill-append string (< end beg))
8239             (kill-new string)))
8240         (setq this-command 'kill-region))
8241 @end group
8243 @group
8244     ;; 3. The third argument to `condition-case' tells the interpreter
8245     ;;    what to do with an error.
8246 @end group
8247 @group
8248     ;;    The third argument has a conditions part and a body part.
8249     ;;    If the conditions are met (in this case,
8250     ;;             if text or buffer are read-only)
8251     ;;    then the body is executed.
8252 @end group
8253 @group
8254     ((buffer-read-only text-read-only) ;; this is the if-part
8255      ;; then...
8256      (copy-region-as-kill beg end)
8257 @end group
8258 @group
8259      (if kill-read-only-ok            ;; usually this variable is nil
8260          (message "Read only text copied to kill ring")
8261        ;; or else, signal an error if the buffer is read-only;
8262        (barf-if-buffer-read-only)
8263        ;; and, in any case, signal that the text is read-only.
8264        (signal 'text-read-only (list (current-buffer)))))))
8265 @end group
8266 @end smallexample
8267 @end ignore
8269 @node condition-case, Lisp macro, Complete kill-region, kill-region
8270 @comment  node-name,  next,  previous,  up
8271 @subsection @code{condition-case}
8272 @findex condition-case
8274 As we have seen earlier (@pxref{Making Errors, , Generate an Error
8275 Message}), when the Emacs Lisp interpreter has trouble evaluating an
8276 expression, it provides you with help; in the jargon, this is called
8277 ``signaling an error''.  Usually, the computer stops the program and
8278 shows you a message.
8280 However, some programs undertake complicated actions.  They should not
8281 simply stop on an error.  In the @code{kill-region} function, the most
8282 likely error is that you will try to kill text that is read-only and
8283 cannot be removed.  So the @code{kill-region} function contains code
8284 to handle this circumstance.  This code, which makes up the body of
8285 the @code{kill-region} function, is inside of a @code{condition-case}
8286 special form.
8288 @need 800
8289 The template for @code{condition-case} looks like this:
8291 @smallexample
8292 @group
8293 (condition-case
8294   @var{var}
8295   @var{bodyform}
8296   @var{error-handler}@dots{})
8297 @end group
8298 @end smallexample
8300 The second argument, @var{bodyform}, is straightforward.  The
8301 @code{condition-case} special form causes the Lisp interpreter to
8302 evaluate the code in @var{bodyform}.  If no error occurs, the special
8303 form returns the code's value and produces the side-effects, if any.
8305 In short, the @var{bodyform} part of a @code{condition-case}
8306 expression determines what should happen when everything works
8307 correctly.
8309 However, if an error occurs, among its other actions, the function
8310 generating the error signal will define one or more error condition
8311 names.
8313 An error handler is the third argument to @code{condition case}.
8314 An error handler has two parts, a @var{condition-name} and a
8315 @var{body}.  If the @var{condition-name} part of an error handler
8316 matches a condition name generated by an error, then the @var{body}
8317 part of the error handler is run.
8319 As you will expect, the @var{condition-name} part of an error handler
8320 may be either a single condition name or a list of condition names.
8322 Also, a complete @code{condition-case} expression may contain more
8323 than one error handler.  When an error occurs, the first applicable
8324 handler is run.
8326 Lastly, the first argument to the @code{condition-case} expression,
8327 the @var{var} argument, is sometimes bound to a variable that
8328 contains information about the error.  However, if that argument is
8329 nil, as is the case in @code{kill-region}, that information is
8330 discarded.
8332 @need 1200
8333 In brief, in the @code{kill-region} function, the code
8334 @code{condition-case} works like this:
8336 @smallexample
8337 @group
8338 @var{If no errors}, @var{run only this code}
8339     @var{but}, @var{if errors}, @var{run this other code}.
8340 @end group
8341 @end smallexample
8343 @ignore
8344 2006 Oct 24
8345 In Emacs 22,
8346 copy-region-as-kill is short, 12 lines, and uses
8347 filter-buffer-substring, which is longer, 39 lines
8348 and has delete-and-extract-region in it.
8349 delete-and-extract-region is written in C.
8351 see Initializing a Variable with @code{defvar}
8352 this is line 8054
8353 Initializing a Variable with @code{defvar} includes line 8350
8354 @end ignore
8356 @node Lisp macro,  , condition-case, kill-region
8357 @comment  node-name,  next,  previous,  up
8358 @subsection Lisp macro
8359 @cindex Macro, lisp
8360 @cindex Lisp macro
8362 The part of the @code{condition-case} expression that is evaluated in
8363 the expectation that all goes well has a @code{when}.  The code uses
8364 @code{when} to determine whether the @code{string} variable points to
8365 text that exists.
8367 A @code{when} expression is simply a programmers' convenience.  It is
8368 an @code{if} without the possibility of an else clause.  In your mind,
8369 you can replace @code{when} with @code{if} and understand what goes
8370 on.  That is what the Lisp interpreter does.
8372 Technically speaking, @code{when} is a Lisp macro.  A Lisp @dfn{macro}
8373 enables you to define new control constructs and other language
8374 features.  It tells the interpreter how to compute another Lisp
8375 expression which will in turn compute the value.  In this case, the
8376 `other expression' is an @code{if} expression.
8378 The @code{kill-region} function definition also has an @code{unless}
8379 macro; it is the converse of @code{when}.  The @code{unless} macro is
8380 an @code{if} without a then clause
8382 For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU
8383 Emacs Lisp Reference Manual}.  The C programming language also
8384 provides macros.  These are different, but also useful.
8386 @ignore
8387 We will briefly look at C macros in
8388 @ref{Digression into C}.
8389 @end ignore
8391 @need 1200
8392 Regarding the @code{when} macro, in the @code{condition-case}
8393 expression, when the string has content, then another conditional
8394 expression is executed.  This is an @code{if} with both a then-part
8395 and an else-part.
8397 @smallexample
8398 @group
8399 (if (eq last-command 'kill-region)
8400     (kill-append string (< end beg) yank-handler)
8401   (kill-new string nil yank-handler))
8402 @end group
8403 @end smallexample
8405 The then-part is evaluated if the previous command was another call to
8406 @code{kill-region}; if not, the else-part is evaluated.
8408 @code{yank-handler} is an optional argument to @code{kill-region} that
8409 tells the @code{kill-append} and @code{kill-new} functions how deal
8410 with properties added to the text, such as `bold' or `italics'.
8412 @code{last-command} is a variable that comes with Emacs that we have
8413 not seen before.  Normally, whenever a function is executed, Emacs
8414 sets the value of @code{last-command} to the previous command.
8416 @need 1200
8417 In this segment of the definition, the @code{if} expression checks
8418 whether the previous command was @code{kill-region}.  If it was,
8420 @smallexample
8421 (kill-append string (< end beg) yank-handler)
8422 @end smallexample
8424 @noindent
8425 concatenates a copy of the newly clipped text to the just previously
8426 clipped text in the kill ring.
8428 @node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text
8429 @comment  node-name,  next,  previous,  up
8430 @section @code{copy-region-as-kill}
8431 @findex copy-region-as-kill
8432 @findex nthcdr
8434 The @code{copy-region-as-kill} function copies a region of text from a
8435 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
8436 in the @code{kill-ring}.
8438 If you call @code{copy-region-as-kill} immediately after a
8439 @code{kill-region} command, Emacs appends the newly copied text to the
8440 previously copied text.  This means that if you yank back the text, you
8441 get it all, from both this and the previous operation.  On the other
8442 hand, if some other command precedes the @code{copy-region-as-kill},
8443 the function copies the text into a separate entry in the kill ring.
8445 @menu
8446 * Complete copy-region-as-kill::  The complete function definition.
8447 * copy-region-as-kill body::      The body of @code{copy-region-as-kill}.
8448 @end menu
8450 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
8451 @ifnottex
8452 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
8453 @end ifnottex
8455 @need 1200
8456 Here is the complete text of the version 22 @code{copy-region-as-kill}
8457 function:
8459 @smallexample
8460 @group
8461 (defun copy-region-as-kill (beg end)
8462   "Save the region as if killed, but don't kill it.
8463 In Transient Mark mode, deactivate the mark.
8464 If `interprogram-cut-function' is non-nil, also save the text for a window
8465 system cut and paste."
8466   (interactive "r")
8467 @end group
8468 @group
8469   (if (eq last-command 'kill-region)
8470       (kill-append (filter-buffer-substring beg end) (< end beg))
8471     (kill-new (filter-buffer-substring beg end)))
8472 @end group
8473 @group
8474   (if transient-mark-mode
8475       (setq deactivate-mark t))
8476   nil)
8477 @end group
8478 @end smallexample
8480 @need 800
8481 As usual, this function can be divided into its component parts:
8483 @smallexample
8484 @group
8485 (defun copy-region-as-kill (@var{argument-list})
8486   "@var{documentation}@dots{}"
8487   (interactive "r")
8488   @var{body}@dots{})
8489 @end group
8490 @end smallexample
8492 The arguments are @code{beg} and @code{end} and the function is
8493 interactive with @code{"r"}, so the two arguments must refer to the
8494 beginning and end of the region.  If you have been reading though this
8495 document from the beginning, understanding these parts of a function is
8496 almost becoming routine.
8498 The documentation is somewhat confusing unless you remember that the
8499 word `kill' has a meaning different from usual.  The `Transient Mark'
8500 and @code{interprogram-cut-function} comments explain certain
8501 side-effects.
8503 After you once set a mark, a buffer always contains a region.  If you
8504 wish, you can use Transient Mark mode to highlight the region
8505 temporarily.  (No one wants to highlight the region all the time, so
8506 Transient Mark mode highlights it only at appropriate times.  Many
8507 people turn off Transient Mark mode, so the region is never
8508 highlighted.)
8510 Also, a windowing system allows you to copy, cut, and paste among
8511 different programs.  In the X windowing system, for example, the
8512 @code{interprogram-cut-function} function is @code{x-select-text},
8513 which works with the windowing system's equivalent of the Emacs kill
8514 ring.
8516 The body of the @code{copy-region-as-kill} function starts with an
8517 @code{if} clause.  What this clause does is distinguish between two
8518 different situations: whether or not this command is executed
8519 immediately after a previous @code{kill-region} command.  In the first
8520 case, the new region is appended to the previously copied text.
8521 Otherwise, it is inserted into the beginning of the kill ring as a
8522 separate piece of text from the previous piece.
8524 The last two lines of the function prevent the region from lighting up
8525 if Transient Mark mode is turned on.
8527 The body of @code{copy-region-as-kill} merits discussion in detail.
8529 @node copy-region-as-kill body,  , Complete copy-region-as-kill, copy-region-as-kill
8530 @comment  node-name,  next,  previous,  up
8531 @subsection The Body of @code{copy-region-as-kill}
8533 The @code{copy-region-as-kill} function works in much the same way as
8534 the @code{kill-region} function.  Both are written so that two or more
8535 kills in a row combine their text into a single entry.  If you yank
8536 back the text from the kill ring, you get it all in one piece.
8537 Moreover, kills that kill forward from the current position of the
8538 cursor are added to the end of the previously copied text and commands
8539 that copy text backwards add it to the beginning of the previously
8540 copied text.  This way, the words in the text stay in the proper
8541 order.
8543 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
8544 use of the @code{last-command} variable that keeps track of the
8545 previous Emacs command.
8547 @menu
8548 * last-command & this-command::
8549 * kill-append function::
8550 * kill-new function::
8551 @end menu
8553 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
8554 @ifnottex
8555 @unnumberedsubsubsec @code{last-command} and @code{this-command}
8556 @end ifnottex
8558 Normally, whenever a function is executed, Emacs sets the value of
8559 @code{this-command} to the function being executed (which in this case
8560 would be @code{copy-region-as-kill}).  At the same time, Emacs sets
8561 the value of @code{last-command} to the previous value of
8562 @code{this-command}.
8564 In the first part of the body of the @code{copy-region-as-kill}
8565 function, an @code{if} expression determines whether the value of
8566 @code{last-command} is @code{kill-region}.  If so, the then-part of
8567 the @code{if} expression is evaluated; it uses the @code{kill-append}
8568 function to concatenate the text copied at this call to the function
8569 with the text already in the first element (the @sc{car}) of the kill
8570 ring.  On the other hand, if the value of @code{last-command} is not
8571 @code{kill-region}, then the @code{copy-region-as-kill} function
8572 attaches a new element to the kill ring using the @code{kill-new}
8573 function.
8575 @need 1250
8576 The @code{if} expression reads as follows; it uses @code{eq}:
8578 @smallexample
8579 @group
8580   (if (eq last-command 'kill-region)
8581       ;; @r{then-part}
8582       (kill-append  (filter-buffer-substring beg end) (< end beg))
8583     ;; @r{else-part}
8584     (kill-new  (filter-buffer-substring beg end)))
8585 @end group
8586 @end smallexample
8588 @findex filter-buffer-substring
8589 (The @code{filter-buffer-substring} function returns a filtered
8590 substring of the buffer, if any.  Optionally---the arguments are not
8591 here, so neither is done---the function may delete the initial text or
8592 return the text without its properties; this function is a replacement
8593 for the older @code{buffer-substring} function, which came before text
8594 properties were implemented.)
8596 @findex eq @r{(example of use)}
8597 @noindent
8598 The @code{eq} function tests whether its first argument is the same Lisp
8599 object as its second argument.  The @code{eq} function is similar to the
8600 @code{equal} function in that it is used to test for equality, but
8601 differs in that it determines whether two representations are actually
8602 the same object inside the computer, but with different names.
8603 @code{equal} determines whether the structure and contents of two
8604 expressions are the same.
8606 If the previous command was @code{kill-region}, then the Emacs Lisp
8607 interpreter calls the @code{kill-append} function
8609 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
8610 @unnumberedsubsubsec The @code{kill-append} function
8611 @findex kill-append
8613 @need 800
8614 The @code{kill-append} function looks like this:
8616 @c in GNU Emacs 22
8617 @smallexample
8618 @group
8619 (defun kill-append (string before-p &optional yank-handler)
8620   "Append STRING to the end of the latest kill in the kill ring.
8621 If BEFORE-P is non-nil, prepend STRING to the kill.
8622 @dots{} "
8623   (let* ((cur (car kill-ring)))
8624     (kill-new (if before-p (concat string cur) (concat cur string))
8625               (or (= (length cur) 0)
8626                   (equal yank-handler
8627                          (get-text-property 0 'yank-handler cur)))
8628               yank-handler)))
8629 @end group
8630 @end smallexample
8632 @ignore
8633 was:
8634 (defun kill-append (string before-p)
8635   "Append STRING to the end of the latest kill in the kill ring.
8636 If BEFORE-P is non-nil, prepend STRING to the kill.
8637 If `interprogram-cut-function' is set, pass the resulting kill to
8638 it."
8639   (kill-new (if before-p
8640                 (concat string (car kill-ring))
8641               (concat (car kill-ring) string))
8642             t))
8643 @end ignore
8645 @noindent
8646 The @code{kill-append} function is fairly straightforward.  It uses
8647 the @code{kill-new} function, which we will discuss in more detail in
8648 a moment.
8650 (Also, the function provides an optional argument called
8651 @code{yank-handler}; when invoked, this argument tells the function
8652 how to deal with properties added to the text, such as `bold' or
8653 `italics'.)
8655 @c !!! bug in GNU Emacs 22 version of  kill-append ?
8656 It has a @code{let*} function to set the value of the first element of
8657 the kill ring to @code{cur}.  (I do not know why the function does not
8658 use @code{let} instead; only one value is set in the expression.
8659 Perhaps this is a bug that produces no problems?)
8661 Consider the conditional that is one of the two arguments to
8662 @code{kill-new}.  It uses @code{concat} to concatenate the new text to
8663 the @sc{car} of the kill ring.  Whether it prepends or appends the
8664 text depends on the results of an @code{if} expression:
8666 @smallexample
8667 @group
8668 (if before-p                            ; @r{if-part}
8669     (concat string cur)                 ; @r{then-part}
8670   (concat cur string))                  ; @r{else-part}
8671 @end group
8672 @end smallexample
8674 @noindent
8675 If the region being killed is before the region that was killed in the
8676 last command, then it should be prepended before the material that was
8677 saved in the previous kill; and conversely, if the killed text follows
8678 what was just killed, it should be appended after the previous text.
8679 The @code{if} expression depends on the predicate @code{before-p} to
8680 decide whether the newly saved text should be put before or after the
8681 previously saved text.
8683 The symbol @code{before-p} is the name of one of the arguments to
8684 @code{kill-append}.  When the @code{kill-append} function is
8685 evaluated, it is bound to the value returned by evaluating the actual
8686 argument.  In this case, this is the expression @code{(< end beg)}.
8687 This expression does not directly determine whether the killed text in
8688 this command is located before or after the kill text of the last
8689 command; what it does is determine whether the value of the variable
8690 @code{end} is less than the value of the variable @code{beg}.  If it
8691 is, it means that the user is most likely heading towards the
8692 beginning of the buffer.  Also, the result of evaluating the predicate
8693 expression, @code{(< end beg)}, will be true and the text will be
8694 prepended before the previous text.  On the other hand, if the value of
8695 the variable @code{end} is greater than the value of the variable
8696 @code{beg}, the text will be appended after the previous text.
8698 @need 800
8699 When the newly saved text will be prepended, then the string with the new
8700 text will be concatenated before the old text:
8702 @smallexample
8703 (concat string cur)
8704 @end smallexample
8706 @need 1200
8707 @noindent
8708 But if the text will be appended, it will be concatenated
8709 after the old text:
8711 @smallexample
8712 (concat cur string))
8713 @end smallexample
8715 To understand how this works, we first need to review the
8716 @code{concat} function.  The @code{concat} function links together or
8717 unites two strings of text.  The result is a string.  For example:
8719 @smallexample
8720 @group
8721 (concat "abc" "def")
8722      @result{} "abcdef"
8723 @end group
8725 @group
8726 (concat "new "
8727         (car '("first element" "second element")))
8728      @result{} "new first element"
8730 (concat (car
8731         '("first element" "second element")) " modified")
8732      @result{} "first element modified"
8733 @end group
8734 @end smallexample
8736 We can now make sense of @code{kill-append}: it modifies the contents
8737 of the kill ring.  The kill ring is a list, each element of which is
8738 saved text.  The @code{kill-append} function uses the @code{kill-new}
8739 function which in turn uses the @code{setcar} function.
8741 @node kill-new function,  , kill-append function, copy-region-as-kill body
8742 @unnumberedsubsubsec The @code{kill-new} function
8743 @findex kill-new
8745 @c in GNU Emacs 22, additional documentation to kill-new:
8746 @ignore
8747 Optional third arguments YANK-HANDLER controls how the STRING is later
8748 inserted into a buffer; see `insert-for-yank' for details.
8749 When a yank handler is specified, STRING must be non-empty (the yank
8750 handler, if non-nil, is stored as a `yank-handler' text property on STRING).
8752 When the yank handler has a non-nil PARAM element, the original STRING
8753 argument is not used by `insert-for-yank'.  However, since Lisp code
8754 may access and use elements from the kill ring directly, the STRING
8755 argument should still be a \"useful\" string for such uses."
8756 @end ignore
8757 @need 1200
8758 The @code{kill-new} function looks like this:
8760 @smallexample
8761 @group
8762 (defun kill-new (string &optional replace yank-handler)
8763   "Make STRING the latest kill in the kill ring.
8764 Set `kill-ring-yank-pointer' to point to it.
8766 If `interprogram-cut-function' is non-nil, apply it to STRING.
8767 Optional second argument REPLACE non-nil means that STRING will replace
8768 the front of the kill ring, rather than being added to the list.
8769 @dots{}"
8770 @end group
8771 @group
8772   (if (> (length string) 0)
8773       (if yank-handler
8774           (put-text-property 0 (length string)
8775                              'yank-handler yank-handler string))
8776     (if yank-handler
8777         (signal 'args-out-of-range
8778                 (list string "yank-handler specified for empty string"))))
8779 @end group
8780 @group
8781   (if (fboundp 'menu-bar-update-yank-menu)
8782       (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8783 @end group
8784 @group
8785   (if (and replace kill-ring)
8786       (setcar kill-ring string)
8787     (push string kill-ring)
8788     (if (> (length kill-ring) kill-ring-max)
8789         (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8790 @end group
8791 @group
8792   (setq kill-ring-yank-pointer kill-ring)
8793   (if interprogram-cut-function
8794       (funcall interprogram-cut-function string (not replace))))
8795 @end group
8796 @end smallexample
8797 @ignore
8798 was:
8799 (defun kill-new (string &optional replace)
8800   "Make STRING the latest kill in the kill ring.
8801 Set the kill-ring-yank pointer to point to it.
8802 If `interprogram-cut-function' is non-nil, apply it to STRING.
8803 Optional second argument REPLACE non-nil means that STRING will replace
8804 the front of the kill ring, rather than being added to the list."
8805   (and (fboundp 'menu-bar-update-yank-menu)
8806        (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8807   (if (and replace kill-ring)
8808       (setcar kill-ring string)
8809     (setq kill-ring (cons string kill-ring))
8810     (if (> (length kill-ring) kill-ring-max)
8811         (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8812   (setq kill-ring-yank-pointer kill-ring)
8813   (if interprogram-cut-function
8814       (funcall interprogram-cut-function string (not replace))))
8815 @end ignore
8817 (Notice that the function is not interactive.)
8819 As usual, we can look at this function in parts.
8821 The function definition has an optional @code{yank-handler} argument,
8822 which when invoked tells the function how to deal with properties
8823 added to the text, such as `bold' or `italics'.  We will skip that.
8825 @need 1200
8826 The first line of the documentation makes sense:
8828 @smallexample
8829 Make STRING the latest kill in the kill ring.
8830 @end smallexample
8832 @noindent
8833 Let's skip over the rest of the documentation for the moment.
8835 @noindent
8836 Also, let's skip over the initial @code{if} expression and those lines
8837 of code involving @code{menu-bar-update-yank-menu}.  We will explain
8838 them below.
8840 @need 1200
8841 The critical lines are these:
8843 @smallexample
8844 @group
8845   (if (and replace kill-ring)
8846       ;; @r{then}
8847       (setcar kill-ring string)
8848 @end group
8849 @group
8850     ;; @r{else}
8851   (push string kill-ring)
8852 @end group
8853 @group
8854     (setq kill-ring (cons string kill-ring))
8855     (if (> (length kill-ring) kill-ring-max)
8856         ;; @r{avoid overly long kill ring}
8857         (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8858 @end group
8859 @group
8860   (setq kill-ring-yank-pointer kill-ring)
8861   (if interprogram-cut-function
8862       (funcall interprogram-cut-function string (not replace))))
8863 @end group
8864 @end smallexample
8866 The conditional test is @w{@code{(and replace kill-ring)}}.
8867 This will be true when two conditions are met:  the kill ring has
8868 something in it, and the @code{replace} variable is true.
8870 @need 1250
8871 When the @code{kill-append} function sets @code{replace} to be true
8872 and when the kill ring has at least one item in it, the @code{setcar}
8873 expression is executed:
8875 @smallexample
8876 (setcar kill-ring string)
8877 @end smallexample
8879 The @code{setcar} function actually changes the first element of the
8880 @code{kill-ring} list to the value of @code{string}.  It replaces the
8881 first element.
8883 @need 1250
8884 On the other hand, if the kill ring is empty, or replace is false, the
8885 else-part of the condition is executed:
8887 @smallexample
8888 (push string kill-ring)
8889 @end smallexample
8891 @noindent
8892 @need 1250
8893 @code{push} puts its first argument onto the second.  It is similar to
8894 the older
8896 @smallexample
8897 (setq kill-ring (cons string kill-ring))
8898 @end smallexample
8900 @noindent
8901 @need 1250
8902 or the newer
8904 @smallexample
8905 (add-to-list kill-ring string)
8906 @end smallexample
8908 @noindent
8909 When it is false, the expression first constructs a new version of the
8910 kill ring by prepending @code{string} to the existing kill ring as a
8911 new element (that is what the @code{push} does).  Then it executes a
8912 second @code{if} clause.  This second @code{if} clause keeps the kill
8913 ring from growing too long.
8915 Let's look at these two expressions in order.
8917 The @code{push} line of the else-part sets the new value of the kill
8918 ring to what results from adding the string being killed to the old
8919 kill ring.
8921 We can see how this works with an example.
8923 @need 800
8924 First,
8926 @smallexample
8927 (setq example-list '("here is a clause" "another clause"))
8928 @end smallexample
8930 @need 1200
8931 @noindent
8932 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
8933 @code{example-list} and see what it returns:
8935 @smallexample
8936 @group
8937 example-list
8938      @result{} ("here is a clause" "another clause")
8939 @end group
8940 @end smallexample
8942 @need 1200
8943 @noindent
8944 Now, we can add a new element on to this list by evaluating the
8945 following expression:
8946 @findex push, @r{example}
8948 @smallexample
8949 (push "a third clause" example-list)
8950 @end smallexample
8952 @need 800
8953 @noindent
8954 When we evaluate @code{example-list}, we find its value is:
8956 @smallexample
8957 @group
8958 example-list
8959      @result{} ("a third clause" "here is a clause" "another clause")
8960 @end group
8961 @end smallexample
8963 @noindent
8964 Thus, the third clause is added to the list by @code{push}.
8966 @need 1200
8967 Now for the second part of the @code{if} clause.  This expression
8968 keeps the kill ring from growing too long.  It looks like this:
8970 @smallexample
8971 @group
8972 (if (> (length kill-ring) kill-ring-max)
8973     (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8974 @end group
8975 @end smallexample
8977 The code checks whether the length of the kill ring is greater than
8978 the maximum permitted length.  This is the value of
8979 @code{kill-ring-max} (which is 60, by default).  If the length of the
8980 kill ring is too long, then this code sets the last element of the
8981 kill ring to @code{nil}.  It does this by using two functions,
8982 @code{nthcdr} and @code{setcdr}.
8984 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
8985 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
8986 @sc{car} of a list.  In this case, however, @code{setcdr} will not be
8987 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
8988 function is used to cause it to set the @sc{cdr} of the next to last
8989 element of the kill ring---this means that since the @sc{cdr} of the
8990 next to last element is the last element of the kill ring, it will set
8991 the last element of the kill ring.
8993 @findex nthcdr, @r{example}
8994 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
8995 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
8996 @dots{}  It does this @var{N} times and returns the results.
8997 (@xref{nthcdr, , @code{nthcdr}}.)
8999 @findex setcdr, @r{example}
9000 Thus, if we had a four element list that was supposed to be three
9001 elements long, we could set the @sc{cdr} of the next to last element
9002 to @code{nil}, and thereby shorten the list.  (If you set the last
9003 element to some other value than @code{nil}, which you could do, then
9004 you would not have shortened the list.  @xref{setcdr, ,
9005 @code{setcdr}}.)
9007 You can see shortening by evaluating the following three expressions
9008 in turn.  First set the value of @code{trees} to @code{(maple oak pine
9009 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
9010 and then find the value of @code{trees}:
9012 @smallexample
9013 @group
9014 (setq trees '(maple oak pine birch))
9015      @result{} (maple oak pine birch)
9016 @end group
9018 @group
9019 (setcdr (nthcdr 2 trees) nil)
9020      @result{} nil
9022 trees
9023      @result{} (maple oak pine)
9024 @end group
9025 @end smallexample
9027 @noindent
9028 (The value returned by the @code{setcdr} expression is @code{nil} since
9029 that is what the @sc{cdr} is set to.)
9031 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
9032 @sc{cdr} a number of times that is one less than the maximum permitted
9033 size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
9034 element (which will be the rest of the elements in the kill ring) to
9035 @code{nil}.  This prevents the kill ring from growing too long.
9037 @need 800
9038 The next to last expression in the @code{kill-new} function is
9040 @smallexample
9041 (setq kill-ring-yank-pointer kill-ring)
9042 @end smallexample
9044 The @code{kill-ring-yank-pointer} is a global variable that is set to be
9045 the @code{kill-ring}.
9047 Even though the @code{kill-ring-yank-pointer} is called a
9048 @samp{pointer}, it is a variable just like the kill ring.  However, the
9049 name has been chosen to help humans understand how the variable is used.
9051 @need 1200
9052 Now, to return to an early expression in the body of the function:
9054 @smallexample
9055 @group
9056   (if (fboundp 'menu-bar-update-yank-menu)
9057        (menu-bar-update-yank-menu string (and replace (car kill-ring))))
9058 @end group
9059 @end smallexample
9061 @noindent
9062 It starts with an @code{if} expression
9064 In this case, the expression tests first to see whether
9065 @code{menu-bar-update-yank-menu} exists as a function, and if so,
9066 calls it.  The @code{fboundp} function returns true if the symbol it
9067 is testing has a function definition that `is not void'.  If the
9068 symbol's function definition were void, we would receive an error
9069 message, as we did when we created errors intentionally (@pxref{Making
9070 Errors, , Generate an Error Message}).
9072 @noindent
9073 The then-part contains an expression whose first element is the
9074 function @code{and}.
9076 @findex and
9077 The @code{and} special form evaluates each of its arguments until one
9078 of the arguments returns a value of @code{nil}, in which case the
9079 @code{and} expression returns @code{nil}; however, if none of the
9080 arguments returns a value of @code{nil}, the value resulting from
9081 evaluating the last argument is returned.  (Since such a value is not
9082 @code{nil}, it is considered true in Emacs Lisp.)  In other words, an
9083 @code{and} expression returns a true value only if all its arguments
9084 are true.  (@xref{Second Buffer Related Review}.)
9086 The expression determines whether the second argument to
9087 @code{menu-bar-update-yank-menu} is true or not.
9088 @ignore
9089     ;; If we're supposed to be extending an existing string, and that
9090     ;; string really is at the front of the menu, then update it in place.
9091 @end ignore
9093 @code{menu-bar-update-yank-menu} is one of the functions that make it
9094 possible to use the `Select and Paste' menu in the Edit item of a menu
9095 bar; using a mouse, you can look at the various pieces of text you
9096 have saved and select one piece to paste.
9098 The last expression in the @code{kill-new} function adds the newly
9099 copied string to whatever facility exists for copying and pasting
9100 among different programs running in a windowing system.  In the X
9101 Windowing system, for example, the @code{x-select-text} function takes
9102 the string and stores it in memory operated by X.  You can paste the
9103 string in another program, such as an Xterm.
9105 @need 1200
9106 The expression looks like this:
9108 @smallexample
9109 @group
9110   (if interprogram-cut-function
9111       (funcall interprogram-cut-function string (not replace))))
9112 @end group
9113 @end smallexample
9115 If an @code{interprogram-cut-function} exists, then Emacs executes
9116 @code{funcall}, which in turn calls its first argument as a function
9117 and passes the remaining arguments to it.  (Incidentally, as far as I
9118 can see, this @code{if} expression could be replaced by an @code{and}
9119 expression similar to the one in the first part of the function.)
9121 We are not going to discuss windowing systems and other programs
9122 further, but merely note that this is a mechanism that enables GNU
9123 Emacs to work easily and well with other programs.
9125 This code for placing text in the kill ring, either concatenated with
9126 an existing element or as a new element, leads us to the code for
9127 bringing back text that has been cut out of the buffer---the yank
9128 commands.  However, before discussing the yank commands, it is better
9129 to learn how lists are implemented in a computer.  This will make
9130 clear such mysteries as the use of the term `pointer'.  But before
9131 that, we will digress into C.
9133 @ignore
9134 @c is this true in Emacs 22?   Does not seems to be
9136   (If the @w{@code{(< end beg))}}
9137 expression is true, @code{kill-append} prepends the string to the just
9138 previously clipped text.  For a detailed discussion, see
9139 @ref{kill-append function, , The @code{kill-append} function}.)
9141 If you then yank back the text, i.e., `paste' it, you get both
9142 pieces of text at once.  That way, if you delete two words in a row,
9143 and then yank them back, you get both words, in their proper order,
9144 with one yank.  (The @w{@code{(< end beg))}} expression makes sure the
9145 order is correct.)
9147 On the other hand, if the previous command is not @code{kill-region},
9148 then the @code{kill-new} function is called, which adds the text to
9149 the kill ring as the latest item, and sets the
9150 @code{kill-ring-yank-pointer} variable to point to it.
9151 @end ignore
9152 @ignore
9154 @c Evidently, changed for Emacs 22. The zap-to-char command does not
9155 @c use the delete-and-extract-region function
9157 2006 Oct 26, the Digression into C is now OK but should come after
9158 copy-region-as-kill and filter-buffer-substring
9160 2006 Oct 24
9161 In Emacs 22,
9162 copy-region-as-kill is short, 12 lines, and uses
9163 filter-buffer-substring, which is longer, 39 lines
9164 and has delete-and-extract-region in it.
9165 delete-and-extract-region is written in C.
9167 see Initializing a Variable with @code{defvar}
9168 @end ignore
9170 @node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text
9171 @comment  node-name,  next,  previous,  up
9172 @section Digression into C
9173 @findex delete-and-extract-region
9174 @cindex C, a digression into
9175 @cindex Digression into C
9177 The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
9178 @code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
9179 function, which in turn uses the @code{delete-and-extract-region}
9180 function.  It removes the contents of a region and you cannot get them
9181 back.
9183 Unlike the other code discussed here, the
9184 @code{delete-and-extract-region} function is not written in Emacs
9185 Lisp; it is written in C and is one of the primitives of the GNU Emacs
9186 system.  Since it is very simple, I will digress briefly from Lisp and
9187 describe it here.
9189 @c GNU Emacs 22  in /usr/local/src/emacs/src/editfns.c
9190 @c the DEFUN for  buffer-substring-no-properties
9192 @need 1500
9193 Like many of the other Emacs primitives,
9194 @code{delete-and-extract-region} is written as an instance of a C
9195 macro, a macro being a template for code.  The complete macro looks
9196 like this:
9198 @smallexample
9199 @group
9200 DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties,
9201        Sbuffer_substring_no_properties, 2, 2, 0,
9202        doc: /* Return the characters of part of the buffer,
9203 without the text properties.
9204 The two arguments START and END are character positions;
9205 they can be in either order.  */)
9206      (start, end)
9207      Lisp_Object start, end;
9209   register int b, e;
9211   validate_region (&start, &end);
9212   b = XINT (start);
9213   e = XINT (end);
9215   return make_buffer_string (b, e, 0);
9217 @end group
9218 @end smallexample
9220 Without going into the details of the macro writing process, let me
9221 point out that this macro starts with the word @code{DEFUN}.  The word
9222 @code{DEFUN} was chosen since the code serves the same purpose as
9223 @code{defun} does in Lisp.  (The @code{DEFUN} C macro is defined in
9224 @file{emacs/src/lisp.h}.)
9226 The word @code{DEFUN} is followed by seven parts inside of
9227 parentheses:
9229 @itemize @bullet
9230 @item
9231 The first part is the name given to the function in Lisp,
9232 @code{delete-and-extract-region}.
9234 @item
9235 The second part is the name of the function in C,
9236 @code{Fdelete_and_extract_region}.  By convention, it starts with
9237 @samp{F}.  Since C does not use hyphens in names, underscores are used
9238 instead.
9240 @item
9241 The third part is the name for the C constant structure that records
9242 information on this function for internal use.  It is the name of the
9243 function in C but begins with an @samp{S} instead of an @samp{F}.
9245 @item
9246 The fourth and fifth parts specify the minimum and maximum number of
9247 arguments the function can have.  This function demands exactly 2
9248 arguments.
9250 @item
9251 The sixth part is nearly like the argument that follows the
9252 @code{interactive} declaration in a function written in Lisp: a letter
9253 followed, perhaps, by a prompt.  The only difference from the Lisp is
9254 when the macro is called with no arguments.  Then you write a @code{0}
9255 (which is a `null string'), as in this macro.
9257 If you were to specify arguments, you would place them between
9258 quotation marks.  The C macro for @code{goto-char} includes
9259 @code{"NGoto char: "} in this position to indicate that the function
9260 expects a raw prefix, in this case, a numerical location in a buffer,
9261 and provides a prompt.
9263 @item
9264 The seventh part is a documentation string, just like the one for a
9265 function written in Emacs Lisp, except that every newline must be
9266 written explicitly as @samp{\n} followed by a backslash and carriage
9267 return.
9269 @need 1000
9270 Thus, the first two lines of documentation for  @code{goto-char} are
9271 written like this:
9273 @smallexample
9274 @group
9275   "Set point to POSITION, a number or marker.\n\
9276 Beginning of buffer is position (point-min), end is (point-max)."
9277 @end group
9278 @end smallexample
9279 @end itemize
9281 @need 1200
9282 In a C macro, the formal parameters come next, with a statement of
9283 what kind of object they are, followed by what might be called the `body'
9284 of the macro.  For @code{delete-and-extract-region} the `body'
9285 consists of the following four lines:
9287 @smallexample
9288 @group
9289 validate_region (&start, &end);
9290 if (XINT (start) == XINT (end))
9291   return build_string ("");
9292 return del_range_1 (XINT (start), XINT (end), 1, 1);
9293 @end group
9294 @end smallexample
9296 The   @code{validate_region} function checks whether the values
9297 passed as the beginning and end of the region are the proper type and
9298 are within range.  If the beginning and end positions are the same,
9299 then return and empty string.
9301 The @code{del_range_1} function actually deletes the text.  It is a
9302 complex function we will not look into.  It updates the buffer and
9303 does other things.  However, it is worth looking at the two arguments
9304 passed to @code{del_range}.  These are @w{@code{XINT (start)}} and
9305 @w{@code{XINT (end)}}.
9307 As far as the C language is concerned, @code{start} and @code{end} are
9308 two integers that mark the beginning and end of the region to be
9309 deleted@footnote{More precisely, and requiring more expert knowledge
9310 to understand, the two integers are of type `Lisp_Object', which can
9311 also be a C union instead of an integer type.}.
9313 In early versions of Emacs, these two numbers were thirty-two bits
9314 long, but the code is slowly being generalized to handle other
9315 lengths.  Three of the available bits are used to specify the type of
9316 information; the remaining bits are used as `content'.
9318 @samp{XINT} is a C macro that extracts the relevant number from the
9319 longer collection of bits; the three other bits are discarded.
9321 @need 800
9322 The command in @code{delete-and-extract-region} looks like this:
9324 @smallexample
9325 del_range_1 (XINT (start), XINT (end), 1, 1);
9326 @end smallexample
9328 @noindent
9329 It deletes the region between the beginning position, @code{start},
9330 and the ending position, @code{end}.
9332 From the point of view of the person writing Lisp, Emacs is all very
9333 simple; but hidden underneath is a great deal of complexity to make it
9334 all work.
9336 @node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text
9337 @comment  node-name,  next,  previous,  up
9338 @section Initializing a Variable with @code{defvar}
9339 @findex defvar
9340 @cindex Initializing a variable
9341 @cindex Variable initialization
9343 @ignore
9344 2006 Oct 24
9345 In Emacs 22,
9346 copy-region-as-kill is short, 12 lines, and uses
9347 filter-buffer-substring, which is longer, 39 lines
9348 and has delete-and-extract-region in it.
9349 delete-and-extract-region is written in C.
9351 see Initializing a Variable with @code{defvar}
9353 @end ignore
9355 The @code{copy-region-as-kill} function is written in Emacs Lisp.  Two
9356 functions within it, @code{kill-append} and @code{kill-new}, copy a
9357 region in a buffer and save it in a variable called the
9358 @code{kill-ring}.  This section describes how the @code{kill-ring}
9359 variable is created and initialized using the @code{defvar} special
9360 form.
9362 (Again we note that the term @code{kill-ring} is a misnomer.  The text
9363 that is clipped out of the buffer can be brought back; it is not a ring
9364 of corpses, but a ring of resurrectable text.)
9366 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
9367 given an initial value by using the @code{defvar} special form.  The
9368 name comes from ``define variable''.
9370 The @code{defvar} special form is similar to @code{setq} in that it sets
9371 the value of a variable.  It is unlike @code{setq} in two ways: first,
9372 it only sets the value of the variable if the variable does not already
9373 have a value.  If the variable already has a value, @code{defvar} does
9374 not override the existing value.  Second, @code{defvar} has a
9375 documentation string.
9377 (Another special form, @code{defcustom}, is designed for variables
9378 that people customize.  It has more features than @code{defvar}.
9379 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
9381 @menu
9382 * See variable current value::
9383 * defvar and asterisk::
9384 @end menu
9386 @node See variable current value, defvar and asterisk, defvar, defvar
9387 @ifnottex
9388 @unnumberedsubsec Seeing the Current Value of a Variable
9389 @end ifnottex
9391 You can see the current value of a variable, any variable, by using
9392 the @code{describe-variable} function, which is usually invoked by
9393 typing @kbd{C-h v}.  If you type @kbd{C-h v} and then @code{kill-ring}
9394 (followed by @key{RET}) when prompted, you will see what is in your
9395 current kill ring---this may be quite a lot!  Conversely, if you have
9396 been doing nothing this Emacs session except read this document, you
9397 may have nothing in it.  Also, you will see the documentation for
9398 @code{kill-ring}:
9400 @smallexample
9401 @group
9402 Documentation:
9403 List of killed text sequences.
9404 Since the kill ring is supposed to interact nicely with cut-and-paste
9405 facilities offered by window systems, use of this variable should
9406 @end group
9407 @group
9408 interact nicely with `interprogram-cut-function' and
9409 `interprogram-paste-function'.  The functions `kill-new',
9410 `kill-append', and `current-kill' are supposed to implement this
9411 interaction; you may want to use them instead of manipulating the kill
9412 ring directly.
9413 @end group
9414 @end smallexample
9416 @need 800
9417 The kill ring is defined by a @code{defvar} in the following way:
9419 @smallexample
9420 @group
9421 (defvar kill-ring nil
9422   "List of killed text sequences.
9423 @dots{}")
9424 @end group
9425 @end smallexample
9427 @noindent
9428 In this variable definition, the variable is given an initial value of
9429 @code{nil}, which makes sense, since if you have saved nothing, you want
9430 nothing back if you give a @code{yank} command.  The documentation
9431 string is written just like the documentation string of a @code{defun}.
9432 As with the documentation string of the @code{defun}, the first line of
9433 the documentation should be a complete sentence, since some commands,
9434 like @code{apropos}, print only the first line of documentation.
9435 Succeeding lines should not be indented; otherwise they look odd when
9436 you use @kbd{C-h v} (@code{describe-variable}).
9438 @node defvar and asterisk,  , See variable current value, defvar
9439 @subsection @code{defvar} and an asterisk
9440 @findex defvar @r{for a user customizable variable}
9441 @findex defvar @r{with an asterisk}
9443 In the past, Emacs used the @code{defvar} special form both for
9444 internal variables that you would not expect a user to change and for
9445 variables that you do expect a user to change.  Although you can still
9446 use @code{defvar} for user customizable variables, please use
9447 @code{defcustom} instead, since that special form provides a path into
9448 the Customization commands.  (@xref{defcustom, , Specifying Variables
9449 using @code{defcustom}}.)
9451 When you specified a variable using the @code{defvar} special form,
9452 you could distinguish a readily settable variable from others by
9453 typing an asterisk, @samp{*}, in the first column of its documentation
9454 string.  For example:
9456 @smallexample
9457 @group
9458 (defvar shell-command-default-error-buffer nil
9459   "*Buffer name for `shell-command' @dots{} error output.
9460 @dots{} ")
9461 @end group
9462 @end smallexample
9464 @findex set-variable
9465 @noindent
9466 You could (and still can) use the @code{set-variable} command to
9467 change the value of @code{shell-command-default-error-buffer}
9468 temporarily.  However, options set using @code{set-variable} are set
9469 only for the duration of your editing session.  The new values are not
9470 saved between sessions.  Each time Emacs starts, it reads the original
9471 value, unless you change the value within your @file{.emacs} file,
9472 either by setting it manually or by using @code{customize}.
9473 @xref{Emacs Initialization, , Your @file{.emacs} File}.
9475 For me, the major use of the @code{set-variable} command is to suggest
9476 variables that I might want to set in my @file{.emacs} file.  There
9477 are now more than 700 such variables --- far too many to remember
9478 readily.  Fortunately, you can press @key{TAB} after calling the
9479 @code{M-x set-variable} command to see the list of variables.
9480 (@xref{Examining, , Examining and Setting Variables, emacs,
9481 The GNU Emacs Manual}.)
9483 @need 1250
9484 @node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text
9485 @comment  node-name,  next,  previous,  up
9486 @section Review
9488 Here is a brief summary of some recently introduced functions.
9490 @table @code
9491 @item car
9492 @itemx cdr
9493 @code{car} returns the first element of a list; @code{cdr} returns the
9494 second and subsequent elements of a list.
9496 @need 1250
9497 For example:
9499 @smallexample
9500 @group
9501 (car '(1 2 3 4 5 6 7))
9502      @result{} 1
9503 (cdr '(1 2 3 4 5 6 7))
9504      @result{} (2 3 4 5 6 7)
9505 @end group
9506 @end smallexample
9508 @item cons
9509 @code{cons} constructs a list by prepending its first argument to its
9510 second argument.
9512 @need 1250
9513 For example:
9515 @smallexample
9516 @group
9517 (cons 1 '(2 3 4))
9518      @result{} (1 2 3 4)
9519 @end group
9520 @end smallexample
9522 @item funcall
9523 @code{funcall} evaluates its first argument as a function.  It passes
9524 its remaining arguments to its first argument.
9526 @item nthcdr
9527 Return the result of taking @sc{cdr} `n' times on a list.
9528 @iftex
9530 @tex
9531 $n^{th}$
9532 @end tex
9533 @code{cdr}.
9534 @end iftex
9535 The `rest of the rest', as it were.
9537 @need 1250
9538 For example:
9540 @smallexample
9541 @group
9542 (nthcdr 3 '(1 2 3 4 5 6 7))
9543      @result{} (4 5 6 7)
9544 @end group
9545 @end smallexample
9547 @item setcar
9548 @itemx setcdr
9549 @code{setcar} changes the first element of a list; @code{setcdr}
9550 changes the second and subsequent elements of a list.
9552 @need 1250
9553 For example:
9555 @smallexample
9556 @group
9557 (setq triple '(1 2 3))
9559 (setcar triple '37)
9561 triple
9562      @result{} (37 2 3)
9564 (setcdr triple '("foo" "bar"))
9566 triple
9567      @result{} (37 "foo" "bar")
9568 @end group
9569 @end smallexample
9571 @item progn
9572 Evaluate each argument in sequence and then return the value of the
9573 last.
9575 @need 1250
9576 For example:
9578 @smallexample
9579 @group
9580 (progn 1 2 3 4)
9581      @result{} 4
9582 @end group
9583 @end smallexample
9585 @item save-restriction
9586 Record whatever narrowing is in effect in the current buffer, if any,
9587 and restore that narrowing after evaluating the arguments.
9589 @item search-forward
9590 Search for a string, and if the string is found, move point.  With a
9591 regular expression, use the similar @code{re-search-forward}.
9592 (@xref{Regexp Search, , Regular Expression Searches}, for an
9593 explanation of regular expression patterns and searches.)
9595 @need 1250
9596 @noindent
9597 @code{search-forward} and @code{re-search-forward} take four
9598 arguments:
9600 @enumerate
9601 @item
9602 The string or regular expression to search for.
9604 @item
9605 Optionally, the limit of the search.
9607 @item
9608 Optionally, what to do if the search fails, return @code{nil} or an
9609 error message.
9611 @item
9612 Optionally, how many times to repeat the search; if negative, the
9613 search goes backwards.
9614 @end enumerate
9616 @item kill-region
9617 @itemx delete-and-extract-region
9618 @itemx copy-region-as-kill
9620 @code{kill-region} cuts the text between point and mark from the
9621 buffer and stores that text in the kill ring, so you can get it back
9622 by yanking.
9624 @code{copy-region-as-kill} copies the text between point and mark into
9625 the kill ring, from which you can get it by yanking.  The function
9626 does not cut or remove the text from the buffer.
9627 @end table
9629 @code{delete-and-extract-region} removes the text between point and
9630 mark from the buffer and throws it away.  You cannot get it back.
9631 (This is not an interactive command.)
9633 @need 1500
9634 @node search Exercises,  , cons & search-fwd Review, Cutting & Storing Text
9635 @section Searching Exercises
9637 @itemize @bullet
9638 @item
9639 Write an interactive function that searches for a string.  If the
9640 search finds the string, leave point after it and display a message
9641 that says ``Found!''.  (Do not use @code{search-forward} for the name
9642 of this function; if you do, you will overwrite the existing version of
9643 @code{search-forward} that comes with Emacs.  Use a name such as
9644 @code{test-search} instead.)
9646 @item
9647 Write a function that prints the third element of the kill ring in the
9648 echo area, if any; if the kill ring does not contain a third element,
9649 print an appropriate message.
9650 @end itemize
9652 @node List Implementation, Yanking, Cutting & Storing Text, Top
9653 @comment  node-name,  next,  previous,  up
9654 @chapter How Lists are Implemented
9655 @cindex Lists in a computer
9657 In Lisp, atoms are recorded in a straightforward fashion; if the
9658 implementation is not straightforward in practice, it is, nonetheless,
9659 straightforward in theory.  The atom @samp{rose}, for example, is
9660 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
9661 @samp{e}.  A list, on the other hand, is kept differently.  The mechanism
9662 is equally simple, but it takes a moment to get used to the idea.  A
9663 list is kept using a series of pairs of pointers.  In the series, the
9664 first pointer in each pair points to an atom or to another list, and the
9665 second pointer in each pair points to the next pair, or to the symbol
9666 @code{nil}, which marks the end of the list.
9668 A pointer itself is quite simply the electronic address of what is
9669 pointed to.  Hence, a list is kept as a series of electronic addresses.
9671 @menu
9672 * Lists diagrammed::
9673 * Symbols as Chest::            Exploring a powerful metaphor.
9674 * List Exercise::
9675 @end menu
9677 @node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
9678 @ifnottex
9679 @unnumberedsec Lists diagrammed
9680 @end ifnottex
9682 For example, the list @code{(rose violet buttercup)} has three elements,
9683 @samp{rose}, @samp{violet}, and @samp{buttercup}.  In the computer, the
9684 electronic address of @samp{rose} is recorded in a segment of computer
9685 memory along with the address that gives the electronic address of where
9686 the atom @samp{violet} is located; and that address (the one that tells
9687 where @samp{violet} is located) is kept along with an address that tells
9688 where the address for the atom @samp{buttercup} is located.
9690 @need 1200
9691 This sounds more complicated than it is and is easier seen in a diagram:
9693 @c clear print-postscript-figures
9694 @c !!! cons-cell-diagram #1
9695 @ifnottex
9696 @smallexample
9697 @group
9698     ___ ___      ___ ___      ___ ___
9699    |___|___|--> |___|___|--> |___|___|--> nil
9700      |            |            |
9701      |            |            |
9702       --> rose     --> violet   --> buttercup
9703 @end group
9704 @end smallexample
9705 @end ifnottex
9706 @ifset print-postscript-figures
9707 @sp 1
9708 @tex
9709 @center @image{cons-1}
9710 %%%% old method of including an image
9711 % \input /usr/local/lib/tex/inputs/psfig.tex
9712 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
9713 % \catcode`\@=0 %
9714 @end tex
9715 @sp 1
9716 @end ifset
9717 @ifclear print-postscript-figures
9718 @iftex
9719 @smallexample
9720 @group
9721     ___ ___      ___ ___      ___ ___
9722    |___|___|--> |___|___|--> |___|___|--> nil
9723      |            |            |
9724      |            |            |
9725       --> rose     --> violet   --> buttercup
9726 @end group
9727 @end smallexample
9728 @end iftex
9729 @end ifclear
9731 @noindent
9732 In the diagram, each box represents a word of computer memory that
9733 holds a Lisp object, usually in the form of a memory address.  The boxes,
9734 i.e.@: the addresses, are in pairs.  Each arrow points to what the address
9735 is the address of, either an atom or another pair of addresses.  The
9736 first box is the electronic address of @samp{rose} and the arrow points
9737 to @samp{rose}; the second box is the address of the next pair of boxes,
9738 the first part of which is the address of @samp{violet} and the second
9739 part of which is the address of the next pair.  The very last box
9740 points to the symbol @code{nil}, which marks the end of the list.
9742 @need 1200
9743 When a variable is set to a list with a function such as @code{setq},
9744 it stores the address of the first box in the variable.  Thus,
9745 evaluation of the expression
9747 @smallexample
9748 (setq bouquet '(rose violet buttercup))
9749 @end smallexample
9751 @need 1250
9752 @noindent
9753 creates a situation like this:
9755 @c cons-cell-diagram #2
9756 @ifnottex
9757 @smallexample
9758 @group
9759 bouquet
9760      |
9761      |     ___ ___      ___ ___      ___ ___
9762       --> |___|___|--> |___|___|--> |___|___|--> nil
9763             |            |            |
9764             |            |            |
9765              --> rose     --> violet   --> buttercup
9766 @end group
9767 @end smallexample
9768 @end ifnottex
9769 @ifset print-postscript-figures
9770 @sp 1
9771 @tex
9772 @center @image{cons-2}
9773 %%%% old method of including an image
9774 % \input /usr/local/lib/tex/inputs/psfig.tex
9775 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
9776 % \catcode`\@=0 %
9777 @end tex
9778 @sp 1
9779 @end ifset
9780 @ifclear print-postscript-figures
9781 @iftex
9782 @smallexample
9783 @group
9784 bouquet
9785      |
9786      |     ___ ___      ___ ___      ___ ___
9787       --> |___|___|--> |___|___|--> |___|___|--> nil
9788             |            |            |
9789             |            |            |
9790              --> rose     --> violet   --> buttercup
9791 @end group
9792 @end smallexample
9793 @end iftex
9794 @end ifclear
9796 @noindent
9797 In this example, the symbol @code{bouquet} holds the address of the first
9798 pair of boxes.
9800 @need 1200
9801 This same list can be illustrated in a different sort of box notation
9802 like this:
9804 @c cons-cell-diagram #2a
9805 @ifnottex
9806 @smallexample
9807 @group
9808 bouquet
9810  |    --------------       ---------------       ----------------
9811  |   | car   | cdr  |     | car    | cdr  |     | car     | cdr  |
9812   -->| rose  |   o------->| violet |   o------->| butter- |  nil |
9813      |       |      |     |        |      |     | cup     |      |
9814       --------------       ---------------       ----------------
9815 @end group
9816 @end smallexample
9817 @end ifnottex
9818 @ifset print-postscript-figures
9819 @sp 1
9820 @tex
9821 @center @image{cons-2a}
9822 %%%% old method of including an image
9823 % \input /usr/local/lib/tex/inputs/psfig.tex
9824 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
9825 % \catcode`\@=0 %
9826 @end tex
9827 @sp 1
9828 @end ifset
9829 @ifclear print-postscript-figures
9830 @iftex
9831 @smallexample
9832 @group
9833 bouquet
9835  |    --------------       ---------------       ----------------
9836  |   | car   | cdr  |     | car    | cdr  |     | car     | cdr  |
9837   -->| rose  |   o------->| violet |   o------->| butter- |  nil |
9838      |       |      |     |        |      |     | cup     |      |
9839       --------------       ---------------       ----------------
9840 @end group
9841 @end smallexample
9842 @end iftex
9843 @end ifclear
9845 (Symbols consist of more than pairs of addresses, but the structure of
9846 a symbol is made up of addresses.  Indeed, the symbol @code{bouquet}
9847 consists of a group of address-boxes, one of which is the address of
9848 the printed word @samp{bouquet}, a second of which is the address of a
9849 function definition attached to the symbol, if any, a third of which
9850 is the address of the first pair of address-boxes for the list
9851 @code{(rose violet buttercup)}, and so on.  Here we are showing that
9852 the symbol's third address-box points to the first pair of
9853 address-boxes for the list.)
9855 If a symbol is set to the @sc{cdr} of a list, the list itself is not
9856 changed; the symbol simply has an address further down the list.  (In
9857 the jargon, @sc{car} and @sc{cdr} are `non-destructive'.)  Thus,
9858 evaluation of the following expression
9860 @smallexample
9861 (setq flowers (cdr bouquet))
9862 @end smallexample
9864 @need 800
9865 @noindent
9866 produces this:
9868 @c cons-cell-diagram #3
9869 @ifnottex
9870 @sp 1
9871 @smallexample
9872 @group
9873 bouquet        flowers
9874   |              |
9875   |     ___ ___  |     ___ ___      ___ ___
9876    --> |   |   |  --> |   |   |    |   |   |
9877        |___|___|----> |___|___|--> |___|___|--> nil
9878          |              |            |
9879          |              |            |
9880           --> rose       --> violet   --> buttercup
9881 @end group
9882 @end smallexample
9883 @sp 1
9884 @end ifnottex
9885 @ifset print-postscript-figures
9886 @sp 1
9887 @tex
9888 @center @image{cons-3}
9889 %%%% old method of including an image
9890 % \input /usr/local/lib/tex/inputs/psfig.tex
9891 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
9892 % \catcode`\@=0 %
9893 @end tex
9894 @sp 1
9895 @end ifset
9896 @ifclear print-postscript-figures
9897 @iftex
9898 @sp 1
9899 @smallexample
9900 @group
9901 bouquet        flowers
9902   |              |
9903   |     ___ ___  |     ___ ___      ___ ___
9904    --> |   |   |  --> |   |   |    |   |   |
9905        |___|___|----> |___|___|--> |___|___|--> nil
9906          |              |            |
9907          |              |            |
9908           --> rose       --> violet   --> buttercup
9909 @end group
9910 @end smallexample
9911 @sp 1
9912 @end iftex
9913 @end ifclear
9915 @noindent
9916 The value of @code{flowers} is @code{(violet buttercup)}, which is
9917 to say, the symbol @code{flowers} holds the address of the pair of
9918 address-boxes, the first of which holds the address of @code{violet},
9919 and the second of which holds the address of @code{buttercup}.
9921 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
9922 pair}.  @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
9923 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
9924 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
9925 information about cons cells and dotted pairs.
9927 @need 1200
9928 The function @code{cons} adds a new pair of addresses to the front of
9929 a series of addresses like that shown above.  For example, evaluating
9930 the expression
9932 @smallexample
9933 (setq bouquet (cons 'lily bouquet))
9934 @end smallexample
9936 @need 1500
9937 @noindent
9938 produces:
9940 @c cons-cell-diagram #4
9941 @ifnottex
9942 @sp 1
9943 @smallexample
9944 @group
9945 bouquet                       flowers
9946   |                             |
9947   |     ___ ___        ___ ___  |     ___ ___       ___ ___
9948    --> |   |   |      |   |   |  --> |   |   |     |   |   |
9949        |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9950          |              |              |             |
9951          |              |              |             |
9952           --> lily      --> rose       --> violet    --> buttercup
9953 @end group
9954 @end smallexample
9955 @sp 1
9956 @end ifnottex
9957 @ifset print-postscript-figures
9958 @sp 1
9959 @tex
9960 @center @image{cons-4}
9961 %%%% old method of including an image
9962 % \input /usr/local/lib/tex/inputs/psfig.tex
9963 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
9964 % \catcode`\@=0 %
9965 @end tex
9966 @sp 1
9967 @end ifset
9968 @ifclear print-postscript-figures
9969 @iftex
9970 @sp 1
9971 @smallexample
9972 @group
9973 bouquet                       flowers
9974   |                             |
9975   |     ___ ___        ___ ___  |     ___ ___       ___ ___
9976    --> |   |   |      |   |   |  --> |   |   |     |   |   |
9977        |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9978          |              |              |             |
9979          |              |              |             |
9980           --> lily      --> rose       --> violet    --> buttercup
9981 @end group
9982 @end smallexample
9983 @sp 1
9984 @end iftex
9985 @end ifclear
9987 @need 1200
9988 @noindent
9989 However, this does not change the value of the symbol
9990 @code{flowers}, as you can see by evaluating the following,
9992 @smallexample
9993 (eq (cdr (cdr bouquet)) flowers)
9994 @end smallexample
9996 @noindent
9997 which returns @code{t} for true.
9999 Until it is reset, @code{flowers} still has the value
10000 @code{(violet buttercup)}; that is, it has the address of the cons
10001 cell whose first address is of @code{violet}.  Also, this does not
10002 alter any of the pre-existing cons cells; they are all still there.
10004 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
10005 of the next cons cell in the series; to get the @sc{car} of a list,
10006 you get the address of the first element of the list; to @code{cons} a
10007 new element on a list, you add a new cons cell to the front of the list.
10008 That is all there is to it!  The underlying structure of Lisp is
10009 brilliantly simple!
10011 And what does the last address in a series of cons cells refer to?  It
10012 is the address of the empty list, of @code{nil}.
10014 In summary, when a Lisp variable is set to a value, it is provided with
10015 the address of the list to which the variable refers.
10017 @node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation
10018 @section Symbols as a Chest of Drawers
10019 @cindex Symbols as a Chest of Drawers
10020 @cindex Chest of Drawers, metaphor for a symbol
10021 @cindex Drawers, Chest of, metaphor for a symbol
10023 In an earlier section, I suggested that you might imagine a symbol as
10024 being a chest of drawers.  The function definition is put in one
10025 drawer, the value in another, and so on.  What is put in the drawer
10026 holding the value can be changed without affecting the contents of the
10027 drawer holding the function definition, and vice-verse.
10029 Actually, what is put in each drawer is the address of the value or
10030 function definition.  It is as if you found an old chest in the attic,
10031 and in one of its drawers you found a map giving you directions to
10032 where the buried treasure lies.
10034 (In addition to its name, symbol definition, and variable value, a
10035 symbol has a `drawer' for a @dfn{property list} which can be used to
10036 record other information.  Property lists are not discussed here; see
10037 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
10038 Reference Manual}.)
10040 @need 1500
10041 Here is a fanciful representation:
10043 @c chest-of-drawers diagram
10044 @ifnottex
10045 @sp 1
10046 @smallexample
10047 @group
10048             Chest of Drawers            Contents of Drawers
10050             __   o0O0o   __
10051           /                 \
10052          ---------------------
10053         |    directions to    |            [map to]
10054         |     symbol name     |             bouquet
10055         |                     |
10056         +---------------------+
10057         |    directions to    |
10058         |  symbol definition  |             [none]
10059         |                     |
10060         +---------------------+
10061         |    directions to    |            [map to]
10062         |    variable value   |             (rose violet buttercup)
10063         |                     |
10064         +---------------------+
10065         |    directions to    |
10066         |    property list    |             [not described here]
10067         |                     |
10068         +---------------------+
10069         |/                   \|
10070 @end group
10071 @end smallexample
10072 @sp 1
10073 @end ifnottex
10074 @ifset print-postscript-figures
10075 @sp 1
10076 @tex
10077 @center @image{drawers}
10078 %%%% old method of including an image
10079 % \input /usr/local/lib/tex/inputs/psfig.tex
10080 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
10081 % \catcode`\@=0 %
10082 @end tex
10083 @sp 1
10084 @end ifset
10085 @ifclear print-postscript-figures
10086 @iftex
10087 @sp 1
10088 @smallexample
10089 @group
10090             Chest of Drawers            Contents of Drawers
10092             __   o0O0o   __
10093           /                 \
10094          ---------------------
10095         |    directions to    |            [map to]
10096         |     symbol name     |             bouquet
10097         |                     |
10098         +---------------------+
10099         |    directions to    |
10100         |  symbol definition  |             [none]
10101         |                     |
10102         +---------------------+
10103         |    directions to    |            [map to]
10104         |    variable value   |             (rose violet buttercup)
10105         |                     |
10106         +---------------------+
10107         |    directions to    |
10108         |    property list    |             [not described here]
10109         |                     |
10110         +---------------------+
10111         |/                   \|
10112 @end group
10113 @end smallexample
10114 @sp 1
10115 @end iftex
10116 @end ifclear
10118 @node List Exercise,  , Symbols as Chest, List Implementation
10119 @section Exercise
10121 Set @code{flowers} to @code{violet} and @code{buttercup}.  Cons two
10122 more flowers on to this list and set this new list to
10123 @code{more-flowers}.  Set the @sc{car} of @code{flowers} to a fish.
10124 What does the @code{more-flowers} list now contain?
10126 @node Yanking, Loops & Recursion, List Implementation, Top
10127 @comment  node-name,  next,  previous,  up
10128 @chapter Yanking Text Back
10129 @findex yank
10130 @cindex Text retrieval
10131 @cindex Retrieving text
10132 @cindex Pasting text
10134 Whenever you cut text out of a buffer with a `kill' command in GNU Emacs,
10135 you can bring it back with a `yank' command.  The text that is cut out of
10136 the buffer is put in the kill ring and the yank commands insert the
10137 appropriate contents of the kill ring back into a buffer (not necessarily
10138 the original buffer).
10140 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
10141 the kill ring into the current buffer.  If the @kbd{C-y} command is
10142 followed immediately by @kbd{M-y}, the first element is replaced by
10143 the second element.  Successive @kbd{M-y} commands replace the second
10144 element with the third, fourth, or fifth element, and so on.  When the
10145 last element in the kill ring is reached, it is replaced by the first
10146 element and the cycle is repeated.  (Thus the kill ring is called a
10147 `ring' rather than just a `list'.  However, the actual data structure
10148 that holds the text is a list.
10149 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
10150 list is handled as a ring.)
10152 @menu
10153 * Kill Ring Overview::
10154 * kill-ring-yank-pointer::      The kill ring is a list.
10155 * yank nthcdr Exercises::       The @code{kill-ring-yank-pointer} variable.
10156 @end menu
10158 @node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
10159 @comment  node-name,  next,  previous,  up
10160 @section Kill Ring Overview
10161 @cindex Kill ring overview
10163 The kill ring is a list of textual strings.  This is what it looks like:
10165 @smallexample
10166 ("some text" "a different piece of text" "yet more text")
10167 @end smallexample
10169 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
10170 string of characters saying @samp{some text} would be inserted in this
10171 buffer where my cursor is located.
10173 The @code{yank} command is also used for duplicating text by copying it.
10174 The copied text is not cut from the buffer, but a copy of it is put on the
10175 kill ring and is inserted by yanking it back.
10177 Three functions are used for bringing text back from the kill ring:
10178 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
10179 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
10180 which is used by the two other functions.
10182 These functions refer to the kill ring through a variable called the
10183 @code{kill-ring-yank-pointer}.  Indeed, the insertion code for both the
10184 @code{yank} and @code{yank-pop} functions is:
10186 @smallexample
10187 (insert (car kill-ring-yank-pointer))
10188 @end smallexample
10190 @noindent
10191 (Well, no more.  In GNU Emacs 22, the function has been replaced by
10192 @code{insert-for-yank} which calls @code{insert-for-yank-1}
10193 repetitively for each @code{yank-handler} segment.  In turn,
10194 @code{insert-for-yank-1} strips text properties from the inserted text
10195 according to @code{yank-excluded-properties}.  Otherwise, it is just
10196 like @code{insert}.  We will stick with plain @code{insert} since it
10197 is easier to understand.)
10199 To begin to understand how @code{yank} and @code{yank-pop} work, it is
10200 first necessary to look at the @code{kill-ring-yank-pointer} variable.
10202 @node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking
10203 @comment  node-name,  next,  previous,  up
10204 @section The @code{kill-ring-yank-pointer} Variable
10206 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
10207 a variable.  It points to something by being bound to the value of what
10208 it points to, like any other Lisp variable.
10210 @need 1000
10211 Thus, if the value of the kill ring is:
10213 @smallexample
10214 ("some text" "a different piece of text" "yet more text")
10215 @end smallexample
10217 @need 1250
10218 @noindent
10219 and the @code{kill-ring-yank-pointer} points to the second clause, the
10220 value of @code{kill-ring-yank-pointer} is:
10222 @smallexample
10223 ("a different piece of text" "yet more text")
10224 @end smallexample
10226 As explained in the previous chapter (@pxref{List Implementation}), the
10227 computer does not keep two different copies of the text being pointed to
10228 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}.  The
10229 words ``a different piece of text'' and ``yet more text'' are not
10230 duplicated.  Instead, the two Lisp variables point to the same pieces of
10231 text.  Here is a diagram:
10233 @c cons-cell-diagram #5
10234 @ifnottex
10235 @smallexample
10236 @group
10237 kill-ring     kill-ring-yank-pointer
10238     |               |
10239     |      ___ ___  |     ___ ___      ___ ___
10240      ---> |   |   |  --> |   |   |    |   |   |
10241           |___|___|----> |___|___|--> |___|___|--> nil
10242             |              |            |
10243             |              |            |
10244             |              |             --> "yet more text"
10245             |              |
10246             |               --> "a different piece of text"
10247             |
10248              --> "some text"
10249 @end group
10250 @end smallexample
10251 @sp 1
10252 @end ifnottex
10253 @ifset print-postscript-figures
10254 @sp 1
10255 @tex
10256 @center @image{cons-5}
10257 %%%% old method of including an image
10258 % \input /usr/local/lib/tex/inputs/psfig.tex
10259 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
10260 % \catcode`\@=0 %
10261 @end tex
10262 @sp 1
10263 @end ifset
10264 @ifclear print-postscript-figures
10265 @iftex
10266 @smallexample
10267 @group
10268 kill-ring     kill-ring-yank-pointer
10269     |               |
10270     |      ___ ___  |     ___ ___      ___ ___
10271      ---> |   |   |  --> |   |   |    |   |   |
10272           |___|___|----> |___|___|--> |___|___|--> nil
10273             |              |            |
10274             |              |            |
10275             |              |             --> "yet more text"
10276             |              |
10277             |               --> "a different piece of text
10278             |
10279              --> "some text"
10280 @end group
10281 @end smallexample
10282 @sp 1
10283 @end iftex
10284 @end ifclear
10286 Both the variable @code{kill-ring} and the variable
10287 @code{kill-ring-yank-pointer} are pointers.  But the kill ring itself is
10288 usually described as if it were actually what it is composed of.  The
10289 @code{kill-ring} is spoken of as if it were the list rather than that it
10290 points to the list.  Conversely, the @code{kill-ring-yank-pointer} is
10291 spoken of as pointing to a list.
10293 These two ways of talking about the same thing sound confusing at first but
10294 make sense on reflection.  The kill ring is generally thought of as the
10295 complete structure of data that holds the information of what has recently
10296 been cut out of the Emacs buffers.  The @code{kill-ring-yank-pointer}
10297 on the other hand, serves to indicate---that is, to `point to'---that part
10298 of the kill ring of which the first element (the @sc{car}) will be
10299 inserted.
10301 @ignore
10302 In GNU Emacs 22, the @code{kill-new} function calls
10304 @code{(setq kill-ring-yank-pointer kill-ring)}
10306 (defun rotate-yank-pointer (arg)
10307   "Rotate the yanking point in the kill ring.
10308 With argument, rotate that many kills forward (or backward, if negative)."
10309   (interactive "p")
10310   (current-kill arg))
10312 (defun current-kill (n &optional do-not-move)
10313   "Rotate the yanking point by N places, and then return that kill.
10314 If N is zero, `interprogram-paste-function' is set, and calling it
10315 returns a string, then that string is added to the front of the
10316 kill ring and returned as the latest kill.
10317 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
10318 yanking point; just return the Nth kill forward."
10319   (let ((interprogram-paste (and (= n 0)
10320                                  interprogram-paste-function
10321                                  (funcall interprogram-paste-function))))
10322     (if interprogram-paste
10323         (progn
10324           ;; Disable the interprogram cut function when we add the new
10325           ;; text to the kill ring, so Emacs doesn't try to own the
10326           ;; selection, with identical text.
10327           (let ((interprogram-cut-function nil))
10328             (kill-new interprogram-paste))
10329           interprogram-paste)
10330       (or kill-ring (error "Kill ring is empty"))
10331       (let ((ARGth-kill-element
10332              (nthcdr (mod (- n (length kill-ring-yank-pointer))
10333                           (length kill-ring))
10334                      kill-ring)))
10335         (or do-not-move
10336             (setq kill-ring-yank-pointer ARGth-kill-element))
10337         (car ARGth-kill-element)))))
10339 @end ignore
10341 @need 1500
10342 @node yank nthcdr Exercises,  , kill-ring-yank-pointer, Yanking
10343 @section Exercises with @code{yank} and @code{nthcdr}
10345 @itemize @bullet
10346 @item
10347 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
10348 your kill ring.  Add several items to your kill ring; look at its
10349 value again.  Using @kbd{M-y} (@code{yank-pop)}, move all the way
10350 around the kill ring.  How many items were in your kill ring?  Find
10351 the value of @code{kill-ring-max}.  Was your kill ring full, or could
10352 you have kept more blocks of text within it?
10354 @item
10355 Using @code{nthcdr} and @code{car}, construct a series of expressions
10356 to return the first, second, third, and fourth elements of a list.
10357 @end itemize
10359 @node Loops & Recursion, Regexp Search, Yanking, Top
10360 @comment  node-name,  next,  previous,  up
10361 @chapter Loops and Recursion
10362 @cindex Loops and recursion
10363 @cindex Recursion and loops
10364 @cindex Repetition (loops)
10366 Emacs Lisp has two primary ways to cause an expression, or a series of
10367 expressions, to be evaluated repeatedly: one uses a @code{while}
10368 loop, and the other uses @dfn{recursion}.
10370 Repetition can be very valuable.  For example, to move forward four
10371 sentences, you need only write a program that will move forward one
10372 sentence and then repeat the process four times.  Since a computer does
10373 not get bored or tired, such repetitive action does not have the
10374 deleterious effects that excessive or the wrong kinds of repetition can
10375 have on humans.
10377 People mostly write Emacs Lisp functions using @code{while} loops and
10378 their kin; but you can use recursion, which provides a very powerful
10379 way to think about and then to solve problems@footnote{You can write
10380 recursive functions to be frugal or wasteful of mental or computer
10381 resources; as it happens, methods that people find easy---that are
10382 frugal of `mental resources'---sometimes use considerable computer
10383 resources.  Emacs was designed to run on machines that we now consider
10384 limited and its default settings are conservative.  You may want to
10385 increase the values of @code{max-specpdl-size} and
10386 @code{max-lisp-eval-depth}.  In my @file{.emacs} file, I set them to
10387 15 and 30 times their default value.}.
10389 @menu
10390 * while::                       Causing a stretch of code to repeat.
10391 * dolist dotimes::
10392 * Recursion::                   Causing a function to call itself.
10393 * Looping exercise::
10394 @end menu
10396 @node while, dolist dotimes, Loops & Recursion, Loops & Recursion
10397 @comment  node-name,  next,  previous,  up
10398 @section @code{while}
10399 @cindex Loops
10400 @findex while
10402 The @code{while} special form tests whether the value returned by
10403 evaluating its first argument is true or false.  This is similar to what
10404 the Lisp interpreter does with an @code{if}; what the interpreter does
10405 next, however, is different.
10407 In a @code{while} expression, if the value returned by evaluating the
10408 first argument is false, the Lisp interpreter skips the rest of the
10409 expression (the @dfn{body} of the expression) and does not evaluate it.
10410 However, if the value is true, the Lisp interpreter evaluates the body
10411 of the expression and then again tests whether the first argument to
10412 @code{while} is true or false.  If the value returned by evaluating the
10413 first argument is again true, the Lisp interpreter again evaluates the
10414 body of the expression.
10416 @need 1200
10417 The template for a @code{while} expression looks like this:
10419 @smallexample
10420 @group
10421 (while @var{true-or-false-test}
10422   @var{body}@dots{})
10423 @end group
10424 @end smallexample
10426 @menu
10427 * Looping with while::          Repeat so long as test returns true.
10428 * Loop Example::                A @code{while} loop that uses a list.
10429 * print-elements-of-list::      Uses @code{while}, @code{car}, @code{cdr}.
10430 * Incrementing Loop::           A loop with an incrementing counter.
10431 * Incrementing Loop Details::
10432 * Decrementing Loop::           A loop with a decrementing counter.
10433 @end menu
10435 @node Looping with while, Loop Example, while, while
10436 @ifnottex
10437 @unnumberedsubsec Looping with @code{while}
10438 @end ifnottex
10440 So long as the true-or-false-test of the @code{while} expression
10441 returns a true value when it is evaluated, the body is repeatedly
10442 evaluated.  This process is called a loop since the Lisp interpreter
10443 repeats the same thing again and again, like an airplane doing a loop.
10444 When the result of evaluating the true-or-false-test is false, the
10445 Lisp interpreter does not evaluate the rest of the @code{while}
10446 expression and `exits the loop'.
10448 Clearly, if the value returned by evaluating the first argument to
10449 @code{while} is always true, the body following will be evaluated
10450 again and again @dots{} and again @dots{} forever.  Conversely, if the
10451 value returned is never true, the expressions in the body will never
10452 be evaluated.  The craft of writing a @code{while} loop consists of
10453 choosing a mechanism such that the true-or-false-test returns true
10454 just the number of times that you want the subsequent expressions to
10455 be evaluated, and then have the test return false.
10457 The value returned by evaluating a @code{while} is the value of the
10458 true-or-false-test.  An interesting consequence of this is that a
10459 @code{while} loop that evaluates without error will return @code{nil}
10460 or false regardless of whether it has looped 1 or 100 times or none at
10461 all.  A @code{while} expression that evaluates successfully never
10462 returns a true value!  What this means is that @code{while} is always
10463 evaluated for its side effects, which is to say, the consequences of
10464 evaluating the expressions within the body of the @code{while} loop.
10465 This makes sense.  It is not the mere act of looping that is desired,
10466 but the consequences of what happens when the expressions in the loop
10467 are repeatedly evaluated.
10469 @node Loop Example, print-elements-of-list, Looping with while, while
10470 @comment  node-name,  next,  previous,  up
10471 @subsection A @code{while} Loop and a List
10473 A common way to control a @code{while} loop is to test whether a list
10474 has any elements.  If it does, the loop is repeated; but if it does not,
10475 the repetition is ended.  Since this is an important technique, we will
10476 create a short example to illustrate it.
10478 A simple way to test whether a list has elements is to evaluate the
10479 list: if it has no elements, it is an empty list and will return the
10480 empty list, @code{()}, which is a synonym for @code{nil} or false.  On
10481 the other hand, a list with elements will return those elements when it
10482 is evaluated.  Since Emacs Lisp considers as true any value that is not
10483 @code{nil}, a list that returns elements will test true in a
10484 @code{while} loop.
10486 @need 1200
10487 For example, you can set the variable @code{empty-list} to @code{nil} by
10488 evaluating the following @code{setq} expression:
10490 @smallexample
10491 (setq empty-list ())
10492 @end smallexample
10494 @noindent
10495 After evaluating the @code{setq} expression, you can evaluate the
10496 variable @code{empty-list} in the usual way, by placing the cursor after
10497 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
10498 echo area:
10500 @smallexample
10501 empty-list
10502 @end smallexample
10504 On the other hand, if you set a variable to be a list with elements, the
10505 list will appear when you evaluate the variable, as you can see by
10506 evaluating the following two expressions:
10508 @smallexample
10509 @group
10510 (setq animals '(gazelle giraffe lion tiger))
10512 animals
10513 @end group
10514 @end smallexample
10516 Thus, to create a @code{while} loop that tests whether there are any
10517 items in the list @code{animals}, the first part of the loop will be
10518 written like this:
10520 @smallexample
10521 @group
10522 (while animals
10523        @dots{}
10524 @end group
10525 @end smallexample
10527 @noindent
10528 When the @code{while} tests its first argument, the variable
10529 @code{animals} is evaluated.  It returns a list.  So long as the list
10530 has elements, the @code{while} considers the results of the test to be
10531 true; but when the list is empty, it considers the results of the test
10532 to be false.
10534 To prevent the @code{while} loop from running forever, some mechanism
10535 needs to be provided to empty the list eventually.  An oft-used
10536 technique is to have one of the subsequent forms in the @code{while}
10537 expression set the value of the list to be the @sc{cdr} of the list.
10538 Each time the @code{cdr} function is evaluated, the list will be made
10539 shorter, until eventually only the empty list will be left.  At this
10540 point, the test of the @code{while} loop will return false, and the
10541 arguments to the @code{while} will no longer be evaluated.
10543 For example, the list of animals bound to the variable @code{animals}
10544 can be set to be the @sc{cdr} of the original list with the
10545 following expression:
10547 @smallexample
10548 (setq animals (cdr animals))
10549 @end smallexample
10551 @noindent
10552 If you have evaluated the previous expressions and then evaluate this
10553 expression, you will see @code{(giraffe lion tiger)} appear in the echo
10554 area.  If you evaluate the expression again, @code{(lion tiger)} will
10555 appear in the echo area.  If you evaluate it again and yet again,
10556 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
10558 A template for a @code{while} loop that uses the @code{cdr} function
10559 repeatedly to cause the true-or-false-test eventually to test false
10560 looks like this:
10562 @smallexample
10563 @group
10564 (while @var{test-whether-list-is-empty}
10565   @var{body}@dots{}
10566   @var{set-list-to-cdr-of-list})
10567 @end group
10568 @end smallexample
10570 This test and use of @code{cdr} can be put together in a function that
10571 goes through a list and prints each element of the list on a line of its
10572 own.
10574 @node print-elements-of-list, Incrementing Loop, Loop Example, while
10575 @subsection An Example: @code{print-elements-of-list}
10576 @findex print-elements-of-list
10578 The @code{print-elements-of-list} function illustrates a @code{while}
10579 loop with a list.
10581 @cindex @file{*scratch*} buffer
10582 The function requires several lines for its output.  If you are
10583 reading this in a recent instance of GNU Emacs,
10584 @c GNU Emacs 21, GNU Emacs 22, or a later version,
10585 you can evaluate the following expression inside of Info, as usual.
10587 If you are using an earlier version of Emacs, you need to copy the
10588 necessary expressions to your @file{*scratch*} buffer and evaluate
10589 them there.  This is because the echo area had only one line in the
10590 earlier versions.
10592 You can copy the expressions by marking the beginning of the region
10593 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
10594 the end of the region and then copying the region using @kbd{M-w}
10595 (@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
10596 then provides visual feedback).  In the @file{*scratch*}
10597 buffer, you can yank the expressions back by typing @kbd{C-y}
10598 (@code{yank}).
10600 After you have copied the expressions to the @file{*scratch*} buffer,
10601 evaluate each expression in turn.  Be sure to evaluate the last
10602 expression, @code{(print-elements-of-list animals)}, by typing
10603 @kbd{C-u C-x C-e}, that is, by giving an argument to
10604 @code{eval-last-sexp}.  This will cause the result of the evaluation
10605 to be printed in the @file{*scratch*} buffer instead of being printed
10606 in the echo area.  (Otherwise you will see something like this in your
10607 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
10608 each @samp{^J} stands for a `newline'.)
10610 @need 1500
10611 In a recent instance of GNU Emacs, you can evaluate these expressions
10612 directly in the Info buffer, and the echo area will grow to show the
10613 results.
10615 @smallexample
10616 @group
10617 (setq animals '(gazelle giraffe lion tiger))
10619 (defun print-elements-of-list (list)
10620   "Print each element of LIST on a line of its own."
10621   (while list
10622     (print (car list))
10623     (setq list (cdr list))))
10625 (print-elements-of-list animals)
10626 @end group
10627 @end smallexample
10629 @need 1200
10630 @noindent
10631 When you evaluate the three expressions in sequence, you will see
10632 this:
10634 @smallexample
10635 @group
10636 gazelle
10638 giraffe
10640 lion
10642 tiger
10644 @end group
10645 @end smallexample
10647 Each element of the list is printed on a line of its own (that is what
10648 the function @code{print} does) and then the value returned by the
10649 function is printed.  Since the last expression in the function is the
10650 @code{while} loop, and since @code{while} loops always return
10651 @code{nil}, a @code{nil} is printed after the last element of the list.
10653 @node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while
10654 @comment  node-name,  next,  previous,  up
10655 @subsection A Loop with an Incrementing Counter
10657 A loop is not useful unless it stops when it ought.  Besides
10658 controlling a loop with a list, a common way of stopping a loop is to
10659 write the first argument as a test that returns false when the correct
10660 number of repetitions are complete.  This means that the loop must
10661 have a counter---an expression that counts how many times the loop
10662 repeats itself.
10664 @node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while
10665 @ifnottex
10666 @unnumberedsubsec Details of an Incrementing Loop
10667 @end ifnottex
10669 The test for a loop with an incrementing counter can be an expression
10670 such as @code{(< count desired-number)} which returns @code{t} for
10671 true if the value of @code{count} is less than the
10672 @code{desired-number} of repetitions and @code{nil} for false if the
10673 value of @code{count} is equal to or is greater than the
10674 @code{desired-number}.  The expression that increments the count can
10675 be a simple @code{setq} such as @code{(setq count (1+ count))}, where
10676 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
10677 argument.  (The expression @w{@code{(1+ count)}} has the same result
10678 as @w{@code{(+ count 1)}}, but is easier for a human to read.)
10680 @need 1250
10681 The template for a @code{while} loop controlled by an incrementing
10682 counter looks like this:
10684 @smallexample
10685 @group
10686 @var{set-count-to-initial-value}
10687 (while (< count desired-number)         ; @r{true-or-false-test}
10688   @var{body}@dots{}
10689   (setq count (1+ count)))              ; @r{incrementer}
10690 @end group
10691 @end smallexample
10693 @noindent
10694 Note that you need to set the initial value of @code{count}; usually it
10695 is set to 1.
10697 @menu
10698 * Incrementing Example::        Counting pebbles in a triangle.
10699 * Inc Example parts::           The parts of the function definition.
10700 * Inc Example altogether::      Putting the function definition together.
10701 @end menu
10703 @node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details
10704 @unnumberedsubsubsec  Example with incrementing counter
10706 Suppose you are playing on the beach and decide to make a triangle of
10707 pebbles, putting one pebble in the first row, two in the second row,
10708 three in the third row and so on, like this:
10710 @sp 1
10711 @c pebble diagram
10712 @ifnottex
10713 @smallexample
10714 @group
10715                *
10716               * *
10717              * * *
10718             * * * *
10719 @end group
10720 @end smallexample
10721 @end ifnottex
10722 @iftex
10723 @smallexample
10724 @group
10725                @bullet{}
10726               @bullet{} @bullet{}
10727              @bullet{} @bullet{} @bullet{}
10728             @bullet{} @bullet{} @bullet{} @bullet{}
10729 @end group
10730 @end smallexample
10731 @end iftex
10732 @sp 1
10734 @noindent
10735 (About 2500 years ago, Pythagoras and others developed the beginnings of
10736 number theory by considering questions such as this.)
10738 Suppose you want to know how many pebbles you will need to make a
10739 triangle with 7 rows?
10741 Clearly, what you need to do is add up the numbers from 1 to 7.  There
10742 are two ways to do this; start with the smallest number, one, and add up
10743 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
10744 number and add the list going down: 7, 6, 5, 4 and so on.  Because both
10745 mechanisms illustrate common ways of writing @code{while} loops, we will
10746 create two examples, one counting up and the other counting down.  In
10747 this first example, we will start with 1 and add 2, 3, 4 and so on.
10749 If you are just adding up a short list of numbers, the easiest way to do
10750 it is to add up all the numbers at once.  However, if you do not know
10751 ahead of time how many numbers your list will have, or if you want to be
10752 prepared for a very long list, then you need to design your addition so
10753 that what you do is repeat a simple process many times instead of doing
10754 a more complex process once.
10756 For example, instead of adding up all the pebbles all at once, what you
10757 can do is add the number of pebbles in the first row, 1, to the number
10758 in the second row, 2, and then add the total of those two rows to the
10759 third row, 3.  Then you can add the number in the fourth row, 4, to the
10760 total of the first three rows; and so on.
10762 The critical characteristic of the process is that each repetitive
10763 action is simple.  In this case, at each step we add only two numbers,
10764 the number of pebbles in the row and the total already found.  This
10765 process of adding two numbers is repeated again and again until the last
10766 row has been added to the total of all the preceding rows.  In a more
10767 complex loop the repetitive action might not be so simple, but it will
10768 be simpler than doing everything all at once.
10770 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details
10771 @unnumberedsubsubsec The parts of the function definition
10773 The preceding analysis gives us the bones of our function definition:
10774 first, we will need a variable that we can call @code{total} that will
10775 be the total number of pebbles.  This will be the value returned by
10776 the function.
10778 Second, we know that the function will require an argument: this
10779 argument will be the total number of rows in the triangle.  It can be
10780 called @code{number-of-rows}.
10782 Finally, we need a variable to use as a counter.  We could call this
10783 variable @code{counter}, but a better name is @code{row-number}.  That
10784 is because what the counter does in this function is count rows, and a
10785 program should be written to be as understandable as possible.
10787 When the Lisp interpreter first starts evaluating the expressions in the
10788 function, the value of @code{total} should be set to zero, since we have
10789 not added anything to it.  Then the function should add the number of
10790 pebbles in the first row to the total, and then add the number of
10791 pebbles in the second to the total, and then add the number of
10792 pebbles in the third row to the total, and so on, until there are no
10793 more rows left to add.
10795 Both @code{total} and @code{row-number} are used only inside the
10796 function, so they can be declared as local variables with @code{let}
10797 and given initial values.  Clearly, the initial value for @code{total}
10798 should be 0.  The initial value of @code{row-number} should be 1,
10799 since we start with the first row.  This means that the @code{let}
10800 statement will look like this:
10802 @smallexample
10803 @group
10804   (let ((total 0)
10805         (row-number 1))
10806     @var{body}@dots{})
10807 @end group
10808 @end smallexample
10810 After the internal variables are declared and bound to their initial
10811 values, we can begin the @code{while} loop.  The expression that serves
10812 as the test should return a value of @code{t} for true so long as the
10813 @code{row-number} is less than or equal to the @code{number-of-rows}.
10814 (If the expression tests true only so long as the row number is less
10815 than the number of rows in the triangle, the last row will never be
10816 added to the total; hence the row number has to be either less than or
10817 equal to the number of rows.)
10819 @need 1500
10820 @findex <= @r{(less than or equal)}
10821 Lisp provides the @code{<=} function that returns true if the value of
10822 its first argument is less than or equal to the value of its second
10823 argument and false otherwise.  So the expression that the @code{while}
10824 will evaluate as its test should look like this:
10826 @smallexample
10827 (<= row-number number-of-rows)
10828 @end smallexample
10830 The total number of pebbles can be found by repeatedly adding the number
10831 of pebbles in a row to the total already found.  Since the number of
10832 pebbles in the row is equal to the row number, the total can be found by
10833 adding the row number to the total.  (Clearly, in a more complex
10834 situation, the number of pebbles in the row might be related to the row
10835 number in a more complicated way; if this were the case, the row number
10836 would be replaced by the appropriate expression.)
10838 @smallexample
10839 (setq total (+ total row-number))
10840 @end smallexample
10842 @noindent
10843 What this does is set the new value of @code{total} to be equal to the
10844 sum of adding the number of pebbles in the row to the previous total.
10846 After setting the value of @code{total}, the conditions need to be
10847 established for the next repetition of the loop, if there is one.  This
10848 is done by incrementing the value of the @code{row-number} variable,
10849 which serves as a counter.  After the @code{row-number} variable has
10850 been incremented, the true-or-false-test at the beginning of the
10851 @code{while} loop tests whether its value is still less than or equal to
10852 the value of the @code{number-of-rows} and if it is, adds the new value
10853 of the @code{row-number} variable to the @code{total} of the previous
10854 repetition of the loop.
10856 @need 1200
10857 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
10858 @code{row-number} variable can be incremented with this expression:
10860 @smallexample
10861 (setq row-number (1+ row-number))
10862 @end smallexample
10864 @node Inc Example altogether,  , Inc Example parts, Incrementing Loop Details
10865 @unnumberedsubsubsec Putting the function definition together
10867 We have created the parts for the function definition; now we need to
10868 put them together.
10870 @need 800
10871 First, the contents of the @code{while} expression:
10873 @smallexample
10874 @group
10875 (while (<= row-number number-of-rows)   ; @r{true-or-false-test}
10876   (setq total (+ total row-number))
10877   (setq row-number (1+ row-number)))    ; @r{incrementer}
10878 @end group
10879 @end smallexample
10881 Along with the @code{let} expression varlist, this very nearly
10882 completes the body of the function definition.  However, it requires
10883 one final element, the need for which is somewhat subtle.
10885 The final touch is to place the variable @code{total} on a line by
10886 itself after the @code{while} expression.  Otherwise, the value returned
10887 by the whole function is the value of the last expression that is
10888 evaluated in the body of the @code{let}, and this is the value
10889 returned by the @code{while}, which is always @code{nil}.
10891 This may not be evident at first sight.  It almost looks as if the
10892 incrementing expression is the last expression of the whole function.
10893 But that expression is part of the body of the @code{while}; it is the
10894 last element of the list that starts with the symbol @code{while}.
10895 Moreover, the whole of the @code{while} loop is a list within the body
10896 of the @code{let}.
10898 @need 1250
10899 In outline, the function will look like this:
10901 @smallexample
10902 @group
10903 (defun @var{name-of-function} (@var{argument-list})
10904   "@var{documentation}@dots{}"
10905   (let (@var{varlist})
10906     (while (@var{true-or-false-test})
10907       @var{body-of-while}@dots{} )
10908     @dots{} ))                    ; @r{Need final expression here.}
10909 @end group
10910 @end smallexample
10912 The result of evaluating the @code{let} is what is going to be returned
10913 by the @code{defun} since the @code{let} is not embedded within any
10914 containing list, except for the @code{defun} as a whole.  However, if
10915 the @code{while} is the last element of the @code{let} expression, the
10916 function will always return @code{nil}.  This is not what we want!
10917 Instead, what we want is the value of the variable @code{total}.  This
10918 is returned by simply placing the symbol as the last element of the list
10919 starting with @code{let}.  It gets evaluated after the preceding
10920 elements of the list are evaluated, which means it gets evaluated after
10921 it has been assigned the correct value for the total.
10923 It may be easier to see this by printing the list starting with
10924 @code{let} all on one line.  This format makes it evident that the
10925 @var{varlist} and @code{while} expressions are the second and third
10926 elements of the list starting with @code{let}, and the @code{total} is
10927 the last element:
10929 @smallexample
10930 @group
10931 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
10932 @end group
10933 @end smallexample
10935 @need 1200
10936 Putting everything together, the @code{triangle} function definition
10937 looks like this:
10939 @smallexample
10940 @group
10941 (defun triangle (number-of-rows)    ; @r{Version with}
10942                                     ; @r{  incrementing counter.}
10943   "Add up the number of pebbles in a triangle.
10944 The first row has one pebble, the second row two pebbles,
10945 the third row three pebbles, and so on.
10946 The argument is NUMBER-OF-ROWS."
10947 @end group
10948 @group
10949   (let ((total 0)
10950         (row-number 1))
10951     (while (<= row-number number-of-rows)
10952       (setq total (+ total row-number))
10953       (setq row-number (1+ row-number)))
10954     total))
10955 @end group
10956 @end smallexample
10958 @need 1200
10959 After you have installed @code{triangle} by evaluating the function, you
10960 can try it out.  Here are two examples:
10962 @smallexample
10963 @group
10964 (triangle 4)
10966 (triangle 7)
10967 @end group
10968 @end smallexample
10970 @noindent
10971 The sum of the first four numbers is 10 and the sum of the first seven
10972 numbers is 28.
10974 @node Decrementing Loop,  , Incrementing Loop Details, while
10975 @comment  node-name,  next,  previous,  up
10976 @subsection Loop with a Decrementing Counter
10978 Another common way to write a @code{while} loop is to write the test
10979 so that it determines whether a counter is greater than zero.  So long
10980 as the counter is greater than zero, the loop is repeated.  But when
10981 the counter is equal to or less than zero, the loop is stopped.  For
10982 this to work, the counter has to start out greater than zero and then
10983 be made smaller and smaller by a form that is evaluated
10984 repeatedly.
10986 The test will be an expression such as @code{(> counter 0)} which
10987 returns @code{t} for true if the value of @code{counter} is greater
10988 than zero, and @code{nil} for false if the value of @code{counter} is
10989 equal to or less than zero.  The expression that makes the number
10990 smaller and smaller can be a simple @code{setq} such as @code{(setq
10991 counter (1- counter))}, where @code{1-} is a built-in function in
10992 Emacs Lisp that subtracts 1 from its argument.
10994 @need 1250
10995 The template for a decrementing @code{while} loop looks like this:
10997 @smallexample
10998 @group
10999 (while (> counter 0)                    ; @r{true-or-false-test}
11000   @var{body}@dots{}
11001   (setq counter (1- counter)))          ; @r{decrementer}
11002 @end group
11003 @end smallexample
11005 @menu
11006 * Decrementing Example::        More pebbles on the beach.
11007 * Dec Example parts::           The parts of the function definition.
11008 * Dec Example altogether::      Putting the function definition together.
11009 @end menu
11011 @node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
11012 @unnumberedsubsubsec Example with decrementing counter
11014 To illustrate a loop with a decrementing counter, we will rewrite the
11015 @code{triangle} function so the counter decreases to zero.
11017 This is the reverse of the earlier version of the function.  In this
11018 case, to find out how many pebbles are needed to make a triangle with
11019 3 rows, add the number of pebbles in the third row, 3, to the number
11020 in the preceding row, 2, and then add the total of those two rows to
11021 the row that precedes them, which is 1.
11023 Likewise, to find the number of pebbles in a triangle with 7 rows, add
11024 the number of pebbles in the seventh row, 7, to the number in the
11025 preceding row, which is 6, and then add the total of those two rows to
11026 the row that precedes them, which is 5, and so on.  As in the previous
11027 example, each addition only involves adding two numbers, the total of
11028 the rows already added up and the number of pebbles in the row that is
11029 being added to the total.  This process of adding two numbers is
11030 repeated again and again until there are no more pebbles to add.
11032 We know how many pebbles to start with: the number of pebbles in the
11033 last row is equal to the number of rows.  If the triangle has seven
11034 rows, the number of pebbles in the last row is 7.  Likewise, we know how
11035 many pebbles are in the preceding row: it is one less than the number in
11036 the row.
11038 @node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop
11039 @unnumberedsubsubsec The parts of the function definition
11041 We start with three variables: the total number of rows in the
11042 triangle; the number of pebbles in a row; and the total number of
11043 pebbles, which is what we want to calculate.  These variables can be
11044 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
11045 @code{total}, respectively.
11047 Both @code{total} and @code{number-of-pebbles-in-row} are used only
11048 inside the function and are declared with @code{let}.  The initial
11049 value of @code{total} should, of course, be zero.  However, the
11050 initial value of @code{number-of-pebbles-in-row} should be equal to
11051 the number of rows in the triangle, since the addition will start with
11052 the longest row.
11054 @need 1250
11055 This means that the beginning of the @code{let} expression will look
11056 like this:
11058 @smallexample
11059 @group
11060 (let ((total 0)
11061       (number-of-pebbles-in-row number-of-rows))
11062   @var{body}@dots{})
11063 @end group
11064 @end smallexample
11066 The total number of pebbles can be found by repeatedly adding the number
11067 of pebbles in a row to the total already found, that is, by repeatedly
11068 evaluating the following expression:
11070 @smallexample
11071 (setq total (+ total number-of-pebbles-in-row))
11072 @end smallexample
11074 @noindent
11075 After the @code{number-of-pebbles-in-row} is added to the @code{total},
11076 the @code{number-of-pebbles-in-row} should be decremented by one, since
11077 the next time the loop repeats, the preceding row will be
11078 added to the total.
11080 The number of pebbles in a preceding row is one less than the number of
11081 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
11082 used to compute the number of pebbles in the preceding row.  This can be
11083 done with the following expression:
11085 @smallexample
11086 @group
11087 (setq number-of-pebbles-in-row
11088       (1- number-of-pebbles-in-row))
11089 @end group
11090 @end smallexample
11092 Finally, we know that the @code{while} loop should stop making repeated
11093 additions when there are no pebbles in a row.  So the test for
11094 the @code{while} loop is simply:
11096 @smallexample
11097 (while (> number-of-pebbles-in-row 0)
11098 @end smallexample
11100 @node Dec Example altogether,  , Dec Example parts, Decrementing Loop
11101 @unnumberedsubsubsec Putting the function definition together
11103 We can put these expressions together to create a function definition
11104 that works.  However, on examination, we find that one of the local
11105 variables is unneeded!
11107 @need 1250
11108 The function definition looks like this:
11110 @smallexample
11111 @group
11112 ;;; @r{First subtractive version.}
11113 (defun triangle (number-of-rows)
11114   "Add up the number of pebbles in a triangle."
11115   (let ((total 0)
11116         (number-of-pebbles-in-row number-of-rows))
11117     (while (> number-of-pebbles-in-row 0)
11118       (setq total (+ total number-of-pebbles-in-row))
11119       (setq number-of-pebbles-in-row
11120             (1- number-of-pebbles-in-row)))
11121     total))
11122 @end group
11123 @end smallexample
11125 As written, this function works.
11127 However, we do not need @code{number-of-pebbles-in-row}.
11129 @cindex Argument as local variable
11130 When the @code{triangle} function is evaluated, the symbol
11131 @code{number-of-rows} will be bound to a number, giving it an initial
11132 value.  That number can be changed in the body of the function as if
11133 it were a local variable, without any fear that such a change will
11134 effect the value of the variable outside of the function.  This is a
11135 very useful characteristic of Lisp; it means that the variable
11136 @code{number-of-rows} can be used anywhere in the function where
11137 @code{number-of-pebbles-in-row} is used.
11139 @need 800
11140 Here is a second version of the function written a bit more cleanly:
11142 @smallexample
11143 @group
11144 (defun triangle (number)                ; @r{Second version.}
11145   "Return sum of numbers 1 through NUMBER inclusive."
11146   (let ((total 0))
11147     (while (> number 0)
11148       (setq total (+ total number))
11149       (setq number (1- number)))
11150     total))
11151 @end group
11152 @end smallexample
11154 In brief, a properly written @code{while} loop will consist of three parts:
11156 @enumerate
11157 @item
11158 A test that will return false after the loop has repeated itself the
11159 correct number of times.
11161 @item
11162 An expression the evaluation of which will return the value desired
11163 after being repeatedly evaluated.
11165 @item
11166 An expression to change the value passed to the true-or-false-test so
11167 that the test returns false after the loop has repeated itself the right
11168 number of times.
11169 @end enumerate
11171 @node dolist dotimes, Recursion, while, Loops & Recursion
11172 @comment  node-name,  next,  previous,  up
11173 @section Save your time: @code{dolist} and @code{dotimes}
11175 In addition to @code{while}, both @code{dolist} and @code{dotimes}
11176 provide for looping.  Sometimes these are quicker to write than the
11177 equivalent @code{while} loop.  Both are Lisp macros.  (@xref{Macros, ,
11178 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
11180 @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a
11181 list':  @code{dolist} automatically shortens the list each time it
11182 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
11183 each shorter version of the list to the first of its arguments.
11185 @code{dotimes} loops a specific number of times: you specify the number.
11187 @menu
11188 * dolist::
11189 * dotimes::
11190 @end menu
11192 @node dolist, dotimes, dolist dotimes, dolist dotimes
11193 @unnumberedsubsubsec The @code{dolist} Macro
11194 @findex dolist
11196 Suppose, for example, you want to reverse a list, so that
11197 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
11199 @need 1250
11200 In practice, you would use the @code{reverse} function, like this:
11202 @smallexample
11203 @group
11204 (setq animals '(gazelle giraffe lion tiger))
11206 (reverse animals)
11207 @end group
11208 @end smallexample
11210 @need 800
11211 @noindent
11212 Here is how you could reverse the list using a @code{while} loop:
11214 @smallexample
11215 @group
11216 (setq animals '(gazelle giraffe lion tiger))
11218 (defun reverse-list-with-while (list)
11219   "Using while, reverse the order of LIST."
11220   (let (value)  ; make sure list starts empty
11221     (while list
11222       (setq value (cons (car list) value))
11223       (setq list (cdr list)))
11224     value))
11226 (reverse-list-with-while animals)
11227 @end group
11228 @end smallexample
11230 @need 800
11231 @noindent
11232 And here is how you could use the @code{dolist} macro:
11234 @smallexample
11235 @group
11236 (setq animals '(gazelle giraffe lion tiger))
11238 (defun reverse-list-with-dolist (list)
11239   "Using dolist, reverse the order of LIST."
11240   (let (value)  ; make sure list starts empty
11241     (dolist (element list value)
11242       (setq value (cons element value)))))
11244 (reverse-list-with-dolist animals)
11245 @end group
11246 @end smallexample
11248 @need 1250
11249 @noindent
11250 In Info, you can place your cursor after the closing parenthesis of
11251 each expression and type @kbd{C-x C-e}; in each case, you should see
11253 @smallexample
11254 (tiger lion giraffe gazelle)
11255 @end smallexample
11257 @noindent
11258 in the echo area.
11260 For this example, the existing @code{reverse} function is obviously best.
11261 The @code{while} loop is just like our first example (@pxref{Loop
11262 Example, , A @code{while} Loop and a List}).  The @code{while} first
11263 checks whether the list has elements; if so, it constructs a new list
11264 by adding the first element of the list to the existing list (which in
11265 the first iteration of the loop is @code{nil}).  Since the second
11266 element is prepended in front of the first element, and the third
11267 element is prepended in front of the second element, the list is reversed.
11269 In the expression using a @code{while} loop,
11270 the @w{@code{(setq list (cdr list))}}
11271 expression shortens the list, so the @code{while} loop eventually
11272 stops.  In addition, it provides the @code{cons} expression with a new
11273 first element by creating a new and shorter list at each repetition of
11274 the loop.
11276 The @code{dolist} expression does very much the same as the
11277 @code{while} expression, except that the @code{dolist} macro does some
11278 of the work you have to do when writing a @code{while} expression.
11280 Like a @code{while} loop, a @code{dolist} loops.  What is different is
11281 that it automatically shortens the list each time it loops --- it
11282 `@sc{cdr}s down the list' on its own --- and it automatically binds
11283 the @sc{car} of each shorter version of the list to the first of its
11284 arguments.
11286 In the example, the @sc{car} of each shorter version of the list is
11287 referred to using the symbol @samp{element}, the list itself is called
11288 @samp{list}, and the value returned is called @samp{value}.  The
11289 remainder of the @code{dolist} expression is the body.
11291 The @code{dolist} expression binds the @sc{car} of each shorter
11292 version of the list to @code{element} and then evaluates the body of
11293 the expression; and repeats the loop.  The result is returned in
11294 @code{value}.
11296 @node dotimes,  , dolist, dolist dotimes
11297 @unnumberedsubsubsec The @code{dotimes} Macro
11298 @findex dotimes
11300 The @code{dotimes} macro is similar to @code{dolist}, except that it
11301 loops a specific number of times.
11303 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
11304 and so forth each time around the loop, and the value of the third
11305 argument is returned.  You need to provide the value of the second
11306 argument, which is how many times the macro loops.
11308 @need 1250
11309 For example, the following binds the numbers from 0 up to, but not
11310 including, the number 3 to the first argument, @var{number}, and then
11311 constructs a list of the three numbers.  (The first number is 0, the
11312 second number is 1, and the third number is 2; this makes a total of
11313 three numbers in all, starting with zero as the first number.)
11315 @smallexample
11316 @group
11317 (let (value)      ; otherwise a value is a void variable
11318   (dotimes (number 3 value)
11319     (setq value (cons number value))))
11321 @result{} (2 1 0)
11322 @end group
11323 @end smallexample
11325 @noindent
11326 @code{dotimes} returns @code{value}, so the way to use
11327 @code{dotimes} is to operate on some expression @var{number} number of
11328 times and then return the result, either as a list or an atom.
11330 @need 1250
11331 Here is an example of a @code{defun} that uses @code{dotimes} to add
11332 up the number of pebbles in a triangle.
11334 @smallexample
11335 @group
11336 (defun triangle-using-dotimes (number-of-rows)
11337   "Using dotimes, add up the number of pebbles in a triangle."
11338 (let ((total 0))  ; otherwise a total is a void variable
11339   (dotimes (number number-of-rows total)
11340     (setq total (+ total (1+ number))))))
11342 (triangle-using-dotimes 4)
11343 @end group
11344 @end smallexample
11346 @node Recursion, Looping exercise, dolist dotimes, Loops & Recursion
11347 @comment  node-name,  next,  previous,  up
11348 @section Recursion
11349 @cindex Recursion
11351 A recursive function contains code that tells the Lisp interpreter to
11352 call a program that runs exactly like itself, but with slightly
11353 different arguments.  The code runs exactly the same because it has
11354 the same name.  However, even though the program has the same name, it
11355 is not the same entity.  It is different.  In the jargon, it is a
11356 different `instance'.
11358 Eventually, if the program is written correctly, the `slightly
11359 different arguments' will become sufficiently different from the first
11360 arguments that the final instance will stop.
11362 @menu
11363 * Building Robots::             Same model, different serial number ...
11364 * Recursive Definition Parts::  Walk until you stop ...
11365 * Recursion with list::         Using a list as the test whether to recurse.
11366 * Recursive triangle function::
11367 * Recursion with cond::
11368 * Recursive Patterns::          Often used templates.
11369 * No Deferment::                Don't store up work ...
11370 * No deferment solution::
11371 @end menu
11373 @node Building Robots, Recursive Definition Parts, Recursion, Recursion
11374 @comment  node-name,  next,  previous,  up
11375 @subsection Building Robots: Extending the Metaphor
11376 @cindex Building robots
11377 @cindex Robots, building
11379 It is sometimes helpful to think of a running program as a robot that
11380 does a job.  In doing its job, a recursive function calls on a second
11381 robot to help it.  The second robot is identical to the first in every
11382 way, except that the second robot helps the first and has been
11383 passed different arguments than the first.
11385 In a recursive function, the second robot may call a third; and the
11386 third may call a fourth, and so on.  Each of these is a different
11387 entity; but all are clones.
11389 Since each robot has slightly different instructions---the arguments
11390 will differ from one robot to the next---the last robot should know
11391 when to stop.
11393 Let's expand on the metaphor in which a computer program is a robot.
11395 A function definition provides the blueprints for a robot.  When you
11396 install a function definition, that is, when you evaluate a
11397 @code{defun} special form, you install the necessary equipment to
11398 build robots.  It is as if you were in a factory, setting up an
11399 assembly line.  Robots with the same name are built according to the
11400 same blueprints.  So they have, as it were, the same `model number',
11401 but a different `serial number'.
11403 We often say that a recursive function `calls itself'.  What we mean
11404 is that the instructions in a recursive function cause the Lisp
11405 interpreter to run a different function that has the same name and
11406 does the same job as the first, but with different arguments.
11408 It is important that the arguments differ from one instance to the
11409 next; otherwise, the process will never stop.
11411 @node Recursive Definition Parts, Recursion with list, Building Robots, Recursion
11412 @comment  node-name,  next,  previous,  up
11413 @subsection The Parts of a Recursive Definition
11414 @cindex Parts of a Recursive Definition
11415 @cindex Recursive Definition Parts
11417 A recursive function typically contains a conditional expression which
11418 has three parts:
11420 @enumerate
11421 @item
11422 A true-or-false-test that determines whether the function is called
11423 again, here called the @dfn{do-again-test}.
11425 @item
11426 The name of the function.  When this name is called, a new instance of
11427 the function---a new robot, as it were---is created and told what to do.
11429 @item
11430 An expression that returns a different value each time the function is
11431 called, here called the @dfn{next-step-expression}.  Consequently, the
11432 argument (or arguments) passed to the new instance of the function
11433 will be different from that passed to the previous instance.  This
11434 causes the conditional expression, the @dfn{do-again-test}, to test
11435 false after the correct number of repetitions.
11436 @end enumerate
11438 Recursive functions can be much simpler than any other kind of
11439 function.  Indeed, when people first start to use them, they often look
11440 so mysteriously simple as to be incomprehensible.  Like riding a
11441 bicycle, reading a recursive function definition takes a certain knack
11442 which is hard at first but then seems simple.
11444 @need 1200
11445 There are several different common recursive patterns.  A very simple
11446 pattern looks like this:
11448 @smallexample
11449 @group
11450 (defun @var{name-of-recursive-function} (@var{argument-list})
11451   "@var{documentation}@dots{}"
11452   (if @var{do-again-test}
11453     @var{body}@dots{}
11454     (@var{name-of-recursive-function}
11455          @var{next-step-expression})))
11456 @end group
11457 @end smallexample
11459 Each time a recursive function is evaluated, a new instance of it is
11460 created and told what to do.  The arguments tell the instance what to do.
11462 An argument is bound to the value of the next-step-expression.  Each
11463 instance runs with a different value of the next-step-expression.
11465 The value in the next-step-expression is used in the do-again-test.
11467 The value returned by the next-step-expression is passed to the new
11468 instance of the function, which evaluates it (or some
11469 transmogrification of it) to determine whether to continue or stop.
11470 The next-step-expression is designed so that the do-again-test returns
11471 false when the function should no longer be repeated.
11473 The do-again-test is sometimes called the @dfn{stop condition},
11474 since it stops the repetitions when it tests false.
11476 @node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion
11477 @comment  node-name,  next,  previous,  up
11478 @subsection Recursion with a List
11480 The example of a @code{while} loop that printed the elements of a list
11481 of numbers can be written recursively.  Here is the code, including
11482 an expression to set the value of the variable @code{animals} to a list.
11484 If you are using GNU Emacs 20 or before, this example must be copied
11485 to the @file{*scratch*} buffer and each expression must be evaluated
11486 there.  Use @kbd{C-u C-x C-e} to evaluate the
11487 @code{(print-elements-recursively animals)} expression so that the
11488 results are printed in the buffer; otherwise the Lisp interpreter will
11489 try to squeeze the results into the one line of the echo area.
11491 Also, place your cursor immediately after the last closing parenthesis
11492 of the @code{print-elements-recursively} function, before the comment.
11493 Otherwise, the Lisp interpreter will try to evaluate the comment.
11495 If you are using a more recent version of Emacs, you can evaluate this
11496 expression directly in Info.
11498 @findex print-elements-recursively
11499 @smallexample
11500 @group
11501 (setq animals '(gazelle giraffe lion tiger))
11503 (defun print-elements-recursively (list)
11504   "Print each element of LIST on a line of its own.
11505 Uses recursion."
11506   (when list                            ; @r{do-again-test}
11507         (print (car list))              ; @r{body}
11508         (print-elements-recursively     ; @r{recursive call}
11509          (cdr list))))                  ; @r{next-step-expression}
11511 (print-elements-recursively animals)
11512 @end group
11513 @end smallexample
11515 The @code{print-elements-recursively} function first tests whether
11516 there is any content in the list; if there is, the function prints the
11517 first element of the list, the @sc{car} of the list.  Then the
11518 function `invokes itself', but gives itself as its argument, not the
11519 whole list, but the second and subsequent elements of the list, the
11520 @sc{cdr} of the list.
11522 Put another way, if the list is not empty, the function invokes
11523 another instance of code that is similar to the initial code, but is a
11524 different thread of execution, with different arguments than the first
11525 instance.
11527 Put in yet another way, if the list is not empty, the first robot
11528 assemblies a second robot and tells it what to do; the second robot is
11529 a different individual from the first, but is the same model.
11531 When the second evaluation occurs, the @code{when} expression is
11532 evaluated and if true, prints the first element of the list it
11533 receives as its argument (which is the second element of the original
11534 list).  Then the function `calls itself' with the @sc{cdr} of the list
11535 it is invoked with, which (the second time around) is the @sc{cdr} of
11536 the @sc{cdr} of the original list.
11538 Note that although we say that the function `calls itself', what we
11539 mean is that the Lisp interpreter assembles and instructs a new
11540 instance of the program.  The new instance is a clone of the first,
11541 but is a separate individual.
11543 Each time the function `invokes itself', it invokes itself on a
11544 shorter version of the original list.  It creates a new instance that
11545 works on a shorter list.
11547 Eventually, the function invokes itself on an empty list.  It creates
11548 a new instance whose argument is @code{nil}.  The conditional expression
11549 tests the value of @code{list}.  Since the value of @code{list} is
11550 @code{nil}, the @code{when} expression tests false so the then-part is
11551 not evaluated.  The function as a whole then returns @code{nil}.
11553 @need 1200
11554 When you evaluate @code{(print-elements-recursively animals)} in the
11555 @file{*scratch*} buffer, you see this result:
11557 @smallexample
11558 @group
11559 gazelle
11561 giraffe
11563 lion
11565 tiger
11567 @end group
11568 @end smallexample
11570 @need 2000
11571 @node Recursive triangle function, Recursion with cond, Recursion with list, Recursion
11572 @comment  node-name,  next,  previous,  up
11573 @subsection Recursion in Place of a Counter
11574 @findex triangle-recursively
11576 @need 1200
11577 The @code{triangle} function described in a previous section can also
11578 be written recursively.  It looks like this:
11580 @smallexample
11581 @group
11582 (defun triangle-recursively (number)
11583   "Return the sum of the numbers 1 through NUMBER inclusive.
11584 Uses recursion."
11585   (if (= number 1)                    ; @r{do-again-test}
11586       1                               ; @r{then-part}
11587     (+ number                         ; @r{else-part}
11588        (triangle-recursively          ; @r{recursive call}
11589         (1- number)))))               ; @r{next-step-expression}
11591 (triangle-recursively 7)
11592 @end group
11593 @end smallexample
11595 @noindent
11596 You can install this function by evaluating it and then try it by
11597 evaluating @code{(triangle-recursively 7)}.  (Remember to put your
11598 cursor immediately after the last parenthesis of the function
11599 definition, before the comment.)  The function evaluates to 28.
11601 To understand how this function works, let's consider what happens in the
11602 various cases when the function is passed 1, 2, 3, or 4 as the value of
11603 its argument.
11605 @menu
11606 * Recursive Example arg of 1 or 2::
11607 * Recursive Example arg of 3 or 4::
11608 @end menu
11610 @node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function
11611 @ifnottex
11612 @unnumberedsubsubsec An argument of 1 or 2
11613 @end ifnottex
11615 First, what happens if the value of the argument is 1?
11617 The function has an @code{if} expression after the documentation
11618 string.  It tests whether the value of @code{number} is equal to 1; if
11619 so, Emacs evaluates the then-part of the @code{if} expression, which
11620 returns the number 1 as the value of the function.  (A triangle with
11621 one row has one pebble in it.)
11623 Suppose, however, that the value of the argument is 2.  In this case,
11624 Emacs evaluates the else-part of the @code{if} expression.
11626 @need 1200
11627 The else-part consists of an addition, the recursive call to
11628 @code{triangle-recursively} and a decrementing action; and it looks like
11629 this:
11631 @smallexample
11632 (+ number (triangle-recursively (1- number)))
11633 @end smallexample
11635 When Emacs evaluates this expression, the innermost expression is
11636 evaluated first; then the other parts in sequence.  Here are the steps
11637 in detail:
11639 @table @i
11640 @item Step 1 @w{  } Evaluate the innermost expression.
11642 The innermost expression is @code{(1- number)} so Emacs decrements the
11643 value of @code{number} from 2 to 1.
11645 @item Step 2 @w{  } Evaluate the @code{triangle-recursively} function.
11647 The Lisp interpreter creates an individual instance of
11648 @code{triangle-recursively}.  It does not matter that this function is
11649 contained within itself.  Emacs passes the result Step 1 as the
11650 argument used by this instance of the @code{triangle-recursively}
11651 function
11653 In this case, Emacs evaluates @code{triangle-recursively} with an
11654 argument of 1.  This means that this evaluation of
11655 @code{triangle-recursively} returns 1.
11657 @item Step 3 @w{  } Evaluate the value of @code{number}.
11659 The variable @code{number} is the second element of the list that
11660 starts with @code{+}; its value is 2.
11662 @item Step 4 @w{  } Evaluate the @code{+} expression.
11664 The @code{+} expression receives two arguments, the first
11665 from the evaluation of @code{number} (Step 3) and the second from the
11666 evaluation of @code{triangle-recursively} (Step 2).
11668 The result of the addition is the sum of 2 plus 1, and the number 3 is
11669 returned, which is correct.  A triangle with two rows has three
11670 pebbles in it.
11671 @end table
11673 @node Recursive Example arg of 3 or 4,  , Recursive Example arg of 1 or 2, Recursive triangle function
11674 @unnumberedsubsubsec An argument of 3 or 4
11676 Suppose that @code{triangle-recursively} is called with an argument of
11679 @table @i
11680 @item Step 1 @w{  } Evaluate the do-again-test.
11682 The @code{if} expression is evaluated first.  This is the do-again
11683 test and returns false, so the else-part of the @code{if} expression
11684 is evaluated.  (Note that in this example, the do-again-test causes
11685 the function to call itself when it tests false, not when it tests
11686 true.)
11688 @item Step 2 @w{  } Evaluate the innermost expression of the else-part.
11690 The innermost expression of the else-part is evaluated, which decrements
11691 3 to 2.  This is the next-step-expression.
11693 @item Step 3 @w{  } Evaluate the @code{triangle-recursively} function.
11695 The number 2 is passed to the @code{triangle-recursively} function.
11697 We know what happens when Emacs evaluates @code{triangle-recursively} with
11698 an argument of 2.  After going through the sequence of actions described
11699 earlier, it returns a value of 3.  So that is what will happen here.
11701 @item Step 4 @w{  } Evaluate the addition.
11703 3 will be passed as an argument to the addition and will be added to the
11704 number with which the function was called, which is 3.
11705 @end table
11707 @noindent
11708 The value returned by the function as a whole will be 6.
11710 Now that we know what will happen when @code{triangle-recursively} is
11711 called with an argument of 3, it is evident what will happen if it is
11712 called with an argument of 4:
11714 @quotation
11715 @need 800
11716 In the recursive call, the evaluation of
11718 @smallexample
11719 (triangle-recursively (1- 4))
11720 @end smallexample
11722 @need 800
11723 @noindent
11724 will return the value of evaluating
11726 @smallexample
11727 (triangle-recursively 3)
11728 @end smallexample
11730 @noindent
11731 which is 6 and this value will be added to 4 by the addition in the
11732 third line.
11733 @end quotation
11735 @noindent
11736 The value returned by the function as a whole will be 10.
11738 Each time @code{triangle-recursively} is evaluated, it evaluates a
11739 version of itself---a different instance of itself---with a smaller
11740 argument, until the argument is small enough so that it does not
11741 evaluate itself.
11743 Note that this particular design for a recursive function
11744 requires that operations be deferred.
11746 Before @code{(triangle-recursively 7)} can calculate its answer, it
11747 must call @code{(triangle-recursively 6)}; and before
11748 @code{(triangle-recursively 6)} can calculate its answer, it must call
11749 @code{(triangle-recursively 5)}; and so on.  That is to say, the
11750 calculation that @code{(triangle-recursively 7)} makes must be
11751 deferred until @code{(triangle-recursively 6)} makes its calculation;
11752 and @code{(triangle-recursively 6)} must defer until
11753 @code{(triangle-recursively 5)} completes; and so on.
11755 If each of these instances of @code{triangle-recursively} are thought
11756 of as different robots, the first robot must wait for the second to
11757 complete its job, which must wait until the third completes, and so
11760 There is a way around this kind of waiting, which we will discuss in
11761 @ref{No Deferment, , Recursion without Deferments}.
11763 @node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion
11764 @comment  node-name,  next,  previous,  up
11765 @subsection Recursion Example Using @code{cond}
11766 @findex cond
11768 The version of @code{triangle-recursively} described earlier is written
11769 with the @code{if} special form.  It can also be written using another
11770 special form called @code{cond}.  The name of the special form
11771 @code{cond} is an abbreviation of the word @samp{conditional}.
11773 Although the @code{cond} special form is not used as often in the
11774 Emacs Lisp sources as @code{if}, it is used often enough to justify
11775 explaining it.
11777 @need 800
11778 The template for a @code{cond} expression looks like this:
11780 @smallexample
11781 @group
11782 (cond
11783  @var{body}@dots{})
11784 @end group
11785 @end smallexample
11787 @noindent
11788 where the @var{body} is a series of lists.
11790 @need 800
11791 Written out more fully, the template looks like this:
11793 @smallexample
11794 @group
11795 (cond
11796  (@var{first-true-or-false-test} @var{first-consequent})
11797  (@var{second-true-or-false-test} @var{second-consequent})
11798  (@var{third-true-or-false-test} @var{third-consequent})
11799   @dots{})
11800 @end group
11801 @end smallexample
11803 When the Lisp interpreter evaluates the @code{cond} expression, it
11804 evaluates the first element (the @sc{car} or true-or-false-test) of
11805 the first expression in a series of expressions within the body of the
11806 @code{cond}.
11808 If the true-or-false-test returns @code{nil} the rest of that
11809 expression, the consequent, is skipped and  the true-or-false-test of the
11810 next expression is evaluated.  When an expression is found whose
11811 true-or-false-test returns a value that is not @code{nil}, the
11812 consequent of that expression is evaluated.  The consequent can be one
11813 or more expressions.  If the consequent consists of more than one
11814 expression, the expressions are evaluated in sequence and the value of
11815 the last one is returned.  If the expression does not have a consequent,
11816 the value of the true-or-false-test is returned.
11818 If none of the true-or-false-tests test true, the @code{cond} expression
11819 returns @code{nil}.
11821 @need 1250
11822 Written using @code{cond}, the @code{triangle} function looks like this:
11824 @smallexample
11825 @group
11826 (defun triangle-using-cond (number)
11827   (cond ((<= number 0) 0)
11828         ((= number 1) 1)
11829         ((> number 1)
11830          (+ number (triangle-using-cond (1- number))))))
11831 @end group
11832 @end smallexample
11834 @noindent
11835 In this example, the @code{cond} returns 0 if the number is less than or
11836 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
11837 number (triangle-using-cond (1- number)))} if the number is greater than
11840 @node Recursive Patterns, No Deferment, Recursion with cond, Recursion
11841 @comment  node-name,  next,  previous,  up
11842 @subsection Recursive Patterns
11843 @cindex Recursive Patterns
11845 Here are three common recursive patterns.  Each involves a list.
11846 Recursion does not need to involve lists, but Lisp is designed for lists
11847 and this provides a sense of its primal capabilities.
11849 @menu
11850 * Every::
11851 * Accumulate::
11852 * Keep::
11853 @end menu
11855 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
11856 @comment  node-name,  next,  previous,  up
11857 @unnumberedsubsubsec Recursive Pattern: @emph{every}
11858 @cindex Every, type of recursive pattern
11859 @cindex Recursive pattern: every
11861 In the @code{every} recursive pattern, an action is performed on every
11862 element of a list.
11864 @need 1500
11865 The basic pattern is:
11867 @itemize @bullet
11868 @item
11869 If a list be empty, return @code{nil}.
11870 @item
11871 Else, act on the beginning of the list (the @sc{car} of the list)
11872     @itemize @minus
11873     @item
11874     through a recursive call by the function on the rest (the
11875     @sc{cdr}) of the list,
11876     @item
11877     and, optionally, combine the acted-on element, using @code{cons},
11878     with the results of acting on the rest.
11879     @end itemize
11880 @end itemize
11882 @need 1500
11883 Here is example:
11885 @smallexample
11886 @group
11887 (defun square-each (numbers-list)
11888   "Square each of a NUMBERS LIST, recursively."
11889   (if (not numbers-list)                ; do-again-test
11890       nil
11891     (cons
11892      (* (car numbers-list) (car numbers-list))
11893      (square-each (cdr numbers-list))))) ; next-step-expression
11894 @end group
11896 @group
11897 (square-each '(1 2 3))
11898     @result{} (1 4 9)
11899 @end group
11900 @end smallexample
11902 @need 1200
11903 @noindent
11904 If @code{numbers-list} is empty, do nothing.  But if it has content,
11905 construct a list combining the square of the first number in the list
11906 with the result of the recursive call.
11908 (The example follows the pattern exactly: @code{nil} is returned if
11909 the numbers' list is empty.  In practice, you would write the
11910 conditional so it carries out the action when the numbers' list is not
11911 empty.)
11913 The @code{print-elements-recursively} function (@pxref{Recursion with
11914 list, , Recursion with a List}) is another example of an @code{every}
11915 pattern, except in this case, rather than bring the results together
11916 using @code{cons}, we print each element of output.
11918 @need 1250
11919 The @code{print-elements-recursively} function looks like this:
11921 @smallexample
11922 @group
11923 (setq animals '(gazelle giraffe lion tiger))
11924 @end group
11926 @group
11927 (defun print-elements-recursively (list)
11928   "Print each element of LIST on a line of its own.
11929 Uses recursion."
11930   (when list                            ; @r{do-again-test}
11931         (print (car list))              ; @r{body}
11932         (print-elements-recursively     ; @r{recursive call}
11933          (cdr list))))                  ; @r{next-step-expression}
11935 (print-elements-recursively animals)
11936 @end group
11937 @end smallexample
11939 @need 1500
11940 The pattern for @code{print-elements-recursively} is:
11942 @itemize @bullet
11943 @item
11944 When the list is empty, do nothing.
11945 @item
11946 But when the list has at least one element,
11947     @itemize @minus
11948     @item
11949     act on the beginning of the list (the @sc{car} of the list),
11950     @item
11951     and make a recursive call on the rest (the @sc{cdr}) of the list.
11952     @end itemize
11953 @end itemize
11955 @node Accumulate, Keep, Every, Recursive Patterns
11956 @comment  node-name,  next,  previous,  up
11957 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
11958 @cindex Accumulate, type of recursive pattern
11959 @cindex Recursive pattern: accumulate
11961 Another recursive pattern is called the @code{accumulate} pattern.  In
11962 the @code{accumulate} recursive pattern, an action is performed on
11963 every element of a list and the result of that action is accumulated
11964 with the results of performing the action on the other elements.
11966 This is very like the `every' pattern using @code{cons}, except that
11967 @code{cons} is not used, but some other combiner.
11969 @need 1500
11970 The pattern is:
11972 @itemize @bullet
11973 @item
11974 If a list be empty, return zero or some other constant.
11975 @item
11976 Else, act on the beginning of the list (the @sc{car} of the list),
11977     @itemize @minus
11978     @item
11979     and combine that acted-on element, using @code{+} or
11980     some other combining function, with
11981     @item
11982     a recursive call by the function on the rest (the @sc{cdr}) of the list.
11983     @end itemize
11984 @end itemize
11986 @need 1500
11987 Here is an example:
11989 @smallexample
11990 @group
11991 (defun add-elements (numbers-list)
11992   "Add the elements of NUMBERS-LIST together."
11993   (if (not numbers-list)
11994       0
11995     (+ (car numbers-list) (add-elements (cdr numbers-list)))))
11996 @end group
11998 @group
11999 (add-elements '(1 2 3 4))
12000     @result{} 10
12001 @end group
12002 @end smallexample
12004 @xref{Files List, , Making a List of Files}, for an example of the
12005 accumulate pattern.
12007 @node Keep,  , Accumulate, Recursive Patterns
12008 @comment  node-name,  next,  previous,  up
12009 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
12010 @cindex Keep, type of recursive pattern
12011 @cindex Recursive pattern: keep
12013 A third recursive pattern is called the @code{keep} pattern.
12014 In the @code{keep} recursive pattern, each element of a list is tested;
12015 the element is acted on and the results are kept only if the element
12016 meets a criterion.
12018 Again, this is very like the `every' pattern, except the element is
12019 skipped unless it meets a criterion.
12021 @need 1500
12022 The pattern has three parts:
12024 @itemize @bullet
12025 @item
12026 If a list be empty, return @code{nil}.
12027 @item
12028 Else, if the beginning of the list (the @sc{car} of the list) passes
12029         a test
12030     @itemize @minus
12031     @item
12032     act on that element and combine it, using @code{cons} with
12033     @item
12034     a recursive call by the function on the rest (the @sc{cdr}) of the list.
12035     @end itemize
12036 @item
12037 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
12038 the test
12039     @itemize @minus
12040     @item
12041     skip on that element,
12042     @item
12043     and, recursively call the function on the rest (the @sc{cdr}) of the list.
12044     @end itemize
12045 @end itemize
12047 @need 1500
12048 Here is an example that uses @code{cond}:
12050 @smallexample
12051 @group
12052 (defun keep-three-letter-words (word-list)
12053   "Keep three letter words in WORD-LIST."
12054   (cond
12055    ;; First do-again-test: stop-condition
12056    ((not word-list) nil)
12058    ;; Second do-again-test: when to act
12059    ((eq 3 (length (symbol-name (car word-list))))
12060     ;; combine acted-on element with recursive call on shorter list
12061     (cons (car word-list) (keep-three-letter-words (cdr word-list))))
12063    ;; Third do-again-test: when to skip element;
12064    ;;   recursively call shorter list with next-step expression
12065    (t (keep-three-letter-words (cdr word-list)))))
12066 @end group
12068 @group
12069 (keep-three-letter-words '(one two three four five six))
12070     @result{} (one two six)
12071 @end group
12072 @end smallexample
12074 It goes without saying that you need not use @code{nil} as the test for
12075 when to stop; and you can, of course, combine these patterns.
12077 @node No Deferment, No deferment solution, Recursive Patterns, Recursion
12078 @subsection Recursion without Deferments
12079 @cindex Deferment in recursion
12080 @cindex Recursion without Deferments
12082 Let's consider again what happens with the @code{triangle-recursively}
12083 function.  We will find that the intermediate calculations are
12084 deferred until all can be done.
12086 @need 800
12087 Here is the function definition:
12089 @smallexample
12090 @group
12091 (defun triangle-recursively (number)
12092   "Return the sum of the numbers 1 through NUMBER inclusive.
12093 Uses recursion."
12094   (if (= number 1)                    ; @r{do-again-test}
12095       1                               ; @r{then-part}
12096     (+ number                         ; @r{else-part}
12097        (triangle-recursively          ; @r{recursive call}
12098         (1- number)))))               ; @r{next-step-expression}
12099 @end group
12100 @end smallexample
12102 What happens when we call this function with a argument of 7?
12104 The first instance of the @code{triangle-recursively} function adds
12105 the number 7 to the value returned by a second instance of
12106 @code{triangle-recursively}, an instance that has been passed an
12107 argument of 6.  That is to say, the first calculation is:
12109 @smallexample
12110 (+ 7 (triangle-recursively 6))
12111 @end smallexample
12113 @noindent
12114 The first instance of @code{triangle-recursively}---you may want to
12115 think of it as a little robot---cannot complete its job.  It must hand
12116 off the calculation for @code{(triangle-recursively 6)} to a second
12117 instance of the program, to a second robot.  This second individual is
12118 completely different from the first one; it is, in the jargon, a
12119 `different instantiation'.  Or, put another way, it is a different
12120 robot.  It is the same model as the first; it calculates triangle
12121 numbers recursively; but it has a different serial number.
12123 And what does @code{(triangle-recursively 6)} return?  It returns the
12124 number 6 added to the value returned by evaluating
12125 @code{triangle-recursively} with an argument of 5.  Using the robot
12126 metaphor, it asks yet another robot to help it.
12128 @need 800
12129 Now the total is:
12131 @smallexample
12132 (+ 7 6 (triangle-recursively 5))
12133 @end smallexample
12135 @need 800
12136 And what happens next?
12138 @smallexample
12139 (+ 7 6 5 (triangle-recursively 4))
12140 @end smallexample
12142 Each time @code{triangle-recursively} is called, except for the last
12143 time, it creates another instance of the program---another robot---and
12144 asks it to make a calculation.
12146 @need 800
12147 Eventually, the full addition is set up and performed:
12149 @smallexample
12150 (+ 7 6 5 4 3 2 1)
12151 @end smallexample
12153 This design for the function defers the calculation of the first step
12154 until the second can be done, and defers that until the third can be
12155 done, and so on.  Each deferment means the computer must remember what
12156 is being waited on.  This is not a problem when there are only a few
12157 steps, as in this example.  But it can be a problem when there are
12158 more steps.
12160 @node No deferment solution,  , No Deferment, Recursion
12161 @subsection No Deferment Solution
12162 @cindex No deferment solution
12163 @cindex Defermentless solution
12164 @cindex Solution without deferment
12166 The solution to the problem of deferred operations is to write in a
12167 manner that does not defer operations@footnote{The phrase @dfn{tail
12168 recursive} is used to describe such a process, one that uses
12169 `constant space'.}.  This requires
12170 writing to a different pattern, often one that involves writing two
12171 function definitions, an `initialization' function and a `helper'
12172 function.
12174 The `initialization' function sets up the job; the `helper' function
12175 does the work.
12177 @need 1200
12178 Here are the two function definitions for adding up numbers.  They are
12179 so simple, I find them hard to understand.
12181 @smallexample
12182 @group
12183 (defun triangle-initialization (number)
12184   "Return the sum of the numbers 1 through NUMBER inclusive.
12185 This is the `initialization' component of a two function
12186 duo that uses recursion."
12187   (triangle-recursive-helper 0 0 number))
12188 @end group
12189 @end smallexample
12191 @smallexample
12192 @group
12193 (defun triangle-recursive-helper (sum counter number)
12194   "Return SUM, using COUNTER, through NUMBER inclusive.
12195 This is the `helper' component of a two function duo
12196 that uses recursion."
12197   (if (> counter number)
12198       sum
12199     (triangle-recursive-helper (+ sum counter)  ; @r{sum}
12200                                (1+ counter)     ; @r{counter}
12201                                number)))        ; @r{number}
12202 @end group
12203 @end smallexample
12205 @need 1250
12206 Install both function definitions by evaluating them, then call
12207 @code{triangle-initialization} with 2 rows:
12209 @smallexample
12210 @group
12211 (triangle-initialization 2)
12212     @result{} 3
12213 @end group
12214 @end smallexample
12216 The `initialization' function calls the first instance of the `helper'
12217 function with three arguments: zero, zero, and a number which is the
12218 number of rows in the triangle.
12220 The first two arguments passed to the `helper' function are
12221 initialization values.  These values are changed when
12222 @code{triangle-recursive-helper} invokes new instances.@footnote{The
12223 jargon is mildly confusing:  @code{triangle-recursive-helper} uses a
12224 process that is iterative in a procedure that is recursive.  The
12225 process is called iterative because the computer need only record the
12226 three values, @code{sum}, @code{counter}, and @code{number}; the
12227 procedure is recursive because the function `calls itself'.  On the
12228 other hand, both the process and the procedure used by
12229 @code{triangle-recursively} are called recursive.  The word
12230 `recursive' has different meanings in the two contexts.}
12232 Let's see what happens when we have a triangle that has one row.  (This
12233 triangle will have one pebble in it!)
12235 @need 1200
12236 @code{triangle-initialization} will call its helper with
12237 the arguments @w{@code{0 0 1}}.  That function will run the conditional
12238 test whether @code{(> counter number)}:
12240 @smallexample
12241 (> 0 1)
12242 @end smallexample
12244 @need 1200
12245 @noindent
12246 and find that the result is false, so it will invoke
12247 the else-part of the @code{if} clause:
12249 @smallexample
12250 @group
12251     (triangle-recursive-helper
12252      (+ sum counter)  ; @r{sum plus counter} @result{} @r{sum}
12253      (1+ counter)     ; @r{increment counter} @result{} @r{counter}
12254      number)          ; @r{number stays the same}
12255 @end group
12256 @end smallexample
12258 @need 800
12259 @noindent
12260 which will first compute:
12262 @smallexample
12263 @group
12264 (triangle-recursive-helper (+ 0 0)  ; @r{sum}
12265                            (1+ 0)   ; @r{counter}
12266                            1)       ; @r{number}
12267 @exdent which is:
12269 (triangle-recursive-helper 0 1 1)
12270 @end group
12271 @end smallexample
12273 Again, @code{(> counter number)} will be false, so again, the Lisp
12274 interpreter will evaluate @code{triangle-recursive-helper}, creating a
12275 new instance with new arguments.
12277 @need 800
12278 This new instance will be;
12280 @smallexample
12281 @group
12282     (triangle-recursive-helper
12283      (+ sum counter)  ; @r{sum plus counter} @result{} @r{sum}
12284      (1+ counter)     ; @r{increment counter} @result{} @r{counter}
12285      number)          ; @r{number stays the same}
12287 @exdent which is:
12289 (triangle-recursive-helper 1 2 1)
12290 @end group
12291 @end smallexample
12293 In this case, the @code{(> counter number)} test will be true!  So the
12294 instance will return the value of the sum, which will be 1, as
12295 expected.
12297 Now, let's pass @code{triangle-initialization} an argument
12298 of 2, to find out how many pebbles there are in a triangle with two rows.
12300 That function calls @code{(triangle-recursive-helper 0 0 2)}.
12302 @need 800
12303 In stages, the instances called will be:
12305 @smallexample
12306 @group
12307                           @r{sum counter number}
12308 (triangle-recursive-helper 0    1       2)
12310 (triangle-recursive-helper 1    2       2)
12312 (triangle-recursive-helper 3    3       2)
12313 @end group
12314 @end smallexample
12316 When the last instance is called, the @code{(> counter number)} test
12317 will be true, so the instance will return the value of @code{sum},
12318 which will be 3.
12320 This kind of pattern helps when you are writing functions that can use
12321 many resources in a computer.
12323 @need 1500
12324 @node Looping exercise,  , Recursion, Loops & Recursion
12325 @section Looping Exercise
12327 @itemize @bullet
12328 @item
12329 Write a function similar to @code{triangle} in which each row has a
12330 value which is the square of the row number.  Use a @code{while} loop.
12332 @item
12333 Write a function similar to @code{triangle} that multiplies instead of
12334 adds the values.
12336 @item
12337 Rewrite these two functions recursively.  Rewrite these functions
12338 using @code{cond}.
12340 @c comma in printed title causes problem in Info cross reference
12341 @item
12342 Write a function for Texinfo mode that creates an index entry at the
12343 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
12344 (In a Texinfo file, @samp{@@dfn} marks a definition.  This book is
12345 written in Texinfo.)
12347 Many of the functions you will need are described in two of the
12348 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
12349 Text}, and @ref{Yanking, , Yanking Text Back}.  If you use
12350 @code{forward-paragraph} to put the index entry at the beginning of
12351 the paragraph, you will have to use @w{@kbd{C-h f}}
12352 (@code{describe-function}) to find out how to make the command go
12353 backwards.
12355 For more information, see
12356 @ifinfo
12357 @ref{Indicating, , Indicating Definitions, texinfo}.
12358 @end ifinfo
12359 @ifhtml
12360 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
12361 a Texinfo manual in the current directory.  Or, if you are on the
12362 Internet, see
12363 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
12364 @end ifhtml
12365 @iftex
12366 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
12367 Documentation Format}.
12368 @end iftex
12369 @end itemize
12371 @node Regexp Search, Counting Words, Loops & Recursion, Top
12372 @comment  node-name,  next,  previous,  up
12373 @chapter Regular Expression Searches
12374 @cindex Searches, illustrating
12375 @cindex Regular expression searches
12376 @cindex Patterns, searching for
12377 @cindex Motion by sentence and paragraph
12378 @cindex Sentences, movement by
12379 @cindex Paragraphs, movement by
12381 Regular expression searches are used extensively in GNU Emacs.  The
12382 two functions, @code{forward-sentence} and @code{forward-paragraph},
12383 illustrate these searches well.  They use regular expressions to find
12384 where to move point.  The phrase `regular expression' is often written
12385 as `regexp'.
12387 Regular expression searches are described in @ref{Regexp Search, ,
12388 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
12389 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
12390 Manual}.  In writing this chapter, I am presuming that you have at
12391 least a mild acquaintance with them.  The major point to remember is
12392 that regular expressions permit you to search for patterns as well as
12393 for literal strings of characters.  For example, the code in
12394 @code{forward-sentence} searches for the pattern of possible
12395 characters that could mark the end of a sentence, and moves point to
12396 that spot.
12398 Before looking at the code for the @code{forward-sentence} function, it
12399 is worth considering what the pattern that marks the end of a sentence
12400 must be.  The pattern is discussed in the next section; following that
12401 is a description of the regular expression search function,
12402 @code{re-search-forward}.  The @code{forward-sentence} function
12403 is described in the section following.  Finally, the
12404 @code{forward-paragraph} function is described in the last section of
12405 this chapter.  @code{forward-paragraph} is a complex function that
12406 introduces several new features.
12408 @menu
12409 * sentence-end::                The regular expression for @code{sentence-end}.
12410 * re-search-forward::           Very similar to @code{search-forward}.
12411 * forward-sentence::            A straightforward example of regexp search.
12412 * forward-paragraph::           A somewhat complex example.
12413 * etags::                       How to create your own @file{TAGS} table.
12414 * Regexp Review::
12415 * re-search Exercises::
12416 @end menu
12418 @node sentence-end, re-search-forward, Regexp Search, Regexp Search
12419 @comment  node-name,  next,  previous,  up
12420 @section The Regular Expression for @code{sentence-end}
12421 @findex sentence-end
12423 The symbol @code{sentence-end} is bound to the pattern that marks the
12424 end of a sentence.  What should this regular expression be?
12426 Clearly, a sentence may be ended by a period, a question mark, or an
12427 exclamation mark.  Indeed, in English, only clauses that end with one
12428 of those three characters should be considered the end of a sentence.
12429 This means that the pattern should include the character set:
12431 @smallexample
12432 [.?!]
12433 @end smallexample
12435 However, we do not want @code{forward-sentence} merely to jump to a
12436 period, a question mark, or an exclamation mark, because such a character
12437 might be used in the middle of a sentence.  A period, for example, is
12438 used after abbreviations.  So other information is needed.
12440 According to convention, you type two spaces after every sentence, but
12441 only one space after a period, a question mark, or an exclamation mark in
12442 the body of a sentence.  So a period, a question mark, or an exclamation
12443 mark followed by two spaces is a good indicator of an end of sentence.
12444 However, in a file, the two spaces may instead be a tab or the end of a
12445 line.  This means that the regular expression should include these three
12446 items as alternatives.
12448 @need 800
12449 This group of alternatives will look like this:
12451 @smallexample
12452 @group
12453 \\($\\| \\|  \\)
12454        ^   ^^
12455       TAB  SPC
12456 @end group
12457 @end smallexample
12459 @noindent
12460 Here, @samp{$} indicates the end of the line, and I have pointed out
12461 where the tab and two spaces are inserted in the expression.  Both are
12462 inserted by putting the actual characters into the expression.
12464 Two backslashes, @samp{\\}, are required before the parentheses and
12465 vertical bars: the first backslash quotes the following backslash in
12466 Emacs; and the second indicates that the following character, the
12467 parenthesis or the vertical bar, is special.
12469 @need 1000
12470 Also, a sentence may be followed by one or more carriage returns, like
12471 this:
12473 @smallexample
12474 @group
12477 @end group
12478 @end smallexample
12480 @noindent
12481 Like tabs and spaces, a carriage return is inserted into a regular
12482 expression by inserting it literally.  The asterisk indicates that the
12483 @key{RET} is repeated zero or more times.
12485 But a sentence end does not consist only of a period, a question mark or
12486 an exclamation mark followed by appropriate space: a closing quotation
12487 mark or a closing brace of some kind may precede the space.  Indeed more
12488 than one such mark or brace may precede the space.  These require a
12489 expression that looks like this:
12491 @smallexample
12492 []\"')@}]*
12493 @end smallexample
12495 In this expression, the first @samp{]} is the first character in the
12496 expression; the second character is @samp{"}, which is preceded by a
12497 @samp{\} to tell Emacs the @samp{"} is @emph{not} special.  The last
12498 three characters are @samp{'}, @samp{)}, and @samp{@}}.
12500 All this suggests what the regular expression pattern for matching the
12501 end of a sentence should be; and, indeed, if we evaluate
12502 @code{sentence-end} we find that it returns the following value:
12504 @smallexample
12505 @group
12506 sentence-end
12507      @result{} "[.?!][]\"')@}]*\\($\\|     \\|  \\)[
12509 @end group
12510 @end smallexample
12512 @noindent
12513 (Well, not in GNU Emacs 22; that is because of an effort to make the
12514 process simpler and to handle more glyphs and languages.  When the
12515 value of @code{sentence-end} is @code{nil}, then use the value defined
12516 by the function @code{sentence-end}.  (Here is a use of the difference
12517 between a value and a function in Emacs Lisp.)  The function returns a
12518 value constructed from the variables @code{sentence-end-base},
12519 @code{sentence-end-double-space}, @code{sentence-end-without-period},
12520 and @code{sentence-end-without-space}.  The critical variable is
12521 @code{sentence-end-base}; its global value is similar to the one
12522 described above but it also contains two additional quotation marks.
12523 These have differing degrees of curliness.  The
12524 @code{sentence-end-without-period} variable, when true, tells Emacs
12525 that a sentence may end without a period, such as text in Thai.)
12527 @ignore
12528 @noindent
12529 (Note that here the @key{TAB}, two spaces, and  @key{RET} are shown
12530 literally in the pattern.)
12532 This regular expression can be deciphered as follows:
12534 @table @code
12535 @item [.?!]
12536 The first part of the pattern is the three characters, a period, a question
12537 mark and an exclamation mark, within square brackets.  The pattern must
12538 begin with one or other of these characters.
12540 @item []\"')@}]*
12541 The second part of the pattern is the group of closing braces and
12542 quotation marks, which can appear zero or more times.  These may follow
12543 the period, question mark or exclamation mark.  In a regular expression,
12544 the backslash, @samp{\}, followed by the double quotation mark,
12545 @samp{"}, indicates the class of string-quote characters.  Usually, the
12546 double quotation mark is the only character in this class.  The
12547 asterisk, @samp{*}, indicates that the items in the previous group (the
12548 group surrounded by square brackets, @samp{[]}) may be repeated zero or
12549 more times.
12551 @item \\($\\|   \\|  \\)
12552 The third part of the pattern is one or other of: either the end of a
12553 line, or two blank spaces, or a tab.  The double back-slashes are used
12554 to prevent Emacs from reading the parentheses and vertical bars as part
12555 of the search pattern; the parentheses are used to mark the group and
12556 the vertical bars are used to indicated that the patterns to either side
12557 of them are alternatives.  The dollar sign is used to indicate the end
12558 of a line and both the two spaces and the tab are each inserted as is to
12559 indicate what they are.
12561 @item [@key{RET}]*
12562 Finally, the last part of the pattern indicates that the end of the line
12563 or the whitespace following the period, question mark or exclamation
12564 mark may, but need not, be followed by one or more carriage returns.  In
12565 the pattern, the carriage return is inserted as an actual carriage
12566 return between square brackets but here it is shown as @key{RET}.
12567 @end table
12568 @end ignore
12570 @node re-search-forward, forward-sentence, sentence-end, Regexp Search
12571 @comment  node-name,  next,  previous,  up
12572 @section The @code{re-search-forward} Function
12573 @findex re-search-forward
12575 The @code{re-search-forward} function is very like the
12576 @code{search-forward} function.  (@xref{search-forward, , The
12577 @code{search-forward} Function}.)
12579 @code{re-search-forward} searches for a regular expression.  If the
12580 search is successful, it leaves point immediately after the last
12581 character in the target.  If the search is backwards, it leaves point
12582 just before the first character in the target.  You may tell
12583 @code{re-search-forward} to return @code{t} for true.  (Moving point
12584 is therefore a `side effect'.)
12586 Like @code{search-forward}, the @code{re-search-forward} function takes
12587 four arguments:
12589 @enumerate
12590 @item
12591 The first argument is the regular expression that the function searches
12592 for.  The regular expression will be a string between quotations marks.
12594 @item
12595 The optional second argument limits how far the function will search; it is a
12596 bound, which is specified as a position in the buffer.
12598 @item
12599 The optional third argument specifies how the function responds to
12600 failure: @code{nil} as the third argument causes the function to
12601 signal an error (and print a message) when the search fails; any other
12602 value causes it to return @code{nil} if the search fails and @code{t}
12603 if the search succeeds.
12605 @item
12606 The optional fourth argument is the repeat count.  A negative repeat
12607 count causes @code{re-search-forward} to search backwards.
12608 @end enumerate
12610 @need 800
12611 The template for @code{re-search-forward} looks like this:
12613 @smallexample
12614 @group
12615 (re-search-forward "@var{regular-expression}"
12616                 @var{limit-of-search}
12617                 @var{what-to-do-if-search-fails}
12618                 @var{repeat-count})
12619 @end group
12620 @end smallexample
12622 The second, third, and fourth arguments are optional.  However, if you
12623 want to pass a value to either or both of the last two arguments, you
12624 must also pass a value to all the preceding arguments.  Otherwise, the
12625 Lisp interpreter will mistake which argument you are passing the value
12628 @need 1200
12629 In the @code{forward-sentence} function, the regular expression will be
12630 the value of the variable @code{sentence-end}.  In simple form, that is:
12632 @smallexample
12633 @group
12634 "[.?!][]\"')@}]*\\($\\|  \\|  \\)[
12636 @end group
12637 @end smallexample
12639 @noindent
12640 The limit of the search will be the end of the paragraph (since a
12641 sentence cannot go beyond a paragraph).  If the search fails, the
12642 function will return @code{nil}; and the repeat count will be provided
12643 by the argument to the @code{forward-sentence} function.
12645 @node forward-sentence, forward-paragraph, re-search-forward, Regexp Search
12646 @comment  node-name,  next,  previous,  up
12647 @section @code{forward-sentence}
12648 @findex forward-sentence
12650 The command to move the cursor forward a sentence is a straightforward
12651 illustration of how to use regular expression searches in Emacs Lisp.
12652 Indeed, the function looks longer and more complicated than it is; this
12653 is because the function is designed to go backwards as well as forwards;
12654 and, optionally, over more than one sentence.  The function is usually
12655 bound to the key command @kbd{M-e}.
12657 @menu
12658 * Complete forward-sentence::
12659 * fwd-sentence while loops::    Two @code{while} loops.
12660 * fwd-sentence re-search::      A regular expression search.
12661 @end menu
12663 @node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
12664 @ifnottex
12665 @unnumberedsubsec Complete @code{forward-sentence} function definition
12666 @end ifnottex
12668 @need 1250
12669 Here is the code for @code{forward-sentence}:
12671 @c in GNU Emacs 22
12672 @smallexample
12673 @group
12674 (defun forward-sentence (&optional arg)
12675   "Move forward to next `sentence-end'.  With argument, repeat.
12676 With negative argument, move backward repeatedly to `sentence-beginning'.
12678 The variable `sentence-end' is a regular expression that matches ends of
12679 sentences.  Also, every paragraph boundary terminates sentences as well."
12680 @end group
12681 @group
12682   (interactive "p")
12683   (or arg (setq arg 1))
12684   (let ((opoint (point))
12685         (sentence-end (sentence-end)))
12686     (while (< arg 0)
12687       (let ((pos (point))
12688             (par-beg (save-excursion (start-of-paragraph-text) (point))))
12689        (if (and (re-search-backward sentence-end par-beg t)
12690                 (or (< (match-end 0) pos)
12691                     (re-search-backward sentence-end par-beg t)))
12692            (goto-char (match-end 0))
12693          (goto-char par-beg)))
12694       (setq arg (1+ arg)))
12695 @end group
12696 @group
12697     (while (> arg 0)
12698       (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12699        (if (re-search-forward sentence-end par-end t)
12700            (skip-chars-backward " \t\n")
12701          (goto-char par-end)))
12702       (setq arg (1- arg)))
12703     (constrain-to-field nil opoint t)))
12704 @end group
12705 @end smallexample
12707 @ignore
12708 GNU Emacs 21
12709 @smallexample
12710 @group
12711 (defun forward-sentence (&optional arg)
12712   "Move forward to next sentence-end.  With argument, repeat.
12713 With negative argument, move backward repeatedly to sentence-beginning.
12714 Sentence ends are identified by the value of sentence-end
12715 treated as a regular expression.  Also, every paragraph boundary
12716 terminates sentences as well."
12717 @end group
12718 @group
12719   (interactive "p")
12720   (or arg (setq arg 1))
12721   (while (< arg 0)
12722     (let ((par-beg
12723            (save-excursion (start-of-paragraph-text) (point))))
12724       (if (re-search-backward
12725            (concat sentence-end "[^ \t\n]") par-beg t)
12726           (goto-char (1- (match-end 0)))
12727         (goto-char par-beg)))
12728     (setq arg (1+ arg)))
12729   (while (> arg 0)
12730     (let ((par-end
12731            (save-excursion (end-of-paragraph-text) (point))))
12732       (if (re-search-forward sentence-end par-end t)
12733           (skip-chars-backward " \t\n")
12734         (goto-char par-end)))
12735     (setq arg (1- arg))))
12736 @end group
12737 @end smallexample
12738 @end ignore
12740 The function looks long at first sight and it is best to look at its
12741 skeleton first, and then its muscle.  The way to see the skeleton is to
12742 look at the expressions that start in the left-most columns:
12744 @smallexample
12745 @group
12746 (defun forward-sentence (&optional arg)
12747   "@var{documentation}@dots{}"
12748   (interactive "p")
12749   (or arg (setq arg 1))
12750   (let ((opoint (point)) (sentence-end (sentence-end)))
12751     (while (< arg 0)
12752       (let ((pos (point))
12753             (par-beg (save-excursion (start-of-paragraph-text) (point))))
12754        @var{rest-of-body-of-while-loop-when-going-backwards}
12755     (while (> arg 0)
12756       (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
12757        @var{rest-of-body-of-while-loop-when-going-forwards}
12758     @var{handle-forms-and-equivalent}
12759 @end group
12760 @end smallexample
12762 This looks much simpler!  The function definition consists of
12763 documentation, an @code{interactive} expression, an @code{or}
12764 expression, a @code{let} expression, and @code{while} loops.
12766 Let's look at each of these parts in turn.
12768 We note that the documentation is thorough and understandable.
12770 The function has an @code{interactive "p"} declaration.  This means
12771 that the processed prefix argument, if any, is passed to the
12772 function as its argument.  (This will be a number.)  If the function
12773 is not passed an argument (it is optional) then the argument
12774 @code{arg} will be bound to 1.
12776 When @code{forward-sentence} is called non-interactively without an
12777 argument, @code{arg} is bound to @code{nil}.  The @code{or} expression
12778 handles this.  What it does is either leave the value of @code{arg} as
12779 it is, but only if @code{arg} is bound to a value; or it sets the
12780 value of @code{arg} to 1, in the case when @code{arg} is bound to
12781 @code{nil}.
12783 Next is a @code{let}.  That specifies the values of two local
12784 variables, @code{point} and @code{sentence-end}.  The local value of
12785 point, from before the search, is used in the
12786 @code{constrain-to-field} function which handles forms and
12787 equivalents.  The @code{sentence-end} variable is set by the
12788 @code{sentence-end} function.
12790 @node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
12791 @unnumberedsubsec The @code{while} loops
12793 Two @code{while} loops follow.  The first @code{while} has a
12794 true-or-false-test that tests true if the prefix argument for
12795 @code{forward-sentence} is a negative number.  This is for going
12796 backwards.  The body of this loop is similar to the body of the second
12797 @code{while} clause, but it is not exactly the same.  We will skip
12798 this @code{while} loop and concentrate on the second @code{while}
12799 loop.
12801 @need 1500
12802 The second @code{while} loop is for moving point forward.  Its skeleton
12803 looks like this:
12805 @smallexample
12806 @group
12807 (while (> arg 0)            ; @r{true-or-false-test}
12808   (let @var{varlist}
12809     (if (@var{true-or-false-test})
12810         @var{then-part}
12811       @var{else-part}
12812   (setq arg (1- arg))))     ; @code{while} @r{loop decrementer}
12813 @end group
12814 @end smallexample
12816 The @code{while} loop is of the decrementing kind.
12817 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.)  It
12818 has a true-or-false-test that tests true so long as the counter (in
12819 this case, the variable @code{arg}) is greater than zero; and it has a
12820 decrementer that subtracts 1 from the value of the counter every time
12821 the loop repeats.
12823 If no prefix argument is given to @code{forward-sentence}, which is
12824 the most common way the command is used, this @code{while} loop will
12825 run once, since the value of @code{arg} will be 1.
12827 The body of the @code{while} loop consists of a @code{let} expression,
12828 which creates and binds a local variable, and has, as its body, an
12829 @code{if} expression.
12831 @need 1250
12832 The body of the @code{while} loop looks like this:
12834 @smallexample
12835 @group
12836 (let ((par-end
12837        (save-excursion (end-of-paragraph-text) (point))))
12838   (if (re-search-forward sentence-end par-end t)
12839       (skip-chars-backward " \t\n")
12840     (goto-char par-end)))
12841 @end group
12842 @end smallexample
12844 The @code{let} expression creates and binds the local variable
12845 @code{par-end}.  As we shall see, this local variable is designed to
12846 provide a bound or limit to the regular expression search.  If the
12847 search fails to find a proper sentence ending in the paragraph, it will
12848 stop on reaching the end of the paragraph.
12850 But first, let us examine how @code{par-end} is bound to the value of
12851 the end of the paragraph.  What happens is that the @code{let} sets the
12852 value of @code{par-end} to the value returned when the Lisp interpreter
12853 evaluates the expression
12855 @smallexample
12856 @group
12857 (save-excursion (end-of-paragraph-text) (point))
12858 @end group
12859 @end smallexample
12861 @noindent
12862 In this expression, @code{(end-of-paragraph-text)} moves point to the
12863 end of the paragraph, @code{(point)} returns the value of point, and then
12864 @code{save-excursion} restores point to its original position.  Thus,
12865 the @code{let} binds @code{par-end} to the value returned by the
12866 @code{save-excursion} expression, which is the position of the end of
12867 the paragraph.  (The @code{end-of-paragraph-text} function uses
12868 @code{forward-paragraph}, which we will discuss shortly.)
12870 @need 1200
12871 Emacs next evaluates the body of the @code{let}, which is an @code{if}
12872 expression that looks like this:
12874 @smallexample
12875 @group
12876 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
12877     (skip-chars-backward " \t\n")              ; @r{then-part}
12878   (goto-char par-end)))                        ; @r{else-part}
12879 @end group
12880 @end smallexample
12882 The @code{if} tests whether its first argument is true and if so,
12883 evaluates its then-part; otherwise, the Emacs Lisp interpreter
12884 evaluates the else-part.  The true-or-false-test of the @code{if}
12885 expression is the regular expression search.
12887 It may seem odd to have what looks like the `real work' of
12888 the @code{forward-sentence} function buried here, but this is a common
12889 way this kind of operation is carried out in Lisp.
12891 @node fwd-sentence re-search,  , fwd-sentence while loops, forward-sentence
12892 @unnumberedsubsec The regular expression search
12894 The @code{re-search-forward} function searches for the end of the
12895 sentence, that is, for the pattern defined by the @code{sentence-end}
12896 regular expression.  If the pattern is found---if the end of the sentence is
12897 found---then the @code{re-search-forward} function does two things:
12899 @enumerate
12900 @item
12901 The @code{re-search-forward} function carries out a side effect, which
12902 is to move point to the end of the occurrence found.
12904 @item
12905 The @code{re-search-forward} function returns a value of true.  This is
12906 the value received by the @code{if}, and means that the search was
12907 successful.
12908 @end enumerate
12910 @noindent
12911 The side effect, the movement of point, is completed before the
12912 @code{if} function is handed the value returned by the successful
12913 conclusion of the search.
12915 When the @code{if} function receives the value of true from a successful
12916 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
12917 which is the expression @code{(skip-chars-backward " \t\n")}.  This
12918 expression moves backwards over any blank spaces, tabs or carriage
12919 returns until a printed character is found and then leaves point after
12920 the character.  Since point has already been moved to the end of the
12921 pattern that marks the end of the sentence, this action leaves point
12922 right after the closing printed character of the sentence, which is
12923 usually a period.
12925 On the other hand, if the @code{re-search-forward} function fails to
12926 find a pattern marking the end of the sentence, the function returns
12927 false.  The false then causes the @code{if} to evaluate its third
12928 argument, which is @code{(goto-char par-end)}:  it moves point to the
12929 end of the paragraph.
12931 (And if the text is in a form or equivalent, and point may not move
12932 fully, then the @code{constrain-to-field} function comes into play.)
12934 Regular expression searches are exceptionally useful and the pattern
12935 illustrated by @code{re-search-forward}, in which the search is the
12936 test of an @code{if} expression, is handy.  You will see or write code
12937 incorporating this pattern often.
12939 @node forward-paragraph, etags, forward-sentence, Regexp Search
12940 @comment  node-name,  next,  previous,  up
12941 @section @code{forward-paragraph}: a Goldmine of Functions
12942 @findex forward-paragraph
12944 @ignore
12945 @c in GNU Emacs 22
12946 (defun forward-paragraph (&optional arg)
12947   "Move forward to end of paragraph.
12948 With argument ARG, do it ARG times;
12949 a negative argument ARG = -N means move backward N paragraphs.
12951 A line which `paragraph-start' matches either separates paragraphs
12952 \(if `paragraph-separate' matches it also) or is the first line of a paragraph.
12953 A paragraph end is the beginning of a line which is not part of the paragraph
12954 to which the end of the previous line belongs, or the end of the buffer.
12955 Returns the count of paragraphs left to move."
12956   (interactive "p")
12957   (or arg (setq arg 1))
12958   (let* ((opoint (point))
12959          (fill-prefix-regexp
12960           (and fill-prefix (not (equal fill-prefix ""))
12961                (not paragraph-ignore-fill-prefix)
12962                (regexp-quote fill-prefix)))
12963          ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
12964          ;; These regexps shouldn't be anchored, because we look for them
12965          ;; starting at the left-margin.  This allows paragraph commands to
12966          ;; work normally with indented text.
12967          ;; This hack will not find problem cases like "whatever\\|^something".
12968          (parstart (if (and (not (equal "" paragraph-start))
12969                             (equal ?^ (aref paragraph-start 0)))
12970                        (substring paragraph-start 1)
12971                      paragraph-start))
12972          (parsep (if (and (not (equal "" paragraph-separate))
12973                           (equal ?^ (aref paragraph-separate 0)))
12974                      (substring paragraph-separate 1)
12975                    paragraph-separate))
12976          (parsep
12977           (if fill-prefix-regexp
12978               (concat parsep "\\|"
12979                       fill-prefix-regexp "[ \t]*$")
12980             parsep))
12981          ;; This is used for searching.
12982          (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
12983          start found-start)
12984     (while (and (< arg 0) (not (bobp)))
12985       (if (and (not (looking-at parsep))
12986                (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
12987                (looking-at parsep))
12988           (setq arg (1+ arg))
12989         (setq start (point))
12990         ;; Move back over paragraph-separating lines.
12991         (forward-char -1) (beginning-of-line)
12992         (while (and (not (bobp))
12993                     (progn (move-to-left-margin)
12994                            (looking-at parsep)))
12995           (forward-line -1))
12996         (if (bobp)
12997             nil
12998           (setq arg (1+ arg))
12999           ;; Go to end of the previous (non-separating) line.
13000           (end-of-line)
13001           ;; Search back for line that starts or separates paragraphs.
13002           (if (if fill-prefix-regexp
13003                   ;; There is a fill prefix; it overrides parstart.
13004                   (let (multiple-lines)
13005                     (while (and (progn (beginning-of-line) (not (bobp)))
13006                                 (progn (move-to-left-margin)
13007                                        (not (looking-at parsep)))
13008                                 (looking-at fill-prefix-regexp))
13009                       (unless (= (point) start)
13010                         (setq multiple-lines t))
13011                       (forward-line -1))
13012                     (move-to-left-margin)
13013                     ;; This deleted code caused a long hanging-indent line
13014                     ;; not to be filled together with the following lines.
13015                     ;; ;; Don't move back over a line before the paragraph
13016                     ;; ;; which doesn't start with fill-prefix
13017                     ;; ;; unless that is the only line we've moved over.
13018                     ;; (and (not (looking-at fill-prefix-regexp))
13019                     ;;      multiple-lines
13020                     ;;      (forward-line 1))
13021                     (not (bobp)))
13022                 (while (and (re-search-backward sp-parstart nil 1)
13023                             (setq found-start t)
13024                             ;; Found a candidate, but need to check if it is a
13025                             ;; REAL parstart.
13026                             (progn (setq start (point))
13027                                    (move-to-left-margin)
13028                                    (not (looking-at parsep)))
13029                             (not (and (looking-at parstart)
13030                                       (or (not use-hard-newlines)
13031                                           (bobp)
13032                                           (get-text-property
13033                                            (1- start) 'hard)))))
13034                   (setq found-start nil)
13035                   (goto-char start))
13036                 found-start)
13037               ;; Found one.
13038               (progn
13039                 ;; Move forward over paragraph separators.
13040                 ;; We know this cannot reach the place we started
13041                 ;; because we know we moved back over a non-separator.
13042                 (while (and (not (eobp))
13043                             (progn (move-to-left-margin)
13044                                    (looking-at parsep)))
13045                   (forward-line 1))
13046                 ;; If line before paragraph is just margin, back up to there.
13047                 (end-of-line 0)
13048                 (if (> (current-column) (current-left-margin))
13049                     (forward-char 1)
13050                   (skip-chars-backward " \t")
13051                   (if (not (bolp))
13052                       (forward-line 1))))
13053             ;; No starter or separator line => use buffer beg.
13054             (goto-char (point-min))))))
13056     (while (and (> arg 0) (not (eobp)))
13057       ;; Move forward over separator lines...
13058       (while (and (not (eobp))
13059                   (progn (move-to-left-margin) (not (eobp)))
13060                   (looking-at parsep))
13061         (forward-line 1))
13062       (unless (eobp) (setq arg (1- arg)))
13063       ;; ... and one more line.
13064       (forward-line 1)
13065       (if fill-prefix-regexp
13066           ;; There is a fill prefix; it overrides parstart.
13067           (while (and (not (eobp))
13068                       (progn (move-to-left-margin) (not (eobp)))
13069                       (not (looking-at parsep))
13070                       (looking-at fill-prefix-regexp))
13071             (forward-line 1))
13072         (while (and (re-search-forward sp-parstart nil 1)
13073                     (progn (setq start (match-beginning 0))
13074                            (goto-char start)
13075                            (not (eobp)))
13076                     (progn (move-to-left-margin)
13077                            (not (looking-at parsep)))
13078                     (or (not (looking-at parstart))
13079                         (and use-hard-newlines
13080                              (not (get-text-property (1- start) 'hard)))))
13081           (forward-char 1))
13082         (if (< (point) (point-max))
13083             (goto-char start))))
13084     (constrain-to-field nil opoint t)
13085     ;; Return the number of steps that could not be done.
13086     arg))
13087 @end ignore
13089 The @code{forward-paragraph} function moves point forward to the end
13090 of the paragraph.  It is usually bound to @kbd{M-@}} and makes use of a
13091 number of functions that are important in themselves, including
13092 @code{let*}, @code{match-beginning}, and @code{looking-at}.
13094 The function definition for @code{forward-paragraph} is considerably
13095 longer than the function definition for @code{forward-sentence}
13096 because it works with a paragraph, each line of which may begin with a
13097 fill prefix.
13099 A fill prefix consists of a string of characters that are repeated at
13100 the beginning of each line.  For example, in Lisp code, it is a
13101 convention to start each line of a paragraph-long comment with
13102 @samp{;;; }.  In Text mode, four blank spaces make up another common
13103 fill prefix, creating an indented paragraph.  (@xref{Fill Prefix, , ,
13104 emacs, The GNU Emacs Manual}, for more information about fill
13105 prefixes.)
13107 The existence of a fill prefix means that in addition to being able to
13108 find the end of a paragraph whose lines begin on the left-most
13109 column, the @code{forward-paragraph} function must be able to find the
13110 end of a paragraph when all or many of the lines in the buffer begin
13111 with the fill prefix.
13113 Moreover, it is sometimes practical to ignore a fill prefix that
13114 exists, especially when blank lines separate paragraphs.
13115 This is an added complication.
13117 @menu
13118 * forward-paragraph in brief::  Key parts of the function definition.
13119 * fwd-para let::                The @code{let*} expression.
13120 * fwd-para while::              The forward motion @code{while} loop.
13121 @end menu
13123 @node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
13124 @ifnottex
13125 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
13126 @end ifnottex
13128 Rather than print all of the @code{forward-paragraph} function, we
13129 will only print parts of it.  Read without preparation, the function
13130 can be daunting!
13132 @need 800
13133 In outline, the function looks like this:
13135 @smallexample
13136 @group
13137 (defun forward-paragraph (&optional arg)
13138   "@var{documentation}@dots{}"
13139   (interactive "p")
13140   (or arg (setq arg 1))
13141   (let*
13142       @var{varlist}
13143     (while (and (< arg 0) (not (bobp)))     ; @r{backward-moving-code}
13144       @dots{}
13145     (while (and (> arg 0) (not (eobp)))     ; @r{forward-moving-code}
13146       @dots{}
13147 @end group
13148 @end smallexample
13150 The first parts of the function are routine: the function's argument
13151 list consists of one optional argument.  Documentation follows.
13153 The lower case @samp{p} in the @code{interactive} declaration means
13154 that the processed prefix argument, if any, is passed to the function.
13155 This will be a number, and is the repeat count of how many paragraphs
13156 point will move.  The @code{or} expression in the next line handles
13157 the common case when no argument is passed to the function, which occurs
13158 if the function is called from other code rather than interactively.
13159 This case was described earlier.  (@xref{forward-sentence, The
13160 @code{forward-sentence} function}.)  Now we reach the end of the
13161 familiar part of this function.
13163 @node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph
13164 @unnumberedsubsec The @code{let*} expression
13166 The next line of the @code{forward-paragraph} function begins a
13167 @code{let*} expression.  This is a different than @code{let}.  The
13168 symbol is @code{let*} not @code{let}.
13170 The @code{let*} special form is like @code{let} except that Emacs sets
13171 each variable in sequence, one after another, and variables in the
13172 latter part of the varlist can make use of the values to which Emacs
13173 set variables in the earlier part of the varlist.
13175 @ignore
13176 ( refappend save-excursion, , code save-excursion in code append-to-buffer .)
13177 @end ignore
13179 (@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
13181 In the @code{let*} expression in this function, Emacs binds a total of
13182 seven variables:  @code{opoint}, @code{fill-prefix-regexp},
13183 @code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
13184 @code{found-start}.
13186 The variable @code{parsep} appears twice, first, to remove instances
13187 of @samp{^}, and second, to handle fill prefixes.
13189 The variable @code{opoint} is just the value of @code{point}.  As you
13190 can guess, it is used in a @code{constrain-to-field} expression, just
13191 as in @code{forward-sentence}.
13193 The variable @code{fill-prefix-regexp} is set to the value returned by
13194 evaluating the following list:
13196 @smallexample
13197 @group
13198 (and fill-prefix
13199      (not (equal fill-prefix ""))
13200      (not paragraph-ignore-fill-prefix)
13201      (regexp-quote fill-prefix))
13202 @end group
13203 @end smallexample
13205 @noindent
13206 This is an expression whose first element is the @code{and} special form.
13208 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
13209 function}), the @code{and} special form evaluates each of its
13210 arguments until one of the arguments returns a value of @code{nil}, in
13211 which case the @code{and} expression returns @code{nil}; however, if
13212 none of the arguments returns a value of @code{nil}, the value
13213 resulting from evaluating the last argument is returned.  (Since such
13214 a value is not @code{nil}, it is considered true in Lisp.)  In other
13215 words, an @code{and} expression returns a true value only if all its
13216 arguments are true.
13217 @findex and
13219 In this case, the variable @code{fill-prefix-regexp} is bound to a
13220 non-@code{nil} value only if the following four expressions produce a
13221 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
13222 @code{fill-prefix-regexp} is bound to @code{nil}.
13224 @table @code
13225 @item fill-prefix
13226 When this variable is evaluated, the value of the fill prefix, if any,
13227 is returned.  If there is no fill prefix, this variable returns
13228 @code{nil}.
13230 @item (not (equal fill-prefix "")
13231 This expression checks whether an existing fill prefix is an empty
13232 string, that is, a string with no characters in it.  An empty string is
13233 not a useful fill prefix.
13235 @item (not paragraph-ignore-fill-prefix)
13236 This expression returns @code{nil} if the variable
13237 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
13238 true value such as @code{t}.
13240 @item (regexp-quote fill-prefix)
13241 This is the last argument to the @code{and} special form.  If all the
13242 arguments to the @code{and} are true, the value resulting from
13243 evaluating this expression will be returned by the @code{and} expression
13244 and bound to the variable @code{fill-prefix-regexp},
13245 @end table
13247 @findex regexp-quote
13248 @noindent
13249 The result of evaluating this @code{and} expression successfully is that
13250 @code{fill-prefix-regexp} will be bound to the value of
13251 @code{fill-prefix} as modified by the @code{regexp-quote} function.
13252 What @code{regexp-quote} does is read a string and return a regular
13253 expression that will exactly match the string and match nothing else.
13254 This means that @code{fill-prefix-regexp} will be set to a value that
13255 will exactly match the fill prefix if the fill prefix exists.
13256 Otherwise, the variable will be set to @code{nil}.
13258 The next two local variables in the @code{let*} expression are
13259 designed to remove instances of @samp{^} from @code{parstart} and
13260 @code{parsep}, the local variables which indicate the paragraph start
13261 and the paragraph separator.  The next expression sets @code{parsep}
13262 again.  That is to handle fill prefixes.
13264 This is the setting that requires the definition call @code{let*}
13265 rather than @code{let}.  The true-or-false-test for the @code{if}
13266 depends on whether the variable @code{fill-prefix-regexp} evaluates to
13267 @code{nil} or some other value.
13269 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
13270 the else-part of the @code{if} expression and binds @code{parsep} to
13271 its local value.  (@code{parsep} is a regular expression that matches
13272 what separates paragraphs.)
13274 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
13275 the then-part of the @code{if} expression and binds @code{parsep} to a
13276 regular expression that includes the @code{fill-prefix-regexp} as part
13277 of the pattern.
13279 Specifically, @code{parsep} is set to the original value of the
13280 paragraph separate regular expression concatenated with an alternative
13281 expression that consists of the @code{fill-prefix-regexp} followed by
13282 optional whitespace to the end of the line.  The whitespace is defined
13283 by @w{@code{"[ \t]*$"}}.)  The @samp{\\|} defines this portion of the
13284 regexp as an alternative to @code{parsep}.
13286 According to a comment in the code, the next local variable,
13287 @code{sp-parstart}, is used for searching, and then the final two,
13288 @code{start} and @code{found-start}, are set to @code{nil}.
13290 Now we get into the body of the @code{let*}.  The first part of the body
13291 of the @code{let*} deals with the case when the function is given a
13292 negative argument and is therefore moving backwards.  We will skip this
13293 section.
13295 @node fwd-para while,  , fwd-para let, forward-paragraph
13296 @unnumberedsubsec The forward motion @code{while} loop
13298 The second part of the body of the @code{let*} deals with forward
13299 motion.  It is a @code{while} loop that repeats itself so long as the
13300 value of @code{arg} is greater than zero.  In the most common use of
13301 the function, the value of the argument is 1, so the body of the
13302 @code{while} loop is evaluated exactly once, and the cursor moves
13303 forward one paragraph.
13305 @ignore
13306 (while (and (> arg 0) (not (eobp)))
13308   ;; Move forward over separator lines...
13309   (while (and (not (eobp))
13310               (progn (move-to-left-margin) (not (eobp)))
13311               (looking-at parsep))
13312     (forward-line 1))
13313   (unless (eobp) (setq arg (1- arg)))
13314   ;; ... and one more line.
13315   (forward-line 1)
13317   (if fill-prefix-regexp
13318       ;; There is a fill prefix; it overrides parstart.
13319       (while (and (not (eobp))
13320                   (progn (move-to-left-margin) (not (eobp)))
13321                   (not (looking-at parsep))
13322                   (looking-at fill-prefix-regexp))
13323         (forward-line 1))
13325     (while (and (re-search-forward sp-parstart nil 1)
13326                 (progn (setq start (match-beginning 0))
13327                        (goto-char start)
13328                        (not (eobp)))
13329                 (progn (move-to-left-margin)
13330                        (not (looking-at parsep)))
13331                 (or (not (looking-at parstart))
13332                     (and use-hard-newlines
13333                          (not (get-text-property (1- start) 'hard)))))
13334       (forward-char 1))
13336     (if (< (point) (point-max))
13337         (goto-char start))))
13338 @end ignore
13340 This part handles three situations: when point is between paragraphs,
13341 when there is a fill prefix and when there is no fill prefix.
13343 @need 800
13344 The @code{while} loop looks like this:
13346 @smallexample
13347 @group
13348 ;; @r{going forwards and not at the end of the buffer}
13349 (while (and (> arg 0) (not (eobp)))
13351   ;; @r{between paragraphs}
13352   ;; Move forward over separator lines...
13353   (while (and (not (eobp))
13354               (progn (move-to-left-margin) (not (eobp)))
13355               (looking-at parsep))
13356     (forward-line 1))
13357   ;;  @r{This decrements the loop}
13358   (unless (eobp) (setq arg (1- arg)))
13359   ;; ... and one more line.
13360   (forward-line 1)
13361 @end group
13363 @group
13364   (if fill-prefix-regexp
13365       ;; There is a fill prefix; it overrides parstart;
13366       ;; we go forward line by line
13367       (while (and (not (eobp))
13368                   (progn (move-to-left-margin) (not (eobp)))
13369                   (not (looking-at parsep))
13370                   (looking-at fill-prefix-regexp))
13371         (forward-line 1))
13372 @end group
13374 @group
13375     ;; There is no fill prefix;
13376     ;; we go forward character by character
13377     (while (and (re-search-forward sp-parstart nil 1)
13378                 (progn (setq start (match-beginning 0))
13379                        (goto-char start)
13380                        (not (eobp)))
13381                 (progn (move-to-left-margin)
13382                        (not (looking-at parsep)))
13383                 (or (not (looking-at parstart))
13384                     (and use-hard-newlines
13385                          (not (get-text-property (1- start) 'hard)))))
13386       (forward-char 1))
13387 @end group
13389 @group
13390     ;; and if there is no fill prefix and if we are not at the end,
13391     ;;     go to whatever was found in the regular expression search
13392     ;;     for sp-parstart
13393     (if (< (point) (point-max))
13394         (goto-char start))))
13395 @end group
13396 @end smallexample
13398 @findex eobp
13399 We can see that this is a decrementing counter @code{while} loop,
13400 using the expression @code{(setq arg (1- arg))} as the decrementer.
13401 That expression is not far from the @code{while}, but is hidden in
13402 another Lisp macro, an @code{unless} macro.  Unless we are at the end
13403 of the buffer --- that is what the @code{eobp} function determines; it
13404 is an abbreviation of @samp{End Of Buffer P} --- we decrease the value
13405 of @code{arg} by one.
13407 (If we are at the end of the buffer, we cannot go forward any more and
13408 the next loop of the @code{while} expression will test false since the
13409 test is an @code{and} with @code{(not (eobp))}.  The @code{not}
13410 function means exactly as you expect; it is another name for
13411 @code{null}, a function that returns true when its argument is false.)
13413 Interestingly, the loop count is not decremented until we leave the
13414 space between paragraphs, unless we come to the end of buffer or stop
13415 seeing the local value of the paragraph separator.
13417 That second @code{while} also has a @code{(move-to-left-margin)}
13418 expression.  The function is self-explanatory.  It is inside a
13419 @code{progn} expression and not the last element of its body, so it is
13420 only invoked for its side effect, which is to move point to the left
13421 margin of the current line.
13423 @findex looking-at
13424 The @code{looking-at} function is also self-explanatory; it returns
13425 true if the text after point matches the regular expression given as
13426 its argument.
13428 The rest of the body of the loop looks difficult at first, but makes
13429 sense as you come to understand it.
13431 @need 800
13432 First consider what happens if there is a fill prefix:
13434 @smallexample
13435 @group
13436   (if fill-prefix-regexp
13437       ;; There is a fill prefix; it overrides parstart;
13438       ;; we go forward line by line
13439       (while (and (not (eobp))
13440                   (progn (move-to-left-margin) (not (eobp)))
13441                   (not (looking-at parsep))
13442                   (looking-at fill-prefix-regexp))
13443         (forward-line 1))
13444 @end group
13445 @end smallexample
13447 @noindent
13448 This expression moves point forward line by line so long
13449 as four conditions are true:
13451 @enumerate
13452 @item
13453 Point is not at the end of the buffer.
13455 @item
13456 We can move to the left margin of the text and are
13457 not at the end of the buffer.
13459 @item
13460 The text following point does not separate paragraphs.
13462 @item
13463 The pattern following point is the fill prefix regular expression.
13464 @end enumerate
13466 The last condition may be puzzling, until you remember that point was
13467 moved to the beginning of the line early in the @code{forward-paragraph}
13468 function.  This means that if the text has a fill prefix, the
13469 @code{looking-at} function will see it.
13471 @need 1250
13472 Consider what happens when there is no fill prefix.
13474 @smallexample
13475 @group
13476     (while (and (re-search-forward sp-parstart nil 1)
13477                 (progn (setq start (match-beginning 0))
13478                        (goto-char start)
13479                        (not (eobp)))
13480                 (progn (move-to-left-margin)
13481                        (not (looking-at parsep)))
13482                 (or (not (looking-at parstart))
13483                     (and use-hard-newlines
13484                          (not (get-text-property (1- start) 'hard)))))
13485       (forward-char 1))
13486 @end group
13487 @end smallexample
13489 @noindent
13490 This @code{while} loop has us searching forward for
13491 @code{sp-parstart}, which is the combination of possible whitespace
13492 with a the local value of the start of a paragraph or of a paragraph
13493 separator.  (The latter two are within an expression starting
13494 @code{\(?:} so that they are not referenced by the
13495 @code{match-beginning} function.)
13497 @need 800
13498 The two expressions,
13500 @smallexample
13501 @group
13502 (setq start (match-beginning 0))
13503 (goto-char start)
13504 @end group
13505 @end smallexample
13507 @noindent
13508 mean go to the start of the text matched by the regular expression
13509 search.
13511 The @code{(match-beginning 0)} expression is new.  It returns a number
13512 specifying the location of the start of the text that was matched by
13513 the last search.
13515 The @code{match-beginning} function is used here because of a
13516 characteristic of a forward search: a successful forward search,
13517 regardless of whether it is a plain search or a regular expression
13518 search, moves point to the end of the text that is found.  In this
13519 case, a successful search moves point to the end of the pattern for
13520 @code{sp-parstart}.
13522 However, we want to put point at the end of the current paragraph, not
13523 somewhere else.  Indeed, since the search possibly includes the
13524 paragraph separator, point may end up at the beginning of the next one
13525 unless we use an expression that includes @code{match-beginning}.
13527 @findex match-beginning
13528 When given an argument of 0, @code{match-beginning} returns the
13529 position that is the start of the text matched by the most recent
13530 search.  In this case, the most recent search looks for
13531 @code{sp-parstart}.  The @code{(match-beginning 0)} expression returns
13532 the beginning position of that pattern, rather than the end position
13533 of that pattern.
13535 (Incidentally, when passed a positive number as an argument, the
13536 @code{match-beginning} function returns the location of point at that
13537 parenthesized expression in the last search unless that parenthesized
13538 expression begins with @code{\(?:}.  I don't know why @code{\(?:}
13539 appears here since the argument is 0.)
13541 @need 1250
13542 The last expression when there is no fill prefix is
13544 @smallexample
13545 @group
13546 (if (< (point) (point-max))
13547     (goto-char start))))
13548 @end group
13549 @end smallexample
13551 @noindent
13552 This says that if there is no fill prefix and if we are not at the
13553 end, point should move to the beginning of whatever was found by the
13554 regular expression search for @code{sp-parstart}.
13556 The full definition for the @code{forward-paragraph} function not only
13557 includes code for going forwards, but also code for going backwards.
13559 If you are reading this inside of GNU Emacs and you want to see the
13560 whole function, you can type @kbd{C-h f} (@code{describe-function})
13561 and the name of the function.  This gives you the function
13562 documentation and the name of the library containing the function's
13563 source.  Place point over the name of the library and press the RET
13564 key; you will be taken directly to the source.  (Be sure to install
13565 your sources!  Without them, you are like a person who tries to drive
13566 a car with his eyes shut!)
13568 @node etags, Regexp Review, forward-paragraph, Regexp Search
13569 @section Create Your Own @file{TAGS} File
13570 @findex etags
13571 @cindex @file{TAGS} file, create own
13573 Besides @kbd{C-h f} (@code{describe-function}), another way to see the
13574 source of a function is to type @kbd{M-.} (@code{find-tag}) and the
13575 name of the function when prompted for it.  This is a good habit to
13576 get into.  The @kbd{M-.} (@code{find-tag}) command takes you directly
13577 to the source for a function, variable, or node.  The function depends
13578 on tags tables to tell it where to go.
13580 If the @code{find-tag} function first asks you for the name of a
13581 @file{TAGS} table, give it the name of a @file{TAGS} file such as
13582 @file{/usr/local/src/emacs/src/TAGS}.  (The exact path to your
13583 @file{TAGS} file depends on how your copy of Emacs was installed.  I
13584 just told you the location that provides both my C and my Emacs Lisp
13585 sources.)
13587 You can also create your own @file{TAGS} file for directories that
13588 lack one.
13590 You often need to build and install tags tables yourself.  They are
13591 not built automatically.  A tags table is called a @file{TAGS} file;
13592 the name is in upper case letters.
13594 You can create a @file{TAGS} file by calling the @code{etags} program
13595 that comes as a part of the Emacs distribution.  Usually, @code{etags}
13596 is compiled and installed when Emacs is built.  (@code{etags} is not
13597 an Emacs Lisp function or a part of Emacs; it is a C program.)
13599 @need 1250
13600 To create a @file{TAGS} file, first switch to the directory in which
13601 you want to create the file.  In Emacs you can do this with the
13602 @kbd{M-x cd} command, or by visiting a file in the directory, or by
13603 listing the directory with @kbd{C-x d} (@code{dired}).  Then run the
13604 compile command, with @w{@code{etags *.el}} as the command to execute
13606 @smallexample
13607 M-x compile RET etags *.el RET
13608 @end smallexample
13610 @noindent
13611 to create a @file{TAGS} file for Emacs Lisp.
13613 For example, if you have a large number of files in your
13614 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
13615 of which I load 12---you can create a @file{TAGS} file for the Emacs
13616 Lisp files in that directory.
13618 @need 1250
13619 The @code{etags} program takes all the usual shell `wildcards'.  For
13620 example, if you have two directories for which you want a single
13621 @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where
13622 @file{../elisp/} is the second directory:
13624 @smallexample
13625 M-x compile RET etags *.el ../elisp/*.el RET
13626 @end smallexample
13628 @need 1250
13629 Type
13631 @smallexample
13632 M-x compile RET etags --help RET
13633 @end smallexample
13635 @noindent
13636 to see a list of the options accepted by @code{etags} as well as a
13637 list of supported languages.
13639 The @code{etags} program handles more than 20 languages, including
13640 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java,
13641 LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and
13642 most assemblers.  The program has no switches for specifying the
13643 language; it recognizes the language in an input file according to its
13644 file name and contents.
13646 @file{etags} is very helpful when you are writing code yourself and
13647 want to refer back to functions you have already written.  Just run
13648 @code{etags} again at intervals as you write new functions, so they
13649 become part of the @file{TAGS} file.
13651 If you think an appropriate @file{TAGS} file already exists for what
13652 you want, but do not know where it is, you can use the @code{locate}
13653 program to attempt to find it.
13655 Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
13656 for you the full path names of all your @file{TAGS} files.  On my
13657 system, this command lists 34 @file{TAGS} files.  On the other hand, a
13658 `plain vanilla' system I recently installed did not contain any
13659 @file{TAGS} files.
13661 If the tags table you want has been created, you can use the @code{M-x
13662 visit-tags-table} command to specify it.  Otherwise, you will need to
13663 create the tag table yourself and then use @code{M-x
13664 visit-tags-table}.
13666 @subsubheading Building Tags in the Emacs sources
13667 @cindex Building Tags in the Emacs sources
13668 @cindex Tags in the Emacs sources
13669 @findex make tags
13671 The GNU Emacs sources come with a @file{Makefile} that contains a
13672 sophisticated @code{etags} command that creates, collects, and merges
13673 tags tables from all over the Emacs sources and puts the information
13674 into one @file{TAGS} file in the @file{src/} directory. (The
13675 @file{src/} directory is below the top level of your Emacs directory.)
13677 @need 1250
13678 To build this @file{TAGS} file, go to the top level of your Emacs
13679 source directory and run the compile command @code{make tags}:
13681 @smallexample
13682 M-x compile RET make tags RET
13683 @end smallexample
13685 @noindent
13686 (The @code{make tags} command works well with the GNU Emacs sources,
13687 as well as with some other source packages.)
13689 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
13690 Manual}.
13692 @node Regexp Review, re-search Exercises, etags, Regexp Search
13693 @comment  node-name,  next,  previous,  up
13694 @section Review
13696 Here is a brief summary of some recently introduced functions.
13698 @table @code
13699 @item while
13700 Repeatedly evaluate the body of the expression so long as the first
13701 element of the body tests true.  Then return @code{nil}.  (The
13702 expression is evaluated only for its side effects.)
13704 @need 1250
13705 For example:
13707 @smallexample
13708 @group
13709 (let ((foo 2))
13710   (while (> foo 0)
13711     (insert (format "foo is %d.\n" foo))
13712     (setq foo (1- foo))))
13714      @result{}      foo is 2.
13715              foo is 1.
13716              nil
13717 @end group
13718 @end smallexample
13720 @noindent
13721 (The @code{insert} function inserts its arguments at point; the
13722 @code{format} function returns a string formatted from its arguments
13723 the way @code{message} formats its arguments; @code{\n} produces a new
13724 line.)
13726 @item re-search-forward
13727 Search for a pattern, and if the pattern is found, move point to rest
13728 just after it.
13730 @noindent
13731 Takes four arguments, like @code{search-forward}:
13733 @enumerate
13734 @item
13735 A regular expression that specifies the pattern to search for.
13736 (Remember to put quotation marks around this argument!)
13738 @item
13739 Optionally, the limit of the search.
13741 @item
13742 Optionally, what to do if the search fails, return @code{nil} or an
13743 error message.
13745 @item
13746 Optionally, how many times to repeat the search; if negative, the
13747 search goes backwards.
13748 @end enumerate
13750 @item let*
13751 Bind some variables locally to particular values,
13752 and then evaluate the remaining arguments, returning the value of the
13753 last one.  While binding the local variables, use the local values of
13754 variables bound earlier, if any.
13756 @need 1250
13757 For example:
13759 @smallexample
13760 @group
13761 (let* ((foo 7)
13762       (bar (* 3 foo)))
13763   (message "`bar' is %d." bar))
13764      @result{} `bar' is 21.
13765 @end group
13766 @end smallexample
13768 @item match-beginning
13769 Return the position of the start of the text found by the last regular
13770 expression search.
13772 @item looking-at
13773 Return @code{t} for true if the text after point matches the argument,
13774 which should be a regular expression.
13776 @item eobp
13777 Return @code{t} for true if point is at the end of the accessible part
13778 of a buffer.  The end of the accessible part is the end of the buffer
13779 if the buffer is not narrowed; it is the end of the narrowed part if
13780 the buffer is narrowed.
13781 @end table
13783 @need 1500
13784 @node re-search Exercises,  , Regexp Review, Regexp Search
13785 @section Exercises with @code{re-search-forward}
13787 @itemize @bullet
13788 @item
13789 Write a function to search for a regular expression that matches two
13790 or more blank lines in sequence.
13792 @item
13793 Write a function to search for duplicated words, such as `the the'.
13794 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
13795 Manual}, for information on how to write a regexp (a regular
13796 expression) to match a string that is composed of two identical
13797 halves.  You can devise several regexps; some are better than others.
13798 The function I use is described in an appendix, along with several
13799 regexps.  @xref{the-the, , @code{the-the} Duplicated Words Function}.
13800 @end itemize
13802 @node Counting Words, Words in a defun, Regexp Search, Top
13803 @chapter Counting: Repetition and Regexps
13804 @cindex Repetition for word counting
13805 @cindex Regular expressions for word counting
13807 Repetition and regular expression searches are powerful tools that you
13808 often use when you write code in Emacs Lisp.  This chapter illustrates
13809 the use of regular expression searches through the construction of
13810 word count commands using @code{while} loops and recursion.
13812 @menu
13813 * Why Count Words::
13814 * count-words-region::          Use a regexp, but find a problem.
13815 * recursive-count-words::       Start with case of no words in region.
13816 * Counting Exercise::
13817 @end menu
13819 @node Why Count Words, count-words-region, Counting Words, Counting Words
13820 @ifnottex
13821 @unnumberedsec Counting words
13822 @end ifnottex
13824 The standard Emacs distribution contains a function for counting the
13825 number of lines within a region.  However, there is no corresponding
13826 function for counting words.
13828 Certain types of writing ask you to count words.  Thus, if you write
13829 an essay, you may be limited to 800 words; if you write a novel, you
13830 may discipline yourself to write 1000 words a day.  It seems odd to me
13831 that Emacs lacks a word count command.  Perhaps people use Emacs
13832 mostly for code or types of documentation that do not require word
13833 counts; or perhaps they restrict themselves to the operating system
13834 word count command, @code{wc}.  Alternatively, people may follow
13835 the publishers' convention and compute a word count by dividing the
13836 number of characters in a document by five.  In any event, here are
13837 commands to count words.
13839 @node count-words-region, recursive-count-words, Why Count Words, Counting Words
13840 @comment  node-name,  next,  previous,  up
13841 @section The @code{count-words-region} Function
13842 @findex count-words-region
13844 A word count command could count words in a line, paragraph, region,
13845 or buffer.  What should the command cover?  You could design the
13846 command to count the number of words in a complete buffer.  However,
13847 the Emacs tradition encourages flexibility---you may want to count
13848 words in just a section, rather than all of a buffer.  So it makes
13849 more sense to design the command to count the number of words in a
13850 region.  Once you have a @code{count-words-region} command, you can,
13851 if you wish, count words in a whole buffer by marking it with
13852 @w{@kbd{C-x h}} (@code{mark-whole-buffer}).
13854 Clearly, counting words is a repetitive act: starting from the
13855 beginning of the region, you count the first word, then the second
13856 word, then the third word, and so on, until you reach the end of the
13857 region.  This means that word counting is ideally suited to recursion
13858 or to a @code{while} loop.
13860 @menu
13861 * Design count-words-region::   The definition using a @code{while} loop.
13862 * Whitespace Bug::              The Whitespace Bug in @code{count-words-region}.
13863 @end menu
13865 @node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
13866 @ifnottex
13867 @unnumberedsubsec Designing @code{count-words-region}
13868 @end ifnottex
13870 First, we will implement the word count command with a @code{while}
13871 loop, then with recursion.  The command will, of course, be
13872 interactive.
13874 @need 800
13875 The template for an interactive function definition is, as always:
13877 @smallexample
13878 @group
13879 (defun @var{name-of-function} (@var{argument-list})
13880   "@var{documentation}@dots{}"
13881   (@var{interactive-expression}@dots{})
13882   @var{body}@dots{})
13883 @end group
13884 @end smallexample
13886 What we need to do is fill in the slots.
13888 The name of the function should be self-explanatory and similar to the
13889 existing @code{count-lines-region} name.  This makes the name easier
13890 to remember.  @code{count-words-region} is a good choice.
13892 The function counts words within a region.  This means that the
13893 argument list must contain symbols that are bound to the two
13894 positions, the beginning and end of the region.  These two positions
13895 can be called @samp{beginning} and @samp{end} respectively.  The first
13896 line of the documentation should be a single sentence, since that is
13897 all that is printed as documentation by a command such as
13898 @code{apropos}.  The interactive expression will be of the form
13899 @samp{(interactive "r")}, since that will cause Emacs to pass the
13900 beginning and end of the region to the function's argument list.  All
13901 this is routine.
13903 The body of the function needs to be written to do three tasks:
13904 first, to set up conditions under which the @code{while} loop can
13905 count words, second, to run the @code{while} loop, and third, to send
13906 a message to the user.
13908 When a user calls @code{count-words-region}, point may be at the
13909 beginning or the end of the region.  However, the counting process
13910 must start at the beginning of the region.  This means we will want
13911 to put point there if it is not already there.  Executing
13912 @code{(goto-char beginning)} ensures this.  Of course, we will want to
13913 return point to its expected position when the function finishes its
13914 work.  For this reason, the body must be enclosed in a
13915 @code{save-excursion} expression.
13917 The central part of the body of the function consists of a
13918 @code{while} loop in which one expression jumps point forward word by
13919 word, and another expression counts those jumps.  The true-or-false-test
13920 of the @code{while} loop should test true so long as point should jump
13921 forward, and false when point is at the end of the region.
13923 We could use @code{(forward-word 1)} as the expression for moving point
13924 forward word by word, but it is easier to see what Emacs identifies as a
13925 `word' if we use a regular expression search.
13927 A regular expression search that finds the pattern for which it is
13928 searching leaves point after the last character matched.  This means
13929 that a succession of successful word searches will move point forward
13930 word by word.
13932 As a practical matter, we want the regular expression search to jump
13933 over whitespace and punctuation between words as well as over the
13934 words themselves.  A regexp that refuses to jump over interword
13935 whitespace would never jump more than one word!  This means that
13936 the regexp should include the whitespace and punctuation that follows
13937 a word, if any, as well as the word itself.  (A word may end a buffer
13938 and not have any following whitespace or punctuation, so that part of
13939 the regexp must be optional.)
13941 Thus, what we want for the regexp is a pattern defining one or more
13942 word constituent characters followed, optionally, by one or more
13943 characters that are not word constituents.  The regular expression for
13944 this is:
13946 @smallexample
13947 \w+\W*
13948 @end smallexample
13950 @noindent
13951 The buffer's syntax table determines which characters are and are not
13952 word constituents.  (@xref{Syntax, , What Constitutes a Word or
13953 Symbol?}, for more about syntax.  Also, see @ref{Syntax, Syntax, The
13954 Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, ,
13955 Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
13957 @need 800
13958 The search expression looks like this:
13960 @smallexample
13961 (re-search-forward "\\w+\\W*")
13962 @end smallexample
13964 @noindent
13965 (Note that paired backslashes precede the @samp{w} and @samp{W}.  A
13966 single backslash has special meaning to the Emacs Lisp interpreter.
13967 It indicates that the following character is interpreted differently
13968 than usual.  For example, the two characters, @samp{\n}, stand for
13969 @samp{newline}, rather than for a backslash followed by @samp{n}.  Two
13970 backslashes in a row stand for an ordinary, `unspecial' backslash, so
13971 Emacs Lisp interpreter ends of seeing a single backslash followed by a
13972 letter.  So it discovers the letter is special.)
13974 We need a counter to count how many words there are; this variable
13975 must first be set to 0 and then incremented each time Emacs goes
13976 around the @code{while} loop.  The incrementing expression is simply:
13978 @smallexample
13979 (setq count (1+ count))
13980 @end smallexample
13982 Finally, we want to tell the user how many words there are in the
13983 region.  The @code{message} function is intended for presenting this
13984 kind of information to the user.  The message has to be phrased so
13985 that it reads properly regardless of how many words there are in the
13986 region: we don't want to say that ``there are 1 words in the region''.
13987 The conflict between singular and plural is ungrammatical.  We can
13988 solve this problem by using a conditional expression that evaluates
13989 different messages depending on the number of words in the region.
13990 There are three possibilities: no words in the region, one word in the
13991 region, and more than one word.  This means that the @code{cond}
13992 special form is appropriate.
13994 @need 1500
13995 All this leads to the following function definition:
13997 @smallexample
13998 @group
13999 ;;; @r{First version; has bugs!}
14000 (defun count-words-region (beginning end)
14001   "Print number of words in the region.
14002 Words are defined as at least one word-constituent
14003 character followed by at least one character that
14004 is not a word-constituent.  The buffer's syntax
14005 table determines which characters these are."
14006   (interactive "r")
14007   (message "Counting words in region ... ")
14008 @end group
14010 @group
14011 ;;; @r{1. Set up appropriate conditions.}
14012   (save-excursion
14013     (goto-char beginning)
14014     (let ((count 0))
14015 @end group
14017 @group
14018 ;;; @r{2. Run the} while @r{loop.}
14019       (while (< (point) end)
14020         (re-search-forward "\\w+\\W*")
14021         (setq count (1+ count)))
14022 @end group
14024 @group
14025 ;;; @r{3. Send a message to the user.}
14026       (cond ((zerop count)
14027              (message
14028               "The region does NOT have any words."))
14029             ((= 1 count)
14030              (message
14031               "The region has 1 word."))
14032             (t
14033              (message
14034               "The region has %d words." count))))))
14035 @end group
14036 @end smallexample
14038 @noindent
14039 As written, the function works, but not in all circumstances.
14041 @node Whitespace Bug,  , Design count-words-region, count-words-region
14042 @comment  node-name,  next,  previous,  up
14043 @subsection The Whitespace Bug in @code{count-words-region}
14045 The @code{count-words-region} command described in the preceding
14046 section has two bugs, or rather, one bug with two manifestations.
14047 First, if you mark a region containing only whitespace in the middle
14048 of some text, the @code{count-words-region} command tells you that the
14049 region contains one word!  Second, if you mark a region containing
14050 only whitespace at the end of the buffer or the accessible portion of
14051 a narrowed buffer, the command displays an error message that looks
14052 like this:
14054 @smallexample
14055 Search failed: "\\w+\\W*"
14056 @end smallexample
14058 If you are reading this in Info in GNU Emacs, you can test for these
14059 bugs yourself.
14061 First, evaluate the function in the usual manner to install it.
14062 @ifinfo
14063 Here is a copy of the definition.  Place your cursor after the closing
14064 parenthesis and type @kbd{C-x C-e} to install it.
14066 @smallexample
14067 @group
14068 ;; @r{First version; has bugs!}
14069 (defun count-words-region (beginning end)
14070   "Print number of words in the region.
14071 Words are defined as at least one word-constituent character followed
14072 by at least one character that is not a word-constituent.  The buffer's
14073 syntax table determines which characters these are."
14074 @end group
14075 @group
14076   (interactive "r")
14077   (message "Counting words in region ... ")
14078 @end group
14080 @group
14081 ;;; @r{1. Set up appropriate conditions.}
14082   (save-excursion
14083     (goto-char beginning)
14084     (let ((count 0))
14085 @end group
14087 @group
14088 ;;; @r{2. Run the} while @r{loop.}
14089       (while (< (point) end)
14090         (re-search-forward "\\w+\\W*")
14091         (setq count (1+ count)))
14092 @end group
14094 @group
14095 ;;; @r{3. Send a message to the user.}
14096       (cond ((zerop count)
14097              (message "The region does NOT have any words."))
14098             ((= 1 count) (message "The region has 1 word."))
14099             (t (message "The region has %d words." count))))))
14100 @end group
14101 @end smallexample
14102 @end ifinfo
14104 @need 1000
14105 If you wish, you can also install this keybinding by evaluating it:
14107 @smallexample
14108 (global-set-key "\C-c=" 'count-words-region)
14109 @end smallexample
14111 To conduct the first test, set mark and point to the beginning and end
14112 of the following line and then type @kbd{C-c =} (or @kbd{M-x
14113 count-words-region} if you have not bound @kbd{C-c =}):
14115 @smallexample
14116     one   two  three
14117 @end smallexample
14119 @noindent
14120 Emacs will tell you, correctly, that the region has three words.
14122 Repeat the test, but place mark at the beginning of the line and place
14123 point just @emph{before} the word @samp{one}.  Again type the command
14124 @kbd{C-c =} (or @kbd{M-x count-words-region}).  Emacs should tell you
14125 that the region has no words, since it is composed only of the
14126 whitespace at the beginning of the line.  But instead Emacs tells you
14127 that the region has one word!
14129 For the third test, copy the sample line to the end of the
14130 @file{*scratch*} buffer and then type several spaces at the end of the
14131 line.  Place mark right after the word @samp{three} and point at the
14132 end of line.  (The end of the line will be the end of the buffer.)
14133 Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before.
14134 Again, Emacs should tell you that the region has no words, since it is
14135 composed only of the whitespace at the end of the line.  Instead,
14136 Emacs displays an error message saying @samp{Search failed}.
14138 The two bugs stem from the same problem.
14140 Consider the first manifestation of the bug, in which the command
14141 tells you that the whitespace at the beginning of the line contains
14142 one word.  What happens is this: The @code{M-x count-words-region}
14143 command moves point to the beginning of the region.  The @code{while}
14144 tests whether the value of point is smaller than the value of
14145 @code{end}, which it is.  Consequently, the regular expression search
14146 looks for and finds the first word.  It leaves point after the word.
14147 @code{count} is set to one.  The @code{while} loop repeats; but this
14148 time the value of point is larger than the value of @code{end}, the
14149 loop is exited; and the function displays a message saying the number
14150 of words in the region is one.  In brief, the regular expression
14151 search looks for and finds the word even though it is outside
14152 the marked region.
14154 In the second manifestation of the bug, the region is whitespace at
14155 the end of the buffer.  Emacs says @samp{Search failed}.  What happens
14156 is that the true-or-false-test in the @code{while} loop tests true, so
14157 the search expression is executed.  But since there are no more words
14158 in the buffer, the search fails.
14160 In both manifestations of the bug, the search extends or attempts to
14161 extend outside of the region.
14163 The solution is to limit the search to the region---this is a fairly
14164 simple action, but as you may have come to expect, it is not quite as
14165 simple as you might think.
14167 As we have seen, the @code{re-search-forward} function takes a search
14168 pattern as its first argument.  But in addition to this first,
14169 mandatory argument, it accepts three optional arguments.  The optional
14170 second argument bounds the search.  The optional third argument, if
14171 @code{t}, causes the function to return @code{nil} rather than signal
14172 an error if the search fails.  The optional fourth argument is a
14173 repeat count.  (In Emacs, you can see a function's documentation by
14174 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
14176 In the @code{count-words-region} definition, the value of the end of
14177 the region is held by the variable @code{end} which is passed as an
14178 argument to the function.  Thus, we can add @code{end} as an argument
14179 to the regular expression search expression:
14181 @smallexample
14182 (re-search-forward "\\w+\\W*" end)
14183 @end smallexample
14185 However, if you make only this change to the @code{count-words-region}
14186 definition and then test the new version of the definition on a
14187 stretch of whitespace, you will receive an error message saying
14188 @samp{Search failed}.
14190 What happens is this: the search is limited to the region, and fails
14191 as you expect because there are no word-constituent characters in the
14192 region.  Since it fails, we receive an error message.  But we do not
14193 want to receive an error message in this case; we want to receive the
14194 message that "The region does NOT have any words."
14196 The solution to this problem is to provide @code{re-search-forward}
14197 with a third argument of @code{t}, which causes the function to return
14198 @code{nil} rather than signal an error if the search fails.
14200 However, if you make this change and try it, you will see the message
14201 ``Counting words in region ... '' and @dots{} you will keep on seeing
14202 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
14204 Here is what happens: the search is limited to the region, as before,
14205 and it fails because there are no word-constituent characters in the
14206 region, as expected.  Consequently, the @code{re-search-forward}
14207 expression returns @code{nil}.  It does nothing else.  In particular,
14208 it does not move point, which it does as a side effect if it finds the
14209 search target.  After the @code{re-search-forward} expression returns
14210 @code{nil}, the next expression in the @code{while} loop is evaluated.
14211 This expression increments the count.  Then the loop repeats.  The
14212 true-or-false-test tests true because the value of point is still less
14213 than the value of end, since the @code{re-search-forward} expression
14214 did not move point. @dots{} and the cycle repeats @dots{}
14216 The @code{count-words-region} definition requires yet another
14217 modification, to cause the true-or-false-test of the @code{while} loop
14218 to test false if the search fails.  Put another way, there are two
14219 conditions that must be satisfied in the true-or-false-test before the
14220 word count variable is incremented: point must still be within the
14221 region and the search expression must have found a word to count.
14223 Since both the first condition and the second condition must be true
14224 together, the two expressions, the region test and the search
14225 expression, can be joined with an @code{and} special form and embedded in
14226 the @code{while} loop as the true-or-false-test, like this:
14228 @smallexample
14229 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
14230 @end smallexample
14232 @c colon in printed section title causes problem in Info cross reference
14233 @c also trouble with an overfull hbox
14234 @iftex
14235 @noindent
14236 (For information about @code{and}, see
14237 @ref{kill-new function, , The @code{kill-new} function}.)
14238 @end iftex
14239 @ifinfo
14240 @noindent
14241 (@xref{kill-new function, , The @code{kill-new} function}, for
14242 information about @code{and}.)
14243 @end ifinfo
14245 The @code{re-search-forward} expression returns @code{t} if the search
14246 succeeds and as a side effect moves point.  Consequently, as words are
14247 found, point is moved through the region.  When the search expression
14248 fails to find another word, or when point reaches the end of the
14249 region, the true-or-false-test tests false, the @code{while} loop
14250 exits, and the @code{count-words-region} function displays one or
14251 other of its messages.
14253 After incorporating these final changes, the @code{count-words-region}
14254 works without bugs (or at least, without bugs that I have found!).
14255 Here is what it looks like:
14257 @smallexample
14258 @group
14259 ;;; @r{Final version:} @code{while}
14260 (defun count-words-region (beginning end)
14261   "Print number of words in the region."
14262   (interactive "r")
14263   (message "Counting words in region ... ")
14264 @end group
14266 @group
14267 ;;; @r{1. Set up appropriate conditions.}
14268   (save-excursion
14269     (let ((count 0))
14270       (goto-char beginning)
14271 @end group
14273 @group
14274 ;;; @r{2. Run the} while @r{loop.}
14275       (while (and (< (point) end)
14276                   (re-search-forward "\\w+\\W*" end t))
14277         (setq count (1+ count)))
14278 @end group
14280 @group
14281 ;;; @r{3. Send a message to the user.}
14282       (cond ((zerop count)
14283              (message
14284               "The region does NOT have any words."))
14285             ((= 1 count)
14286              (message
14287               "The region has 1 word."))
14288             (t
14289              (message
14290               "The region has %d words." count))))))
14291 @end group
14292 @end smallexample
14294 @node recursive-count-words, Counting Exercise, count-words-region, Counting Words
14295 @comment  node-name,  next,  previous,  up
14296 @section Count Words Recursively
14297 @cindex Count words recursively
14298 @cindex Recursively counting words
14299 @cindex Words, counted recursively
14301 You can write the function for counting words recursively as well as
14302 with a @code{while} loop.  Let's see how this is done.
14304 First, we need to recognize that the @code{count-words-region}
14305 function has three jobs: it sets up the appropriate conditions for
14306 counting to occur; it counts the words in the region; and it sends a
14307 message to the user telling how many words there are.
14309 If we write a single recursive function to do everything, we will
14310 receive a message for every recursive call.  If the region contains 13
14311 words, we will receive thirteen messages, one right after the other.
14312 We don't want this!  Instead, we must write two functions to do the
14313 job, one of which (the recursive function) will be used inside of the
14314 other.  One function will set up the conditions and display the
14315 message; the other will return the word count.
14317 Let us start with the function that causes the message to be displayed.
14318 We can continue to call this @code{count-words-region}.
14320 This is the function that the user will call.  It will be interactive.
14321 Indeed, it will be similar to our previous versions of this
14322 function, except that it will call @code{recursive-count-words} to
14323 determine how many words are in the region.
14325 @need 1250
14326 We can readily construct a template for this function, based on our
14327 previous versions:
14329 @smallexample
14330 @group
14331 ;; @r{Recursive version; uses regular expression search}
14332 (defun count-words-region (beginning end)
14333   "@var{documentation}@dots{}"
14334   (@var{interactive-expression}@dots{})
14335 @end group
14336 @group
14338 ;;; @r{1. Set up appropriate conditions.}
14339   (@var{explanatory message})
14340   (@var{set-up functions}@dots{}
14341 @end group
14342 @group
14344 ;;; @r{2. Count the words.}
14345     @var{recursive call}
14346 @end group
14347 @group
14349 ;;; @r{3. Send a message to the user.}
14350     @var{message providing word count}))
14351 @end group
14352 @end smallexample
14354 The definition looks straightforward, except that somehow the count
14355 returned by the recursive call must be passed to the message
14356 displaying the word count.  A little thought suggests that this can be
14357 done by making use of a @code{let} expression: we can bind a variable
14358 in the varlist of a @code{let} expression to the number of words in
14359 the region, as returned by the recursive call; and then the
14360 @code{cond} expression, using binding, can display the value to the
14361 user.
14363 Often, one thinks of the binding within a @code{let} expression as
14364 somehow secondary to the `primary' work of a function.  But in this
14365 case, what you might consider the `primary' job of the function,
14366 counting words, is done within the @code{let} expression.
14368 @need 1250
14369 Using @code{let}, the function definition looks like this:
14371 @smallexample
14372 @group
14373 (defun count-words-region (beginning end)
14374   "Print number of words in the region."
14375   (interactive "r")
14376 @end group
14378 @group
14379 ;;; @r{1. Set up appropriate conditions.}
14380   (message "Counting words in region ... ")
14381   (save-excursion
14382     (goto-char beginning)
14383 @end group
14385 @group
14386 ;;; @r{2. Count the words.}
14387     (let ((count (recursive-count-words end)))
14388 @end group
14390 @group
14391 ;;; @r{3. Send a message to the user.}
14392       (cond ((zerop count)
14393              (message
14394               "The region does NOT have any words."))
14395             ((= 1 count)
14396              (message
14397               "The region has 1 word."))
14398             (t
14399              (message
14400               "The region has %d words." count))))))
14401 @end group
14402 @end smallexample
14404 Next, we need to write the recursive counting function.
14406 A recursive function has at least three parts: the `do-again-test', the
14407 `next-step-expression', and the recursive call.
14409 The do-again-test determines whether the function will or will not be
14410 called again.  Since we are counting words in a region and can use a
14411 function that moves point forward for every word, the do-again-test
14412 can check whether point is still within the region.  The do-again-test
14413 should find the value of point and determine whether point is before,
14414 at, or after the value of the end of the region.  We can use the
14415 @code{point} function to locate point.  Clearly, we must pass the
14416 value of the end of the region to the recursive counting function as an
14417 argument.
14419 In addition, the do-again-test should also test whether the search finds a
14420 word.  If it does not, the function should not call itself again.
14422 The next-step-expression changes a value so that when the recursive
14423 function is supposed to stop calling itself, it stops.  More
14424 precisely, the next-step-expression changes a value so that at the
14425 right time, the do-again-test stops the recursive function from
14426 calling itself again.  In this case, the next-step-expression can be
14427 the expression that moves point forward, word by word.
14429 The third part of a recursive function is the recursive call.
14431 Somewhere, also, we also need a part that does the `work' of the
14432 function, a part that does the counting.  A vital part!
14434 @need 1250
14435 But already, we have an outline of the recursive counting function:
14437 @smallexample
14438 @group
14439 (defun recursive-count-words (region-end)
14440   "@var{documentation}@dots{}"
14441    @var{do-again-test}
14442    @var{next-step-expression}
14443    @var{recursive call})
14444 @end group
14445 @end smallexample
14447 Now we need to fill in the slots.  Let's start with the simplest cases
14448 first:  if point is at or beyond the end of the region, there cannot
14449 be any words in the region, so the function should return zero.
14450 Likewise, if the search fails, there are no words to count, so the
14451 function should return zero.
14453 On the other hand, if point is within the region and the search
14454 succeeds, the function should call itself again.
14456 @need 800
14457 Thus, the do-again-test should look like this:
14459 @smallexample
14460 @group
14461 (and (< (point) region-end)
14462      (re-search-forward "\\w+\\W*" region-end t))
14463 @end group
14464 @end smallexample
14466 Note that the search expression is part of the do-again-test---the
14467 function returns @code{t} if its search succeeds and @code{nil} if it
14468 fails.  (@xref{Whitespace Bug, , The Whitespace Bug in
14469 @code{count-words-region}}, for an explanation of how
14470 @code{re-search-forward} works.)
14472 The do-again-test is the true-or-false test of an @code{if} clause.
14473 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
14474 clause should call the function again; but if it fails, the else-part
14475 should return zero since either point is outside the region or the
14476 search failed because there were no words to find.
14478 But before considering the recursive call, we need to consider the
14479 next-step-expression.  What is it?  Interestingly, it is the search
14480 part of the do-again-test.
14482 In addition to returning @code{t} or @code{nil} for the
14483 do-again-test, @code{re-search-forward} moves point forward as a side
14484 effect of a successful search.  This is the action that changes the
14485 value of point so that the recursive function stops calling itself
14486 when point completes its movement through the region.  Consequently,
14487 the @code{re-search-forward} expression is the next-step-expression.
14489 @need 1200
14490 In outline, then, the body of the @code{recursive-count-words}
14491 function looks like this:
14493 @smallexample
14494 @group
14495 (if @var{do-again-test-and-next-step-combined}
14496     ;; @r{then}
14497     @var{recursive-call-returning-count}
14498   ;; @r{else}
14499   @var{return-zero})
14500 @end group
14501 @end smallexample
14503 How to incorporate the mechanism that counts?
14505 If you are not used to writing recursive functions, a question like
14506 this can be troublesome.  But it can and should be approached
14507 systematically.
14509 We know that the counting mechanism should be associated in some way
14510 with the recursive call.  Indeed, since the next-step-expression moves
14511 point forward by one word, and since a recursive call is made for
14512 each word, the counting mechanism must be an expression that adds one
14513 to the value returned by a call to @code{recursive-count-words}.
14515 @need 800
14516 Consider several cases:
14518 @itemize @bullet
14519 @item
14520 If there are two words in the region, the function should return
14521 a value resulting from adding one to the value returned when it counts
14522 the first word, plus the number returned when it counts the remaining
14523 words in the region, which in this case is one.
14525 @item
14526 If there is one word in the region, the function should return
14527 a value resulting from adding one to the value returned when it counts
14528 that word, plus the number returned when it counts the remaining
14529 words in the region, which in this case is zero.
14531 @item
14532 If there are no words in the region, the function should return zero.
14533 @end itemize
14535 From the sketch we can see that the else-part of the @code{if} returns
14536 zero for the case of no words.  This means that the then-part of the
14537 @code{if} must return a value resulting from adding one to the value
14538 returned from a count of the remaining words.
14540 @need 1200
14541 The expression will look like this, where @code{1+} is a function that
14542 adds one to its argument.
14544 @smallexample
14545 (1+ (recursive-count-words region-end))
14546 @end smallexample
14548 @need 1200
14549 The whole @code{recursive-count-words} function will then look like
14550 this:
14552 @smallexample
14553 @group
14554 (defun recursive-count-words (region-end)
14555   "@var{documentation}@dots{}"
14557 ;;; @r{1. do-again-test}
14558   (if (and (< (point) region-end)
14559            (re-search-forward "\\w+\\W*" region-end t))
14560 @end group
14562 @group
14563 ;;; @r{2. then-part: the recursive call}
14564       (1+ (recursive-count-words region-end))
14566 ;;; @r{3. else-part}
14567     0))
14568 @end group
14569 @end smallexample
14571 @need 1250
14572 Let's examine how this works:
14574 If there are no words in the region, the else part of the @code{if}
14575 expression is evaluated and consequently the function returns zero.
14577 If there is one word in the region, the value of point is less than
14578 the value of @code{region-end} and the search succeeds.  In this case,
14579 the true-or-false-test of the @code{if} expression tests true, and the
14580 then-part of the @code{if} expression is evaluated.  The counting
14581 expression is evaluated.  This expression returns a value (which will
14582 be the value returned by the whole function) that is the sum of one
14583 added to the value returned by a recursive call.
14585 Meanwhile, the next-step-expression has caused point to jump over the
14586 first (and in this case only) word in the region.  This means that
14587 when @code{(recursive-count-words region-end)} is evaluated a second
14588 time, as a result of the recursive call, the value of point will be
14589 equal to or greater than the value of region end.  So this time,
14590 @code{recursive-count-words} will return zero.  The zero will be added
14591 to one, and the original evaluation of @code{recursive-count-words}
14592 will return one plus zero, which is one, which is the correct amount.
14594 Clearly, if there are two words in the region, the first call to
14595 @code{recursive-count-words} returns one added to the value returned
14596 by calling @code{recursive-count-words} on a region containing the
14597 remaining word---that is, it adds one to one, producing two, which is
14598 the correct amount.
14600 Similarly, if there are three words in the region, the first call to
14601 @code{recursive-count-words} returns one added to the value returned
14602 by calling @code{recursive-count-words} on a region containing the
14603 remaining two words---and so on and so on.
14605 @need 1250
14606 @noindent
14607 With full documentation the two functions look like this:
14609 @need 1250
14610 @noindent
14611 The recursive function:
14613 @findex recursive-count-words
14614 @smallexample
14615 @group
14616 (defun recursive-count-words (region-end)
14617   "Number of words between point and REGION-END."
14618 @end group
14620 @group
14621 ;;; @r{1. do-again-test}
14622   (if (and (< (point) region-end)
14623            (re-search-forward "\\w+\\W*" region-end t))
14624 @end group
14626 @group
14627 ;;; @r{2. then-part: the recursive call}
14628       (1+ (recursive-count-words region-end))
14630 ;;; @r{3. else-part}
14631     0))
14632 @end group
14633 @end smallexample
14635 @need 800
14636 @noindent
14637 The wrapper:
14639 @smallexample
14640 @group
14641 ;;; @r{Recursive version}
14642 (defun count-words-region (beginning end)
14643   "Print number of words in the region.
14644 @end group
14646 @group
14647 Words are defined as at least one word-constituent
14648 character followed by at least one character that is
14649 not a word-constituent.  The buffer's syntax table
14650 determines which characters these are."
14651 @end group
14652 @group
14653   (interactive "r")
14654   (message "Counting words in region ... ")
14655   (save-excursion
14656     (goto-char beginning)
14657     (let ((count (recursive-count-words end)))
14658 @end group
14659 @group
14660       (cond ((zerop count)
14661              (message
14662               "The region does NOT have any words."))
14663 @end group
14664 @group
14665             ((= 1 count)
14666              (message "The region has 1 word."))
14667             (t
14668              (message
14669               "The region has %d words." count))))))
14670 @end group
14671 @end smallexample
14673 @node Counting Exercise,  , recursive-count-words, Counting Words
14674 @section Exercise: Counting Punctuation
14676 Using a @code{while} loop, write a function to count the number of
14677 punctuation marks in a region---period, comma, semicolon, colon,
14678 exclamation mark, and question mark.  Do the same using recursion.
14680 @node Words in a defun, Readying a Graph, Counting Words, Top
14681 @chapter Counting Words in a @code{defun}
14682 @cindex Counting words in a @code{defun}
14683 @cindex Word counting in a @code{defun}
14685 Our next project is to count the number of words in a function
14686 definition.  Clearly, this can be done using some variant of
14687 @code{count-word-region}.  @xref{Counting Words, , Counting Words:
14688 Repetition and Regexps}.  If we are just going to count the words in
14689 one definition, it is easy enough to mark the definition with the
14690 @kbd{C-M-h} (@code{mark-defun}) command, and then call
14691 @code{count-word-region}.
14693 However, I am more ambitious: I want to count the words and symbols in
14694 every definition in the Emacs sources and then print a graph that
14695 shows how many functions there are of each length: how many contain 40
14696 to 49 words or symbols, how many contain 50 to 59 words or symbols,
14697 and so on.  I have often been curious how long a typical function is,
14698 and this will tell.
14700 @menu
14701 * Divide and Conquer::
14702 * Words and Symbols::           What to count?
14703 * Syntax::                      What constitutes a word or symbol?
14704 * count-words-in-defun::        Very like @code{count-words}.
14705 * Several defuns::              Counting several defuns in a file.
14706 * Find a File::                 Do you want to look at a file?
14707 * lengths-list-file::           A list of the lengths of many definitions.
14708 * Several files::               Counting in definitions in different files.
14709 * Several files recursively::   Recursively counting in different files.
14710 * Prepare the data::            Prepare the data for display in a graph.
14711 @end menu
14713 @node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
14714 @ifnottex
14715 @unnumberedsec Divide and Conquer
14716 @end ifnottex
14718 Described in one phrase, the histogram project is daunting; but
14719 divided into numerous small steps, each of which we can take one at a
14720 time, the project becomes less fearsome.  Let us consider what the
14721 steps must be:
14723 @itemize @bullet
14724 @item
14725 First, write a function to count the words in one definition.  This
14726 includes the problem of handling symbols as well as words.
14728 @item
14729 Second, write a function to list the numbers of words in each function
14730 in a file.  This function can use the @code{count-words-in-defun}
14731 function.
14733 @item
14734 Third, write a function to list the numbers of words in each function
14735 in each of several files.  This entails automatically finding the
14736 various files, switching to them, and counting the words in the
14737 definitions within them.
14739 @item
14740 Fourth, write a function to convert the list of numbers that we
14741 created in step three to a form that will be suitable for printing as
14742 a graph.
14744 @item
14745 Fifth, write a function to print the results as a graph.
14746 @end itemize
14748 This is quite a project!  But if we take each step slowly, it will not
14749 be difficult.
14751 @node Words and Symbols, Syntax, Divide and Conquer, Words in a defun
14752 @section What to Count?
14753 @cindex Words and symbols in defun
14755 When we first start thinking about how to count the words in a
14756 function definition, the first question is (or ought to be) what are
14757 we going to count?  When we speak of `words' with respect to a Lisp
14758 function definition, we are actually speaking, in large part, of
14759 `symbols'.  For example, the following @code{multiply-by-seven}
14760 function contains the five symbols @code{defun},
14761 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}.  In
14762 addition, in the documentation string, it contains the four words
14763 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}.  The
14764 symbol @samp{number} is repeated, so the definition contains a total
14765 of ten words and symbols.
14767 @smallexample
14768 @group
14769 (defun multiply-by-seven (number)
14770   "Multiply NUMBER by seven."
14771   (* 7 number))
14772 @end group
14773 @end smallexample
14775 @noindent
14776 However, if we mark the @code{multiply-by-seven} definition with
14777 @kbd{C-M-h} (@code{mark-defun}), and then call
14778 @code{count-words-region} on it, we will find that
14779 @code{count-words-region} claims the definition has eleven words, not
14780 ten!  Something is wrong!
14782 The problem is twofold: @code{count-words-region} does not count the
14783 @samp{*} as a word, and it counts the single symbol,
14784 @code{multiply-by-seven}, as containing three words.  The hyphens are
14785 treated as if they were interword spaces rather than intraword
14786 connectors: @samp{multiply-by-seven} is counted as if it were written
14787 @samp{multiply by seven}.
14789 The cause of this confusion is the regular expression search within
14790 the @code{count-words-region} definition that moves point forward word
14791 by word.  In the canonical version of @code{count-words-region}, the
14792 regexp is:
14794 @smallexample
14795 "\\w+\\W*"
14796 @end smallexample
14798 @noindent
14799 This regular expression is a pattern defining one or more word
14800 constituent characters possibly followed by one or more characters
14801 that are not word constituents.  What is meant by `word constituent
14802 characters' brings us to the issue of syntax, which is worth a section
14803 of its own.
14805 @node Syntax, count-words-in-defun, Words and Symbols, Words in a defun
14806 @section What Constitutes a Word or Symbol?
14807 @cindex Syntax categories and tables
14809 Emacs treats different characters as belonging to different
14810 @dfn{syntax categories}.  For example, the regular expression,
14811 @samp{\\w+}, is a pattern specifying one or more @emph{word
14812 constituent} characters.  Word constituent characters are members of
14813 one syntax category.  Other syntax categories include the class of
14814 punctuation characters, such as the period and the comma, and the
14815 class of whitespace characters, such as the blank space and the tab
14816 character.  (For more information, see @ref{Syntax, Syntax, The Syntax
14817 Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax
14818 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
14820 Syntax tables specify which characters belong to which categories.
14821 Usually, a hyphen is not specified as a `word constituent character'.
14822 Instead, it is specified as being in the `class of characters that are
14823 part of symbol names but not words.'  This means that the
14824 @code{count-words-region} function treats it in the same way it treats
14825 an interword white space, which is why @code{count-words-region}
14826 counts @samp{multiply-by-seven} as three words.
14828 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
14829 one symbol: modify the syntax table or modify the regular expression.
14831 We could redefine a hyphen as a word constituent character by
14832 modifying the syntax table that Emacs keeps for each mode.  This
14833 action would serve our purpose, except that a hyphen is merely the
14834 most common character within symbols that is not typically a word
14835 constituent character; there are others, too.
14837 Alternatively, we can redefine the regular expression used in the
14838 @code{count-words} definition so as to include symbols.  This
14839 procedure has the merit of clarity, but the task is a little tricky.
14841 @need 1200
14842 The first part is simple enough: the pattern must match ``at least one
14843 character that is a word or symbol constituent''.  Thus:
14845 @smallexample
14846 "\\(\\w\\|\\s_\\)+"
14847 @end smallexample
14849 @noindent
14850 The @samp{\\(} is the first part of the grouping construct that
14851 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
14852 by the @samp{\\|}.  The @samp{\\w} matches any word-constituent
14853 character and the @samp{\\s_} matches any character that is part of a
14854 symbol name but not a word-constituent character.  The @samp{+}
14855 following the group indicates that the word or symbol constituent
14856 characters must be matched at least once.
14858 However, the second part of the regexp is more difficult to design.
14859 What we want is to follow the first part with ``optionally one or more
14860 characters that are not constituents of a word or symbol''.  At first,
14861 I thought I could define this with the following:
14863 @smallexample
14864 "\\(\\W\\|\\S_\\)*"
14865 @end smallexample
14867 @noindent
14868 The upper case @samp{W} and @samp{S} match characters that are
14869 @emph{not} word or symbol constituents.  Unfortunately, this
14870 expression matches any character that is either not a word constituent
14871 or not a symbol constituent.  This matches any character!
14873 I then noticed that every word or symbol in my test region was
14874 followed by white space (blank space, tab, or newline).  So I tried
14875 placing a pattern to match one or more blank spaces after the pattern
14876 for one or more word or symbol constituents.  This failed, too.  Words
14877 and symbols are often separated by whitespace, but in actual code
14878 parentheses may follow symbols and punctuation may follow words.  So
14879 finally, I designed a pattern in which the word or symbol constituents
14880 are followed optionally by characters that are not white space and
14881 then followed optionally by white space.
14883 @need 800
14884 Here is the full regular expression:
14886 @smallexample
14887 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14888 @end smallexample
14890 @node count-words-in-defun, Several defuns, Syntax, Words in a defun
14891 @section The @code{count-words-in-defun} Function
14892 @cindex Counting words in a @code{defun}
14894 We have seen that there are several ways to write a
14895 @code{count-word-region} function.  To write a
14896 @code{count-words-in-defun}, we need merely adapt one of these
14897 versions.
14899 The version that uses a @code{while} loop is easy to understand, so I
14900 am going to adapt that.  Because @code{count-words-in-defun} will be
14901 part of a more complex program, it need not be interactive and it need
14902 not display a message but just return the count.  These considerations
14903 simplify the definition a little.
14905 On the other hand, @code{count-words-in-defun} will be used within a
14906 buffer that contains function definitions.  Consequently, it is
14907 reasonable to ask that the function determine whether it is called
14908 when point is within a function definition, and if it is, to return
14909 the count for that definition.  This adds complexity to the
14910 definition, but saves us from needing to pass arguments to the
14911 function.
14913 @need 1250
14914 These considerations lead us to prepare the following template:
14916 @smallexample
14917 @group
14918 (defun count-words-in-defun ()
14919   "@var{documentation}@dots{}"
14920   (@var{set up}@dots{}
14921      (@var{while loop}@dots{})
14922    @var{return count})
14923 @end group
14924 @end smallexample
14926 @noindent
14927 As usual, our job is to fill in the slots.
14929 First, the set up.
14931 We are presuming that this function will be called within a buffer
14932 containing function definitions.  Point will either be within a
14933 function definition or not.  For @code{count-words-in-defun} to work,
14934 point must move to the beginning of the definition, a counter must
14935 start at zero, and the counting loop must stop when point reaches the
14936 end of the definition.
14938 The @code{beginning-of-defun} function searches backwards for an
14939 opening delimiter such as a @samp{(} at the beginning of a line, and
14940 moves point to that position, or else to the limit of the search.  In
14941 practice, this means that @code{beginning-of-defun} moves point to the
14942 beginning of an enclosing or preceding function definition, or else to
14943 the beginning of the buffer.  We can use @code{beginning-of-defun} to
14944 place point where we wish to start.
14946 The @code{while} loop requires a counter to keep track of the words or
14947 symbols being counted.  A @code{let} expression can be used to create
14948 a local variable for this purpose, and bind it to an initial value of zero.
14950 The @code{end-of-defun} function works like @code{beginning-of-defun}
14951 except that it moves point to the end of the definition.
14952 @code{end-of-defun} can be used as part of an expression that
14953 determines the position of the end of the definition.
14955 The set up for @code{count-words-in-defun} takes shape rapidly: first
14956 we move point to the beginning of the definition, then we create a
14957 local variable to hold the count, and finally, we record the position
14958 of the end of the definition so the @code{while} loop will know when to stop
14959 looping.
14961 @need 1250
14962 The code looks like this:
14964 @smallexample
14965 @group
14966 (beginning-of-defun)
14967 (let ((count 0)
14968       (end (save-excursion (end-of-defun) (point))))
14969 @end group
14970 @end smallexample
14972 @noindent
14973 The code is simple.  The only slight complication is likely to concern
14974 @code{end}: it is bound to the position of the end of the definition
14975 by a @code{save-excursion} expression that returns the value of point
14976 after @code{end-of-defun} temporarily moves it to the end of the
14977 definition.
14979 The second part of the @code{count-words-in-defun}, after the set up,
14980 is the @code{while} loop.
14982 The loop must contain an expression that jumps point forward word by
14983 word and symbol by symbol, and another expression that counts the
14984 jumps.  The true-or-false-test for the @code{while} loop should test
14985 true so long as point should jump forward, and false when point is at
14986 the end of the definition.  We have already redefined the regular
14987 expression for this (@pxref{Syntax}), so the loop is straightforward:
14989 @smallexample
14990 @group
14991 (while (and (< (point) end)
14992             (re-search-forward
14993              "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
14994   (setq count (1+ count)))
14995 @end group
14996 @end smallexample
14998 The third part of the function definition returns the count of words
14999 and symbols.  This part is the last expression within the body of the
15000 @code{let} expression, and can be, very simply, the local variable
15001 @code{count}, which when evaluated returns the count.
15003 @need 1250
15004 Put together, the @code{count-words-in-defun} definition looks like this:
15006 @findex count-words-in-defun
15007 @smallexample
15008 @group
15009 (defun count-words-in-defun ()
15010   "Return the number of words and symbols in a defun."
15011   (beginning-of-defun)
15012   (let ((count 0)
15013         (end (save-excursion (end-of-defun) (point))))
15014 @end group
15015 @group
15016     (while
15017         (and (< (point) end)
15018              (re-search-forward
15019               "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
15020               end t))
15021       (setq count (1+ count)))
15022     count))
15023 @end group
15024 @end smallexample
15026 How to test this?  The function is not interactive, but it is easy to
15027 put a wrapper around the function to make it interactive; we can use
15028 almost the same code as for the recursive version of
15029 @code{count-words-region}:
15031 @smallexample
15032 @group
15033 ;;; @r{Interactive version.}
15034 (defun count-words-defun ()
15035   "Number of words and symbols in a function definition."
15036   (interactive)
15037   (message
15038    "Counting words and symbols in function definition ... ")
15039 @end group
15040 @group
15041   (let ((count (count-words-in-defun)))
15042     (cond
15043      ((zerop count)
15044       (message
15045        "The definition does NOT have any words or symbols."))
15046 @end group
15047 @group
15048      ((= 1 count)
15049       (message
15050        "The definition has 1 word or symbol."))
15051      (t
15052       (message
15053        "The definition has %d words or symbols." count)))))
15054 @end group
15055 @end smallexample
15057 @need 800
15058 @noindent
15059 Let's re-use @kbd{C-c =} as a convenient keybinding:
15061 @smallexample
15062 (global-set-key "\C-c=" 'count-words-defun)
15063 @end smallexample
15065 Now we can try out @code{count-words-defun}: install both
15066 @code{count-words-in-defun} and @code{count-words-defun}, and set the
15067 keybinding, and then place the cursor within the following definition:
15069 @smallexample
15070 @group
15071 (defun multiply-by-seven (number)
15072   "Multiply NUMBER by seven."
15073   (* 7 number))
15074      @result{} 10
15075 @end group
15076 @end smallexample
15078 @noindent
15079 Success!  The definition has 10 words and symbols.
15081 The next problem is to count the numbers of words and symbols in
15082 several definitions within a single file.
15084 @node Several defuns, Find a File, count-words-in-defun, Words in a defun
15085 @section Count Several @code{defuns} Within a File
15087 A file such as @file{simple.el} may have a hundred or more function
15088 definitions within it.  Our long term goal is to collect statistics on
15089 many files, but as a first step, our immediate goal is to collect
15090 statistics on one file.
15092 The information will be a series of numbers, each number being the
15093 length of a function definition.  We can store the numbers in a list.
15095 We know that we will want to incorporate the information regarding one
15096 file with information about many other files; this means that the
15097 function for counting definition lengths within one file need only
15098 return the list of lengths.  It need not and should not display any
15099 messages.
15101 The word count commands contain one expression to jump point forward
15102 word by word and another expression to count the jumps.  The function
15103 to return the lengths of definitions can be designed to work the same
15104 way, with one expression to jump point forward definition by
15105 definition and another expression to construct the lengths' list.
15107 This statement of the problem makes it elementary to write the
15108 function definition.  Clearly, we will start the count at the
15109 beginning of the file, so the first command will be @code{(goto-char
15110 (point-min))}.  Next, we start the @code{while} loop; and the
15111 true-or-false test of the loop can be a regular expression search for
15112 the next function definition---so long as the search succeeds, point
15113 is moved forward and then the body of the loop is evaluated.  The body
15114 needs an expression that constructs the lengths' list.  @code{cons},
15115 the list construction command, can be used to create the list.  That
15116 is almost all there is to it.
15118 @need 800
15119 Here is what this fragment of code looks like:
15121 @smallexample
15122 @group
15123 (goto-char (point-min))
15124 (while (re-search-forward "^(defun" nil t)
15125   (setq lengths-list
15126         (cons (count-words-in-defun) lengths-list)))
15127 @end group
15128 @end smallexample
15130 What we have left out is the mechanism for finding the file that
15131 contains the function definitions.
15133 In previous examples, we either used this, the Info file, or we
15134 switched back and forth to some other buffer, such as the
15135 @file{*scratch*} buffer.
15137 Finding a file is a new process that we have not yet discussed.
15139 @node Find a File, lengths-list-file, Several defuns, Words in a defun
15140 @comment  node-name,  next,  previous,  up
15141 @section Find a File
15142 @cindex Find a File
15144 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
15145 command.  This command is almost, but not quite right for the lengths
15146 problem.
15148 @need 1200
15149 Let's look at the source for @code{find-file}:
15151 @smallexample
15152 @group
15153 (defun find-file (filename)
15154   "Edit file FILENAME.
15155 Switch to a buffer visiting file FILENAME,
15156 creating one if none already exists."
15157   (interactive "FFind file: ")
15158   (switch-to-buffer (find-file-noselect filename)))
15159 @end group
15160 @end smallexample
15162 @noindent
15163 (The most recent version of the @code{find-file} function definition
15164 permits you to specify optional wildcards to visit multiple files; that
15165 makes the definition more complex and we will not discuss it here,
15166 since it is not relevant.  You can see its source using either
15167 @kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
15169 @ignore
15170 In Emacs 22
15171 (defun find-file (filename &optional wildcards)
15172   "Edit file FILENAME.
15173 Switch to a buffer visiting file FILENAME,
15174 creating one if none already exists.
15175 Interactively, the default if you just type RET is the current directory,
15176 but the visited file name is available through the minibuffer history:
15177 type M-n to pull it into the minibuffer.
15179 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
15180 expand wildcards (if any) and visit multiple files.  You can
15181 suppress wildcard expansion by setting `find-file-wildcards' to nil.
15183 To visit a file without any kind of conversion and without
15184 automatically choosing a major mode, use \\[find-file-literally]."
15185   (interactive (find-file-read-args "Find file: " nil))
15186   (let ((value (find-file-noselect filename nil nil wildcards)))
15187     (if (listp value)
15188         (mapcar 'switch-to-buffer (nreverse value))
15189       (switch-to-buffer value))))
15190 @end ignore
15192 The definition I am showing possesses short but complete documentation
15193 and an interactive specification that prompts you for a file name when
15194 you use the command interactively.  The body of the definition
15195 contains two functions, @code{find-file-noselect} and
15196 @code{switch-to-buffer}.
15198 According to its documentation as shown by @kbd{C-h f} (the
15199 @code{describe-function} command), the @code{find-file-noselect}
15200 function reads the named file into a buffer and returns the buffer.
15201 (Its most recent version includes an optional wildcards argument,
15202 too, as well as another to read a file literally and an other you
15203 suppress warning messages.  These optional arguments are irrelevant.)
15205 However, the @code{find-file-noselect} function does not select the
15206 buffer in which it puts the file.  Emacs does not switch its attention
15207 (or yours if you are using @code{find-file-noselect}) to the selected
15208 buffer.  That is what @code{switch-to-buffer} does: it switches the
15209 buffer to which Emacs attention is directed; and it switches the
15210 buffer displayed in the window to the new buffer.  We have discussed
15211 buffer switching elsewhere.  (@xref{Switching Buffers}.)
15213 In this histogram project, we do not need to display each file on the
15214 screen as the program determines the length of each definition within
15215 it.  Instead of employing @code{switch-to-buffer}, we can work with
15216 @code{set-buffer}, which redirects the attention of the computer
15217 program to a different buffer but does not redisplay it on the screen.
15218 So instead of calling on @code{find-file} to do the job, we must write
15219 our own expression.
15221 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
15223 @node lengths-list-file, Several files, Find a File, Words in a defun
15224 @section @code{lengths-list-file} in Detail
15226 The core of the @code{lengths-list-file} function is a @code{while}
15227 loop containing a function to move point forward `defun by defun' and
15228 a function to count the number of words and symbols in each defun.
15229 This core must be surrounded by functions that do various other tasks,
15230 including finding the file, and ensuring that point starts out at the
15231 beginning of the file.  The function definition looks like this:
15232 @findex lengths-list-file
15234 @smallexample
15235 @group
15236 (defun lengths-list-file (filename)
15237   "Return list of definitions' lengths within FILE.
15238 The returned list is a list of numbers.
15239 Each number is the number of words or
15240 symbols in one function definition."
15241 @end group
15242 @group
15243   (message "Working on `%s' ... " filename)
15244   (save-excursion
15245     (let ((buffer (find-file-noselect filename))
15246           (lengths-list))
15247       (set-buffer buffer)
15248       (setq buffer-read-only t)
15249       (widen)
15250       (goto-char (point-min))
15251       (while (re-search-forward "^(defun" nil t)
15252         (setq lengths-list
15253               (cons (count-words-in-defun) lengths-list)))
15254       (kill-buffer buffer)
15255       lengths-list)))
15256 @end group
15257 @end smallexample
15259 @noindent
15260 The function is passed one argument, the name of the file on which it
15261 will work.  It has four lines of documentation, but no interactive
15262 specification.  Since people worry that a computer is broken if they
15263 don't see anything going on, the first line of the body is a
15264 message.
15266 The next line contains a @code{save-excursion} that returns Emacs'
15267 attention to the current buffer when the function completes.  This is
15268 useful in case you embed this function in another function that
15269 presumes point is restored to the original buffer.
15271 In the varlist of the @code{let} expression, Emacs finds the file and
15272 binds the local variable @code{buffer} to the buffer containing the
15273 file.  At the same time, Emacs creates @code{lengths-list} as a local
15274 variable.
15276 Next, Emacs switches its attention to the buffer.
15278 In the following line, Emacs makes the buffer read-only.  Ideally,
15279 this line is not necessary.  None of the functions for counting words
15280 and symbols in a function definition should change the buffer.
15281 Besides, the buffer is not going to be saved, even if it were changed.
15282 This line is entirely the consequence of great, perhaps excessive,
15283 caution.  The reason for the caution is that this function and those
15284 it calls work on the sources for Emacs and it is inconvenient if they
15285 are inadvertently modified.  It goes without saying that I did not
15286 realize a need for this line until an experiment went awry and started
15287 to modify my Emacs source files @dots{}
15289 Next comes a call to widen the buffer if it is narrowed.  This
15290 function is usually not needed---Emacs creates a fresh buffer if none
15291 already exists; but if a buffer visiting the file already exists Emacs
15292 returns that one.  In this case, the buffer may be narrowed and must
15293 be widened.  If we wanted to be fully `user-friendly', we would
15294 arrange to save the restriction and the location of point, but we
15295 won't.
15297 The @code{(goto-char (point-min))} expression moves point to the
15298 beginning of the buffer.
15300 Then comes a @code{while} loop in which the `work' of the function is
15301 carried out.  In the loop, Emacs determines the length of each
15302 definition and constructs a lengths' list containing the information.
15304 Emacs kills the buffer after working through it.  This is to save
15305 space inside of Emacs.  My version of GNU Emacs 19 contained over 300
15306 source files of interest; GNU Emacs 22 contains over a thousand source
15307 files.  Another function will apply @code{lengths-list-file} to each
15308 of the files.
15310 Finally, the last expression within the @code{let} expression is the
15311 @code{lengths-list} variable; its value is returned as the value of
15312 the whole function.
15314 You can try this function by installing it in the usual fashion.  Then
15315 place your cursor after the following expression and type @kbd{C-x
15316 C-e} (@code{eval-last-sexp}).
15318 @c !!! 22.1.1 lisp sources location here
15319 @smallexample
15320 (lengths-list-file
15321  "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el")
15322 @end smallexample
15324 @noindent
15325 (You may need to change the pathname of the file; the one here is for
15326 GNU Emacs version 22.1.1.  To change the expression, copy it to
15327 the @file{*scratch*} buffer and edit it.
15329 @need 1200
15330 @noindent
15331 (Also, to see the full length of the list, rather than a truncated
15332 version, you may have to evaluate the following:
15334 @smallexample
15335 (custom-set-variables '(eval-expression-print-length nil))
15336 @end smallexample
15338 @noindent
15339 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.
15340 Then evaluate the @code{lengths-list-file} expression.)
15342 @need 1200
15343 The lengths' list for @file{debug.el} takes less than a second to
15344 produce and looks like this in GNU Emacs 22:
15346 @smallexample
15347 (83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
15348 @end smallexample
15350 @need 1500
15351 (Using my old machine, the version 19 lengths' list for @file{debug.el}
15352 took seven seconds to produce and looked like this:
15354 @smallexample
15355 (75 41 80 62 20 45 44 68 45 12 34 235)
15356 @end smallexample
15358 (The newer version of @file{debug.el} contains more defuns than the
15359 earlier one; and my new machine is much faster than the old one.)
15361 Note that the length of the last definition in the file is first in
15362 the list.
15364 @node Several files, Several files recursively, lengths-list-file, Words in a defun
15365 @section Count Words in @code{defuns} in Different Files
15367 In the previous section, we created a function that returns a list of
15368 the lengths of each definition in a file.  Now, we want to define a
15369 function to return a master list of the lengths of the definitions in
15370 a list of files.
15372 Working on each of a list of files is a repetitious act, so we can use
15373 either a @code{while} loop or recursion.
15375 @menu
15376 * lengths-list-many-files::     Return a list of the lengths of defuns.
15377 * append::                      Attach one list to another.
15378 @end menu
15380 @node lengths-list-many-files, append, Several files, Several files
15381 @ifnottex
15382 @unnumberedsubsec Determine the lengths of @code{defuns}
15383 @end ifnottex
15385 The design using a @code{while} loop is routine.  The argument passed
15386 the function is a list of files.  As we saw earlier (@pxref{Loop
15387 Example}), you can write a @code{while} loop so that the body of the
15388 loop is evaluated if such a list contains elements, but to exit the
15389 loop if the list is empty.  For this design to work, the body of the
15390 loop must contain an expression that shortens the list each time the
15391 body is evaluated, so that eventually the list is empty.  The usual
15392 technique is to set the value of the list to the value of the @sc{cdr}
15393 of the list each time the body is evaluated.
15395 @need 800
15396 The template looks like this:
15398 @smallexample
15399 @group
15400 (while @var{test-whether-list-is-empty}
15401   @var{body}@dots{}
15402   @var{set-list-to-cdr-of-list})
15403 @end group
15404 @end smallexample
15406 Also, we remember that a @code{while} loop returns @code{nil} (the
15407 result of evaluating the true-or-false-test), not the result of any
15408 evaluation within its body.  (The evaluations within the body of the
15409 loop are done for their side effects.)  However, the expression that
15410 sets the lengths' list is part of the body---and that is the value
15411 that we want returned by the function as a whole.  To do this, we
15412 enclose the @code{while} loop within a @code{let} expression, and
15413 arrange that the last element of the @code{let} expression contains
15414 the value of the lengths' list.  (@xref{Incrementing Example, , Loop
15415 Example with an Incrementing Counter}.)
15417 @findex lengths-list-many-files
15418 @need 1250
15419 These considerations lead us directly to the function itself:
15421 @smallexample
15422 @group
15423 ;;; @r{Use @code{while} loop.}
15424 (defun lengths-list-many-files (list-of-files)
15425   "Return list of lengths of defuns in LIST-OF-FILES."
15426 @end group
15427 @group
15428   (let (lengths-list)
15430 ;;; @r{true-or-false-test}
15431     (while list-of-files
15432       (setq lengths-list
15433             (append
15434              lengths-list
15436 ;;; @r{Generate a lengths' list.}
15437              (lengths-list-file
15438               (expand-file-name (car list-of-files)))))
15439 @end group
15441 @group
15442 ;;; @r{Make files' list shorter.}
15443       (setq list-of-files (cdr list-of-files)))
15445 ;;; @r{Return final value of lengths' list.}
15446     lengths-list))
15447 @end group
15448 @end smallexample
15450 @code{expand-file-name} is a built-in function that converts a file
15451 name to the absolute, long, path name form.  The function employs the
15452 name of the directory in which the function is called.
15454 @c !!! 22.1.1 lisp sources location here
15455 @need 1500
15456 Thus, if @code{expand-file-name} is called on @code{debug.el} when
15457 Emacs is visiting the
15458 @file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory,
15460 @smallexample
15461 debug.el
15462 @end smallexample
15464 @need 800
15465 @noindent
15466 becomes
15468 @c !!! 22.1.1 lisp sources location here
15469 @smallexample
15470 /usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el
15471 @end smallexample
15473 The only other new element of this function definition is the as yet
15474 unstudied function @code{append}, which merits a short section for
15475 itself.
15477 @node append,  , lengths-list-many-files, Several files
15478 @subsection The @code{append} Function
15480 @need 800
15481 The @code{append} function attaches one list to another.  Thus,
15483 @smallexample
15484 (append '(1 2 3 4) '(5 6 7 8))
15485 @end smallexample
15487 @need 800
15488 @noindent
15489 produces the list
15491 @smallexample
15492 (1 2 3 4 5 6 7 8)
15493 @end smallexample
15495 This is exactly how we want to attach two lengths' lists produced by
15496 @code{lengths-list-file} to each other.  The results contrast with
15497 @code{cons},
15499 @smallexample
15500 (cons '(1 2 3 4) '(5 6 7 8))
15501 @end smallexample
15503 @need 1250
15504 @noindent
15505 which constructs a new list in which the first argument to @code{cons}
15506 becomes the first element of the new list:
15508 @smallexample
15509 ((1 2 3 4) 5 6 7 8)
15510 @end smallexample
15512 @node Several files recursively, Prepare the data, Several files, Words in a defun
15513 @section Recursively Count Words in Different Files
15515 Besides a @code{while} loop, you can work on each of a list of files
15516 with recursion.  A recursive version of @code{lengths-list-many-files}
15517 is short and simple.
15519 The recursive function has the usual parts: the `do-again-test', the
15520 `next-step-expression', and the recursive call.  The `do-again-test'
15521 determines whether the function should call itself again, which it
15522 will do if the @code{list-of-files} contains any remaining elements;
15523 the `next-step-expression' resets the @code{list-of-files} to the
15524 @sc{cdr} of itself, so eventually the list will be empty; and the
15525 recursive call calls itself on the shorter list.  The complete
15526 function is shorter than this description!
15527 @findex recursive-lengths-list-many-files
15529 @smallexample
15530 @group
15531 (defun recursive-lengths-list-many-files (list-of-files)
15532   "Return list of lengths of each defun in LIST-OF-FILES."
15533   (if list-of-files                     ; @r{do-again-test}
15534       (append
15535        (lengths-list-file
15536         (expand-file-name (car list-of-files)))
15537        (recursive-lengths-list-many-files
15538         (cdr list-of-files)))))
15539 @end group
15540 @end smallexample
15542 @noindent
15543 In a sentence, the function returns the lengths' list for the first of
15544 the @code{list-of-files} appended to the result of calling itself on
15545 the rest of the @code{list-of-files}.
15547 Here is a test of @code{recursive-lengths-list-many-files}, along with
15548 the results of running @code{lengths-list-file} on each of the files
15549 individually.
15551 Install @code{recursive-lengths-list-many-files} and
15552 @code{lengths-list-file}, if necessary, and then evaluate the
15553 following expressions.  You may need to change the files' pathnames;
15554 those here work when this Info file and the Emacs sources are located
15555 in their customary places.  To change the expressions, copy them to
15556 the @file{*scratch*} buffer, edit them, and then evaluate them.
15558 The results are shown after the @samp{@result{}}.  (These results are
15559 for files from Emacs version 22.1.1; files from other versions of
15560 Emacs may produce different results.)
15562 @c !!! 22.1.1 lisp sources location here
15563 @smallexample
15564 @group
15565 (cd "/usr/local/share/emacs/22.1.1/")
15567 (lengths-list-file "./lisp/macros.el")
15568      @result{} (283 263 480 90)
15569 @end group
15571 @group
15572 (lengths-list-file "./lisp/mail/mailalias.el")
15573      @result{} (38 32 29 95 178 180 321 218 324)
15574 @end group
15576 @group
15577 (lengths-list-file "./lisp/makesum.el")
15578      @result{} (85 181)
15579 @end group
15581 @group
15582   (recursive-lengths-list-many-files
15583    '("./lisp/macros.el"
15584      "./lisp/mail/mailalias.el"
15585      "./lisp/makesum.el"))
15586        @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
15587 @end group
15588 @end smallexample
15590 The @code{recursive-lengths-list-many-files} function produces the
15591 output we want.
15593 The next step is to prepare the data in the list for display in a graph.
15595 @node Prepare the data,  , Several files recursively, Words in a defun
15596 @section Prepare the Data for Display in a Graph
15598 The @code{recursive-lengths-list-many-files} function returns a list
15599 of numbers.  Each number records the length of a function definition.
15600 What we need to do now is transform this data into a list of numbers
15601 suitable for generating a graph.  The new list will tell how many
15602 functions definitions contain less than 10 words and
15603 symbols, how many contain between 10 and 19 words and symbols, how
15604 many contain between 20 and 29 words and symbols, and so on.
15606 In brief, we need to go through the lengths' list produced by the
15607 @code{recursive-lengths-list-many-files} function and count the number
15608 of defuns within each range of lengths, and produce a list of those
15609 numbers.
15611 @menu
15612 * Data for Display in Detail::
15613 * Sorting::                     Sorting lists.
15614 * Files List::                  Making a list of files.
15615 * Counting function definitions::
15616 @end menu
15618 @node Data for Display in Detail, Sorting, Prepare the data, Prepare the data
15619 @ifnottex
15620 @unnumberedsubsec The Data for Display in Detail
15621 @end ifnottex
15623 Based on what we have done before, we can readily foresee that it
15624 should not be too hard to write a function that `@sc{cdr}s' down the
15625 lengths' list, looks at each element, determines which length range it
15626 is in, and increments a counter for that range.
15628 However, before beginning to write such a function, we should consider
15629 the advantages of sorting the lengths' list first, so the numbers are
15630 ordered from smallest to largest.  First, sorting will make it easier
15631 to count the numbers in each range, since two adjacent numbers will
15632 either be in the same length range or in adjacent ranges.  Second, by
15633 inspecting a sorted list, we can discover the highest and lowest
15634 number, and thereby determine the largest and smallest length range
15635 that we will need.
15637 @node Sorting, Files List, Data for Display in Detail, Prepare the data
15638 @subsection Sorting Lists
15639 @findex sort
15641 Emacs contains a function to sort lists, called (as you might guess)
15642 @code{sort}.  The @code{sort} function takes two arguments, the list
15643 to be sorted, and a predicate that determines whether the first of
15644 two list elements is ``less'' than the second.
15646 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
15647 Type Object as an Argument}), a predicate is a function that
15648 determines whether some property is true or false.  The @code{sort}
15649 function will reorder a list according to whatever property the
15650 predicate uses; this means that @code{sort} can be used to sort
15651 non-numeric lists by non-numeric criteria---it can, for example,
15652 alphabetize a list.
15654 @need 1250
15655 The @code{<} function is used when sorting a numeric list.  For example,
15657 @smallexample
15658 (sort '(4 8 21 17 33 7 21 7) '<)
15659 @end smallexample
15661 @need 800
15662 @noindent
15663 produces this:
15665 @smallexample
15666 (4 7 7 8 17 21 21 33)
15667 @end smallexample
15669 @noindent
15670 (Note that in this example, both the arguments are quoted so that the
15671 symbols are not evaluated before being passed to @code{sort} as
15672 arguments.)
15674 Sorting the list returned by the
15675 @code{recursive-lengths-list-many-files} function is straightforward;
15676 it uses the @code{<} function:
15678 @ignore
15679 2006 Oct 29
15680 In GNU Emacs 22,  eval
15681 (progn
15682   (cd "/usr/local/share/emacs/22.0.50/")
15683   (sort
15684    (recursive-lengths-list-many-files
15685     '("./lisp/macros.el"
15686       "./lisp/mail/mailalias.el"
15687       "./lisp/makesum.el"))
15688    '<))
15690 @end ignore
15692 @smallexample
15693 @group
15694 (sort
15695  (recursive-lengths-list-many-files
15696   '("./lisp/macros.el"
15697     "./lisp/mailalias.el"
15698     "./lisp/makesum.el"))
15699  '<)
15700 @end group
15701 @end smallexample
15703 @need 800
15704 @noindent
15705 which produces:
15707 @smallexample
15708 (29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
15709 @end smallexample
15711 @noindent
15712 (Note that in this example, the first argument to @code{sort} is not
15713 quoted, since the expression must be evaluated so as to produce the
15714 list that is passed to @code{sort}.)
15716 @node Files List, Counting function definitions, Sorting, Prepare the data
15717 @subsection Making a List of Files
15719 The @code{recursive-lengths-list-many-files} function requires a list
15720 of files as its argument.  For our test examples, we constructed such
15721 a list by hand; but the Emacs Lisp source directory is too large for
15722 us to do for that.  Instead, we will write a function to do the job
15723 for us.  In this function, we will use both a @code{while} loop and a
15724 recursive call.
15726 @findex directory-files
15727 We did not have to write a function like this for older versions of
15728 GNU Emacs, since they placed all the @samp{.el} files in one
15729 directory.  Instead, we were able to use the @code{directory-files}
15730 function, which lists the names of files that match a specified
15731 pattern within a single directory.
15733 However, recent versions of Emacs place Emacs Lisp files in
15734 sub-directories of the top level @file{lisp} directory.  This
15735 re-arrangement eases navigation.  For example, all the mail related
15736 files are in a @file{lisp} sub-directory called @file{mail}.  But at
15737 the same time, this arrangement forces us to create a file listing
15738 function that descends into the sub-directories.
15740 @findex files-in-below-directory
15741 We can create this function, called @code{files-in-below-directory},
15742 using familiar functions such as @code{car}, @code{nthcdr}, and
15743 @code{substring} in conjunction with an existing function called
15744 @code{directory-files-and-attributes}.  This latter function not only
15745 lists all the filenames in a directory, including the names
15746 of sub-directories, but also their attributes.
15748 To restate our goal: to create a function that will enable us
15749 to feed filenames to @code{recursive-lengths-list-many-files}
15750 as a list that looks like this (but with more elements):
15752 @smallexample
15753 @group
15754 ("./lisp/macros.el"
15755  "./lisp/mail/rmail.el"
15756  "./lisp/makesum.el")
15757 @end group
15758 @end smallexample
15760 The @code{directory-files-and-attributes} function returns a list of
15761 lists.  Each of the lists within the main list consists of 13
15762 elements.  The first element is a string that contains the name of the
15763 file -- which, in GNU/Linux, may be a `directory file', that is to
15764 say, a file with the special attributes of a directory.  The second
15765 element of the list is @code{t} for a directory, a string
15766 for symbolic link (the string is the name linked to), or @code{nil}.
15768 For example, the first @samp{.el} file in the @file{lisp/} directory
15769 is @file{abbrev.el}.  Its name is
15770 @file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a
15771 directory or a symbolic link.
15773 @need 1000
15774 This is how @code{directory-files-and-attributes} lists that file and
15775 its attributes:
15777 @smallexample
15778 @group
15779 ("abbrev.el"
15782 1000
15784 @end group
15785 @group
15786 (17733 259)
15787 (17491 28834)
15788 (17596 62124)
15789 13157
15790 "-rw-rw-r--"
15791 @end group
15792 @group
15794 2971624
15795 773)
15796 @end group
15797 @end smallexample
15799 @need 1200
15800 On the other hand, @file{mail/} is a directory within the @file{lisp/}
15801 directory.  The beginning of its listing looks like this:
15803 @smallexample
15804 @group
15805 ("mail"
15807 @dots{}
15809 @end group
15810 @end smallexample
15812 (To learn about the different attributes, look at the documentation of
15813 @code{file-attributes}.  Bear in mind that the @code{file-attributes}
15814 function does not list the filename, so its first element is
15815 @code{directory-files-and-attributes}'s second element.)
15817 We will want our new function, @code{files-in-below-directory}, to
15818 list the @samp{.el} files in the directory it is told to check, and in
15819 any directories below that directory.
15821 This gives us a hint on how to construct
15822 @code{files-in-below-directory}:  within a directory, the function
15823 should add @samp{.el} filenames to a list; and if, within a directory,
15824 the function comes upon a sub-directory, it should go into that
15825 sub-directory and repeat its actions.
15827 However, we should note that every directory contains a name that
15828 refers to itself, called @file{.}, (``dot'') and a name that refers to
15829 its parent directory, called @file{..} (``double dot'').  (In
15830 @file{/}, the root directory, @file{..} refers to itself, since
15831 @file{/} has no parent.)  Clearly, we do not want our
15832 @code{files-in-below-directory} function to enter those directories,
15833 since they always lead us, directly or indirectly, to the current
15834 directory.
15836 Consequently, our @code{files-in-below-directory} function must do
15837 several tasks:
15839 @itemize @bullet
15840 @item
15841 Check to see whether it is looking at a filename that ends in
15842 @samp{.el}; and if so, add its name to a list.
15844 @item
15845 Check to see whether it is looking at a filename that is the name of a
15846 directory; and if so,
15848 @itemize @minus
15849 @item
15850 Check to see whether it is looking at @file{.}  or @file{..}; and if
15851 so skip it.
15853 @item
15854 Or else, go into that directory and repeat the process.
15855 @end itemize
15856 @end itemize
15858 Let's write a function definition to do these tasks.  We will use a
15859 @code{while} loop to move from one filename to another within a
15860 directory, checking what needs to be done; and we will use a recursive
15861 call to repeat the actions on each sub-directory.  The recursive
15862 pattern is `accumulate'
15863 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
15864 using @code{append} as the combiner.
15866 @ignore
15867 (directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
15868 (shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
15870 (directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
15871 (shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
15872 @end ignore
15874 @c  /usr/local/share/emacs/22.1.1/lisp/
15876 @need 800
15877 Here is the function:
15879 @smallexample
15880 @group
15881 (defun files-in-below-directory (directory)
15882   "List the .el files in DIRECTORY and in its sub-directories."
15883   ;; Although the function will be used non-interactively,
15884   ;; it will be easier to test if we make it interactive.
15885   ;; The directory will have a name such as
15886   ;;  "/usr/local/share/emacs/22.1.1/lisp/"
15887   (interactive "DDirectory name: ")
15888 @end group
15889 @group
15890   (let (el-files-list
15891         (current-directory-list
15892          (directory-files-and-attributes directory t)))
15893     ;; while we are in the current directory
15894     (while current-directory-list
15895 @end group
15896 @group
15897       (cond
15898        ;; check to see whether filename ends in `.el'
15899        ;; and if so, append its name to a list.
15900        ((equal ".el" (substring (car (car current-directory-list)) -3))
15901         (setq el-files-list
15902               (cons (car (car current-directory-list)) el-files-list)))
15903 @end group
15904 @group
15905        ;; check whether filename is that of a directory
15906        ((eq t (car (cdr (car current-directory-list))))
15907         ;; decide whether to skip or recurse
15908         (if
15909             (equal "."
15910                    (substring (car (car current-directory-list)) -1))
15911             ;; then do nothing since filename is that of
15912             ;;   current directory or parent, "." or ".."
15913             ()
15914 @end group
15915 @group
15916           ;; else descend into the directory and repeat the process
15917           (setq el-files-list
15918                 (append
15919                  (files-in-below-directory
15920                   (car (car current-directory-list)))
15921                  el-files-list)))))
15922       ;; move to the next filename in the list; this also
15923       ;; shortens the list so the while loop eventually comes to an end
15924       (setq current-directory-list (cdr current-directory-list)))
15925     ;; return the filenames
15926     el-files-list))
15927 @end group
15928 @end smallexample
15930 @c (files-in-below-directory "/usr/local/src/emacs/lisp/")
15931 @c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
15933 The @code{files-in-below-directory} @code{directory-files} function
15934 takes one argument, the name of a directory.
15936 @need 1250
15937 Thus, on my system,
15939 @c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15941 @c !!! 22.1.1 lisp sources location here
15942 @smallexample
15943 @group
15944 (length
15945  (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
15946 @end group
15947 @end smallexample
15949 @noindent
15950 tells me that in and below my Lisp sources directory are 1031
15951 @samp{.el} files.
15953 @code{files-in-below-directory} returns a list in reverse alphabetical
15954 order.  An expression to sort the list in alphabetical order looks
15955 like this:
15957 @smallexample
15958 @group
15959 (sort
15960  (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
15961  'string-lessp)
15962 @end group
15963 @end smallexample
15965 @ignore
15966 (defun test ()
15967   "Test how long it takes to find lengths of all sorted elisp defuns."
15968   (insert "\n" (current-time-string) "\n")
15969   (sit-for 0)
15970   (sort
15971    (recursive-lengths-list-many-files
15972     (files-in-below-directory "/usr/local/src/emacs/lisp/"))
15973    '<)
15974   (insert (format "%s" (current-time-string))))
15975 @end ignore
15977 @node Counting function definitions,  , Files List, Prepare the data
15978 @subsection Counting function definitions
15980 Our immediate goal is to generate a list that tells us how many
15981 function definitions contain fewer than 10 words and symbols, how many
15982 contain between 10 and 19 words and symbols, how many contain between
15983 20 and 29 words and symbols, and so on.
15985 With a sorted list of numbers, this is easy: count how many elements
15986 of the list are smaller than 10, then, after moving past the numbers
15987 just counted, count how many are smaller than 20, then, after moving
15988 past the numbers just counted, count how many are smaller than 30, and
15989 so on.  Each of the numbers, 10, 20, 30, 40, and the like, is one
15990 larger than the top of that range.  We can call the list of such
15991 numbers the @code{top-of-ranges} list.
15993 @need 1200
15994 If we wished, we could generate this list automatically, but it is
15995 simpler to write a list manually.  Here it is:
15996 @vindex top-of-ranges
15998 @smallexample
15999 @group
16000 (defvar top-of-ranges
16001  '(10  20  30  40  50
16002    60  70  80  90 100
16003   110 120 130 140 150
16004   160 170 180 190 200
16005   210 220 230 240 250
16006   260 270 280 290 300)
16007  "List specifying ranges for `defuns-per-range'.")
16008 @end group
16009 @end smallexample
16011 To change the ranges, we edit this list.
16013 Next, we need to write the function that creates the list of the
16014 number of definitions within each range.  Clearly, this function must
16015 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
16016 as arguments.
16018 The @code{defuns-per-range} function must do two things again and
16019 again: it must count the number of definitions within a range
16020 specified by the current top-of-range value; and it must shift to the
16021 next higher value in the @code{top-of-ranges} list after counting the
16022 number of definitions in the current range.  Since each of these
16023 actions is repetitive, we can use @code{while} loops for the job.
16024 One loop counts the number of definitions in the range defined by the
16025 current top-of-range value, and the other loop selects each of the
16026 top-of-range values in turn.
16028 Several entries of the @code{sorted-lengths} list are counted for each
16029 range; this means that the loop for the @code{sorted-lengths} list
16030 will be inside the loop for the @code{top-of-ranges} list, like a
16031 small gear inside a big gear.
16033 The inner loop counts the number of definitions within the range.  It
16034 is a simple counting loop of the type we have seen before.
16035 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
16036 The true-or-false test of the loop tests whether the value from the
16037 @code{sorted-lengths} list is smaller than the current value of the
16038 top of the range.  If it is, the function increments the counter and
16039 tests the next value from the @code{sorted-lengths} list.
16041 @need 1250
16042 The inner loop looks like this:
16044 @smallexample
16045 @group
16046 (while @var{length-element-smaller-than-top-of-range}
16047   (setq number-within-range (1+ number-within-range))
16048   (setq sorted-lengths (cdr sorted-lengths)))
16049 @end group
16050 @end smallexample
16052 The outer loop must start with the lowest value of the
16053 @code{top-of-ranges} list, and then be set to each of the succeeding
16054 higher values in turn.  This can be done with a loop like this:
16056 @smallexample
16057 @group
16058 (while top-of-ranges
16059   @var{body-of-loop}@dots{}
16060   (setq top-of-ranges (cdr top-of-ranges)))
16061 @end group
16062 @end smallexample
16064 @need 1200
16065 Put together, the two loops look like this:
16067 @smallexample
16068 @group
16069 (while top-of-ranges
16071   ;; @r{Count the number of elements within the current range.}
16072   (while @var{length-element-smaller-than-top-of-range}
16073     (setq number-within-range (1+ number-within-range))
16074     (setq sorted-lengths (cdr sorted-lengths)))
16076   ;; @r{Move to next range.}
16077   (setq top-of-ranges (cdr top-of-ranges)))
16078 @end group
16079 @end smallexample
16081 In addition, in each circuit of the outer loop, Emacs should record
16082 the number of definitions within that range (the value of
16083 @code{number-within-range}) in a list.  We can use @code{cons} for
16084 this purpose.  (@xref{cons, , @code{cons}}.)
16086 The @code{cons} function works fine, except that the list it
16087 constructs will contain the number of definitions for the highest
16088 range at its beginning and the number of definitions for the lowest
16089 range at its end.  This is because @code{cons} attaches new elements
16090 of the list to the beginning of the list, and since the two loops are
16091 working their way through the lengths' list from the lower end first,
16092 the @code{defuns-per-range-list} will end up largest number first.
16093 But we will want to print our graph with smallest values first and the
16094 larger later.  The solution is to reverse the order of the
16095 @code{defuns-per-range-list}.  We can do this using the
16096 @code{nreverse} function, which reverses the order of a list.
16097 @findex nreverse
16099 @need 800
16100 For example,
16102 @smallexample
16103 (nreverse '(1 2 3 4))
16104 @end smallexample
16106 @need 800
16107 @noindent
16108 produces:
16110 @smallexample
16111 (4 3 2 1)
16112 @end smallexample
16114 Note that the @code{nreverse} function is ``destructive''---that is,
16115 it changes the list to which it is applied; this contrasts with the
16116 @code{car} and @code{cdr} functions, which are non-destructive.  In
16117 this case, we do not want the original @code{defuns-per-range-list},
16118 so it does not matter that it is destroyed.  (The @code{reverse}
16119 function provides a reversed copy of a list, leaving the original list
16120 as is.)
16121 @findex reverse
16123 @need 1250
16124 Put all together, the @code{defuns-per-range} looks like this:
16126 @smallexample
16127 @group
16128 (defun defuns-per-range (sorted-lengths top-of-ranges)
16129   "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
16130   (let ((top-of-range (car top-of-ranges))
16131         (number-within-range 0)
16132         defuns-per-range-list)
16133 @end group
16135 @group
16136     ;; @r{Outer loop.}
16137     (while top-of-ranges
16138 @end group
16140 @group
16141       ;; @r{Inner loop.}
16142       (while (and
16143               ;; @r{Need number for numeric test.}
16144               (car sorted-lengths)
16145               (< (car sorted-lengths) top-of-range))
16146 @end group
16148 @group
16149         ;; @r{Count number of definitions within current range.}
16150         (setq number-within-range (1+ number-within-range))
16151         (setq sorted-lengths (cdr sorted-lengths)))
16153       ;; @r{Exit inner loop but remain within outer loop.}
16154 @end group
16156 @group
16157       (setq defuns-per-range-list
16158             (cons number-within-range defuns-per-range-list))
16159       (setq number-within-range 0)      ; @r{Reset count to zero.}
16160 @end group
16162 @group
16163       ;; @r{Move to next range.}
16164       (setq top-of-ranges (cdr top-of-ranges))
16165       ;; @r{Specify next top of range value.}
16166       (setq top-of-range (car top-of-ranges)))
16167 @end group
16169 @group
16170     ;; @r{Exit outer loop and count the number of defuns larger than}
16171     ;; @r{  the largest top-of-range value.}
16172     (setq defuns-per-range-list
16173           (cons
16174            (length sorted-lengths)
16175            defuns-per-range-list))
16176 @end group
16178 @group
16179     ;; @r{Return a list of the number of definitions within each range,}
16180     ;; @r{  smallest to largest.}
16181     (nreverse defuns-per-range-list)))
16182 @end group
16183 @end smallexample
16185 @need 1200
16186 @noindent
16187 The function is straightforward except for one subtle feature.  The
16188 true-or-false test of the inner loop looks like this:
16190 @smallexample
16191 @group
16192 (and (car sorted-lengths)
16193      (< (car sorted-lengths) top-of-range))
16194 @end group
16195 @end smallexample
16197 @need 800
16198 @noindent
16199 instead of like this:
16201 @smallexample
16202 (< (car sorted-lengths) top-of-range)
16203 @end smallexample
16205 The purpose of the test is to determine whether the first item in the
16206 @code{sorted-lengths} list is less than the value of the top of the
16207 range.
16209 The simple version of the test works fine unless the
16210 @code{sorted-lengths} list has a @code{nil} value.  In that case, the
16211 @code{(car sorted-lengths)} expression function returns
16212 @code{nil}.  The @code{<} function cannot compare a number to
16213 @code{nil}, which is an empty list, so Emacs signals an error and
16214 stops the function from attempting to continue to execute.
16216 The @code{sorted-lengths} list always becomes @code{nil} when the
16217 counter reaches the end of the list.  This means that any attempt to
16218 use the @code{defuns-per-range} function with the simple version of
16219 the test will fail.
16221 We solve the problem by using the @code{(car sorted-lengths)}
16222 expression in conjunction with the @code{and} expression.  The
16223 @code{(car sorted-lengths)} expression returns a non-@code{nil}
16224 value so long as the list has at least one number within it, but
16225 returns @code{nil} if the list is empty.  The @code{and} expression
16226 first evaluates the @code{(car sorted-lengths)} expression, and
16227 if it is @code{nil}, returns false @emph{without} evaluating the
16228 @code{<} expression.  But if the @code{(car sorted-lengths)}
16229 expression returns a non-@code{nil} value, the @code{and} expression
16230 evaluates the @code{<} expression, and returns that value as the value
16231 of the @code{and} expression.
16233 @c colon in printed section title causes problem in Info cross reference
16234 This way, we avoid an error.
16235 @iftex
16236 @noindent
16237 (For information about @code{and}, see
16238 @ref{kill-new function, , The @code{kill-new} function}.)
16239 @end iftex
16240 @ifinfo
16241 @noindent
16242 (@xref{kill-new function, , The @code{kill-new} function}, for
16243 information about @code{and}.)
16244 @end ifinfo
16246 Here is a short test of the @code{defuns-per-range} function.  First,
16247 evaluate the expression that binds (a shortened)
16248 @code{top-of-ranges} list to the list of values, then evaluate the
16249 expression for binding the @code{sorted-lengths} list, and then
16250 evaluate the @code{defuns-per-range} function.
16252 @smallexample
16253 @group
16254 ;; @r{(Shorter list than we will use later.)}
16255 (setq top-of-ranges
16256  '(110 120 130 140 150
16257    160 170 180 190 200))
16259 (setq sorted-lengths
16260       '(85 86 110 116 122 129 154 176 179 200 265 300 300))
16262 (defuns-per-range sorted-lengths top-of-ranges)
16263 @end group
16264 @end smallexample
16266 @need 800
16267 @noindent
16268 The list returned looks like this:
16270 @smallexample
16271 (2 2 2 0 0 1 0 2 0 0 4)
16272 @end smallexample
16274 @noindent
16275 Indeed, there are two elements of the @code{sorted-lengths} list
16276 smaller than 110, two elements between 110 and 119, two elements
16277 between 120 and 129, and so on.  There are four elements with a value
16278 of 200 or larger.
16280 @c The next step is to turn this numbers' list into a graph.
16281 @node Readying a Graph, Emacs Initialization, Words in a defun, Top
16282 @chapter Readying a Graph
16283 @cindex Readying a graph
16284 @cindex Graph prototype
16285 @cindex Prototype graph
16286 @cindex Body of graph
16288 Our goal is to construct a graph showing the numbers of function
16289 definitions of various lengths in the Emacs lisp sources.
16291 As a practical matter, if you were creating a graph, you would
16292 probably use a program such as @code{gnuplot} to do the job.
16293 (@code{gnuplot} is nicely integrated into GNU Emacs.)  In this case,
16294 however, we create one from scratch, and in the process we will
16295 re-acquaint ourselves with some of what we learned before and learn
16296 more.
16298 In this chapter, we will first write a simple graph printing function.
16299 This first definition will be a @dfn{prototype}, a rapidly written
16300 function that enables us to reconnoiter this unknown graph-making
16301 territory.  We will discover dragons, or find that they are myth.
16302 After scouting the terrain, we will feel more confident and enhance
16303 the function to label the axes automatically.
16305 @menu
16306 * Columns of a graph::
16307 * graph-body-print::            How to print the body of a graph.
16308 * recursive-graph-body-print::
16309 * Printed Axes::
16310 * Line Graph Exercise::
16311 @end menu
16313 @node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph
16314 @ifnottex
16315 @unnumberedsec Printing the Columns of a Graph
16316 @end ifnottex
16318 Since Emacs is designed to be flexible and work with all kinds of
16319 terminals, including character-only terminals, the graph will need to
16320 be made from one of the `typewriter' symbols.  An asterisk will do; as
16321 we enhance the graph-printing function, we can make the choice of
16322 symbol a user option.
16324 We can call this function @code{graph-body-print}; it will take a
16325 @code{numbers-list} as its only argument.  At this stage, we will not
16326 label the graph, but only print its body.
16328 The @code{graph-body-print} function inserts a vertical column of
16329 asterisks for each element in the @code{numbers-list}.  The height of
16330 each line is determined by the value of that element of the
16331 @code{numbers-list}.
16333 Inserting columns is a repetitive act; that means that this function can
16334 be written either with a @code{while} loop or recursively.
16336 Our first challenge is to discover how to print a column of asterisks.
16337 Usually, in Emacs, we print characters onto a screen horizontally,
16338 line by line, by typing.  We have two routes we can follow: write our
16339 own column-insertion function or discover whether one exists in Emacs.
16341 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
16342 command.  This command is like the @kbd{C-h a} (@code{command-apropos})
16343 command, except that the latter finds only those functions that are
16344 commands.  The @kbd{M-x apropos} command lists all symbols that match
16345 a regular expression, including functions that are not interactive.
16346 @findex apropos
16348 What we want to look for is some command that prints or inserts
16349 columns.  Very likely, the name of the function will contain either
16350 the word `print' or the word `insert' or the word `column'.
16351 Therefore, we can simply type @kbd{M-x apropos RET
16352 print\|insert\|column RET} and look at the result.  On my system, this
16353 command once too takes quite some time, and then produced a list of 79
16354 functions and variables.  Now it does not take much time at all and
16355 produces a list of 211 functions and variables.  Scanning down the
16356 list, the only function that looks as if it might do the job is
16357 @code{insert-rectangle}.
16359 @need 1200
16360 Indeed, this is the function we want; its documentation says:
16362 @smallexample
16363 @group
16364 insert-rectangle:
16365 Insert text of RECTANGLE with upper left corner at point.
16366 RECTANGLE's first line is inserted at point,
16367 its second line is inserted at a point vertically under point, etc.
16368 RECTANGLE should be a list of strings.
16369 After this command, the mark is at the upper left corner
16370 and point is at the lower right corner.
16371 @end group
16372 @end smallexample
16374 We can run a quick test, to make sure it does what we expect of it.
16376 Here is the result of placing the cursor after the
16377 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
16378 (@code{eval-last-sexp}).  The function inserts the strings
16379 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
16380 point.  Also the function returns @code{nil}.
16382 @smallexample
16383 @group
16384 (insert-rectangle '("first" "second" "third"))first
16385                                               second
16386                                               thirdnil
16387 @end group
16388 @end smallexample
16390 @noindent
16391 Of course, we won't be inserting the text of the
16392 @code{insert-rectangle} expression itself into the buffer in which we
16393 are making the graph, but will call the function from our program.  We
16394 shall, however, have to make sure that point is in the buffer at the
16395 place where the @code{insert-rectangle} function will insert its
16396 column of strings.
16398 If you are reading this in Info, you can see how this works by
16399 switching to another buffer, such as the @file{*scratch*} buffer,
16400 placing point somewhere in the buffer, typing @kbd{M-:}, typing the
16401 @code{insert-rectangle} expression into the minibuffer at the prompt,
16402 and then typing @key{RET}.  This causes Emacs to evaluate the
16403 expression in the minibuffer, but to use as the value of point the
16404 position of point in the @file{*scratch*} buffer.  (@kbd{M-:}  is the
16405 keybinding for @code{eval-expression}. Also, @code{nil} does not
16406 appear in the @file{*scratch*} buffer since the expression is
16407 evaluated in the minibuffer.)
16409 We find when we do this that point ends up at the end of the last
16410 inserted line---that is to say, this function moves point as a
16411 side-effect.  If we were to repeat the command, with point at this
16412 position, the next insertion would be below and to the right of the
16413 previous insertion.  We don't want this!  If we are going to make a
16414 bar graph, the columns need to be beside each other.
16416 So we discover that each cycle of the column-inserting @code{while}
16417 loop must reposition point to the place we want it, and that place
16418 will be at the top, not the bottom, of the column.  Moreover, we
16419 remember that when we print a graph, we do not expect all the columns
16420 to be the same height.  This means that the top of each column may be
16421 at a different height from the previous one.  We cannot simply
16422 reposition point to the same line each time, but moved over to the
16423 right---or perhaps we can@dots{}
16425 We are planning to make the columns of the bar graph out of asterisks.
16426 The number of asterisks in the column is the number specified by the
16427 current element of the @code{numbers-list}.  We need to construct a
16428 list of asterisks of the right length for each call to
16429 @code{insert-rectangle}.  If this list consists solely of the requisite
16430 number of asterisks, then we will have position point the right number
16431 of lines above the base for the graph to print correctly.  This could
16432 be difficult.
16434 Alternatively, if we can figure out some way to pass
16435 @code{insert-rectangle} a list of the same length each time, then we
16436 can place point on the same line each time, but move it over one
16437 column to the right for each new column.  If we do this, however, some
16438 of the entries in the list passed to @code{insert-rectangle} must be
16439 blanks rather than asterisks.  For example, if the maximum height of
16440 the graph is 5, but the height of the column is 3, then
16441 @code{insert-rectangle} requires an argument that looks like this:
16443 @smallexample
16444 (" " " " "*" "*" "*")
16445 @end smallexample
16447 This last proposal is not so difficult, so long as we can determine
16448 the column height.  There are two ways for us to specify the column
16449 height: we can arbitrarily state what it will be, which would work
16450 fine for graphs of that height; or we can search through the list of
16451 numbers and use the maximum height of the list as the maximum height
16452 of the graph.  If the latter operation were difficult, then the former
16453 procedure would be easiest, but there is a function built into Emacs
16454 that determines the maximum of its arguments.  We can use that
16455 function.  The function is called @code{max} and it returns the
16456 largest of all its arguments, which must be numbers.  Thus, for
16457 example,
16459 @smallexample
16460 (max  3 4 6 5 7 3)
16461 @end smallexample
16463 @noindent
16464 returns 7.  (A corresponding function called @code{min} returns the
16465 smallest of all its arguments.)
16466 @findex max
16467 @findex min
16469 However, we cannot simply call @code{max} on the @code{numbers-list};
16470 the @code{max} function expects numbers as its argument, not a list of
16471 numbers.  Thus, the following expression,
16473 @smallexample
16474 (max  '(3 4 6 5 7 3))
16475 @end smallexample
16477 @need 800
16478 @noindent
16479 produces the following error message;
16481 @smallexample
16482 Wrong type of argument:  number-or-marker-p, (3 4 6 5 7 3)
16483 @end smallexample
16485 @findex apply
16486 We need a function that passes a list of arguments to a function.
16487 This function is @code{apply}.  This function `applies' its first
16488 argument (a function) to its remaining arguments, the last of which
16489 may be a list.
16491 @need 1250
16492 For example,
16494 @smallexample
16495 (apply 'max 3 4 7 3 '(4 8 5))
16496 @end smallexample
16498 @noindent
16499 returns 8.
16501 (Incidentally, I don't know how you would learn of this function
16502 without a book such as this.  It is possible to discover other
16503 functions, like @code{search-forward} or @code{insert-rectangle}, by
16504 guessing at a part of their names and then using @code{apropos}.  Even
16505 though its base in metaphor is clear---`apply' its first argument to
16506 the rest---I doubt a novice would come up with that particular word
16507 when using @code{apropos} or other aid.  Of course, I could be wrong;
16508 after all, the function was first named by someone who had to invent
16509 it.)
16511 The second and subsequent arguments to @code{apply} are optional, so
16512 we can use @code{apply} to call a function and pass the elements of a
16513 list to it, like this, which also returns 8:
16515 @smallexample
16516 (apply 'max '(4 8 5))
16517 @end smallexample
16519 This latter way is how we will use @code{apply}.  The
16520 @code{recursive-lengths-list-many-files} function returns a numbers'
16521 list to which we can apply @code{max} (we could also apply @code{max} to
16522 the sorted numbers' list; it does not matter whether the list is
16523 sorted or not.)
16525 @need 800
16526 Hence, the operation for finding the maximum height of the graph is this:
16528 @smallexample
16529 (setq max-graph-height (apply 'max numbers-list))
16530 @end smallexample
16532 Now we can return to the question of how to create a list of strings
16533 for a column of the graph.  Told the maximum height of the graph
16534 and the number of asterisks that should appear in the column, the
16535 function should return a list of strings for the
16536 @code{insert-rectangle} command to insert.
16538 Each column is made up of asterisks or blanks.  Since the function is
16539 passed the value of the height of the column and the number of
16540 asterisks in the column, the number of blanks can be found by
16541 subtracting the number of asterisks from the height of the column.
16542 Given the number of blanks and the number of asterisks, two
16543 @code{while} loops can be used to construct the list:
16545 @smallexample
16546 @group
16547 ;;; @r{First version.}
16548 (defun column-of-graph (max-graph-height actual-height)
16549   "Return list of strings that is one column of a graph."
16550   (let ((insert-list nil)
16551         (number-of-top-blanks
16552          (- max-graph-height actual-height)))
16553 @end group
16555 @group
16556     ;; @r{Fill in asterisks.}
16557     (while (> actual-height 0)
16558       (setq insert-list (cons "*" insert-list))
16559       (setq actual-height (1- actual-height)))
16560 @end group
16562 @group
16563     ;; @r{Fill in blanks.}
16564     (while (> number-of-top-blanks 0)
16565       (setq insert-list (cons " " insert-list))
16566       (setq number-of-top-blanks
16567             (1- number-of-top-blanks)))
16568 @end group
16570 @group
16571     ;; @r{Return whole list.}
16572     insert-list))
16573 @end group
16574 @end smallexample
16576 If you install this function and then evaluate the following
16577 expression you will see that it returns the list as desired:
16579 @smallexample
16580 (column-of-graph 5 3)
16581 @end smallexample
16583 @need 800
16584 @noindent
16585 returns
16587 @smallexample
16588 (" " " " "*" "*" "*")
16589 @end smallexample
16591 As written, @code{column-of-graph} contains a major flaw: the symbols
16592 used for the blank and for the marked entries in the column are
16593 `hard-coded' as a space and asterisk.  This is fine for a prototype,
16594 but you, or another user, may wish to use other symbols.  For example,
16595 in testing the graph function, you many want to use a period in place
16596 of the space, to make sure the point is being repositioned properly
16597 each time the @code{insert-rectangle} function is called; or you might
16598 want to substitute a @samp{+} sign or other symbol for the asterisk.
16599 You might even want to make a graph-column that is more than one
16600 display column wide.  The program should be more flexible.  The way to
16601 do that is to replace the blank and the asterisk with two variables
16602 that we can call @code{graph-blank} and @code{graph-symbol} and define
16603 those variables separately.
16605 Also, the documentation is not well written.  These considerations
16606 lead us to the second version of the function:
16608 @smallexample
16609 @group
16610 (defvar graph-symbol "*"
16611   "String used as symbol in graph, usually an asterisk.")
16612 @end group
16614 @group
16615 (defvar graph-blank " "
16616   "String used as blank in graph, usually a blank space.
16617 graph-blank must be the same number of columns wide
16618 as graph-symbol.")
16619 @end group
16620 @end smallexample
16622 @noindent
16623 (For an explanation of @code{defvar}, see
16624 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
16626 @smallexample
16627 @group
16628 ;;; @r{Second version.}
16629 (defun column-of-graph (max-graph-height actual-height)
16630   "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
16632 @end group
16633 @group
16634 The graph-symbols are contiguous entries at the end
16635 of the list.
16636 The list will be inserted as one column of a graph.
16637 The strings are either graph-blank or graph-symbol."
16638 @end group
16640 @group
16641   (let ((insert-list nil)
16642         (number-of-top-blanks
16643          (- max-graph-height actual-height)))
16644 @end group
16646 @group
16647     ;; @r{Fill in @code{graph-symbols}.}
16648     (while (> actual-height 0)
16649       (setq insert-list (cons graph-symbol insert-list))
16650       (setq actual-height (1- actual-height)))
16651 @end group
16653 @group
16654     ;; @r{Fill in @code{graph-blanks}.}
16655     (while (> number-of-top-blanks 0)
16656       (setq insert-list (cons graph-blank insert-list))
16657       (setq number-of-top-blanks
16658             (1- number-of-top-blanks)))
16660     ;; @r{Return whole list.}
16661     insert-list))
16662 @end group
16663 @end smallexample
16665 If we wished, we could rewrite @code{column-of-graph} a third time to
16666 provide optionally for a line graph as well as for a bar graph.  This
16667 would not be hard to do.  One way to think of a line graph is that it
16668 is no more than a bar graph in which the part of each bar that is
16669 below the top is blank.  To construct a column for a line graph, the
16670 function first constructs a list of blanks that is one shorter than
16671 the value, then it uses @code{cons} to attach a graph symbol to the
16672 list; then it uses @code{cons} again to attach the `top blanks' to
16673 the list.
16675 It is easy to see how to write such a function, but since we don't
16676 need it, we will not do it.  But the job could be done, and if it were
16677 done, it would be done with @code{column-of-graph}.  Even more
16678 important, it is worth noting that few changes would have to be made
16679 anywhere else.  The enhancement, if we ever wish to make it, is
16680 simple.
16682 Now, finally, we come to our first actual graph printing function.
16683 This prints the body of a graph, not the labels for the vertical and
16684 horizontal axes, so we can call this @code{graph-body-print}.
16686 @node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph
16687 @section The @code{graph-body-print} Function
16688 @findex graph-body-print
16690 After our preparation in the preceding section, the
16691 @code{graph-body-print} function is straightforward.  The function
16692 will print column after column of asterisks and blanks, using the
16693 elements of a numbers' list to specify the number of asterisks in each
16694 column.  This is a repetitive act, which means we can use a
16695 decrementing @code{while} loop or recursive function for the job.  In
16696 this section, we will write the definition using a @code{while} loop.
16698 The @code{column-of-graph} function requires the height of the graph
16699 as an argument, so we should determine and record that as a local variable.
16701 This leads us to the following template for the @code{while} loop
16702 version of this function:
16704 @smallexample
16705 @group
16706 (defun graph-body-print (numbers-list)
16707   "@var{documentation}@dots{}"
16708   (let ((height  @dots{}
16709          @dots{}))
16710 @end group
16712 @group
16713     (while numbers-list
16714       @var{insert-columns-and-reposition-point}
16715       (setq numbers-list (cdr numbers-list)))))
16716 @end group
16717 @end smallexample
16719 @noindent
16720 We need to fill in the slots of the template.
16722 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
16723 determine the height of the graph.
16725 The @code{while} loop will cycle through the @code{numbers-list} one
16726 element at a time.  As it is shortened by the @code{(setq numbers-list
16727 (cdr numbers-list))} expression, the @sc{car} of each instance of the
16728 list is the value of the argument for @code{column-of-graph}.
16730 At each cycle of the @code{while} loop, the @code{insert-rectangle}
16731 function inserts the list returned by @code{column-of-graph}.  Since
16732 the @code{insert-rectangle} function moves point to the lower right of
16733 the inserted rectangle, we need to save the location of point at the
16734 time the rectangle is inserted, move back to that position after the
16735 rectangle is inserted, and then move horizontally to the next place
16736 from which @code{insert-rectangle} is called.
16738 If the inserted columns are one character wide, as they will be if
16739 single blanks and asterisks are used, the repositioning command is
16740 simply @code{(forward-char 1)}; however, the width of a column may be
16741 greater than one.  This means that the repositioning command should be
16742 written @code{(forward-char symbol-width)}.  The @code{symbol-width}
16743 itself is the length of a @code{graph-blank} and can be found using
16744 the expression @code{(length graph-blank)}.  The best place to bind
16745 the @code{symbol-width} variable to the value of the width of graph
16746 column is in the varlist of the @code{let} expression.
16748 @need 1250
16749 These considerations lead to the following function definition:
16751 @smallexample
16752 @group
16753 (defun graph-body-print (numbers-list)
16754   "Print a bar graph of the NUMBERS-LIST.
16755 The numbers-list consists of the Y-axis values."
16757   (let ((height (apply 'max numbers-list))
16758         (symbol-width (length graph-blank))
16759         from-position)
16760 @end group
16762 @group
16763     (while numbers-list
16764       (setq from-position (point))
16765       (insert-rectangle
16766        (column-of-graph height (car numbers-list)))
16767       (goto-char from-position)
16768       (forward-char symbol-width)
16769 @end group
16770 @group
16771       ;; @r{Draw graph column by column.}
16772       (sit-for 0)
16773       (setq numbers-list (cdr numbers-list)))
16774 @end group
16775 @group
16776     ;; @r{Place point for X axis labels.}
16777     (forward-line height)
16778     (insert "\n")
16780 @end group
16781 @end smallexample
16783 @noindent
16784 The one unexpected expression in this function is the
16785 @w{@code{(sit-for 0)}} expression in the @code{while} loop.  This
16786 expression makes the graph printing operation more interesting to
16787 watch than it would be otherwise.  The expression causes Emacs to
16788 `sit' or do nothing for a zero length of time and then redraw the
16789 screen.  Placed here, it causes Emacs to redraw the screen column by
16790 column.  Without it, Emacs would not redraw the screen until the
16791 function exits.
16793 We can test @code{graph-body-print} with a short list of numbers.
16795 @enumerate
16796 @item
16797 Install @code{graph-symbol}, @code{graph-blank},
16798 @code{column-of-graph}, which are in
16799 @iftex
16800 @ref{Readying a Graph, , Readying a Graph},
16801 @end iftex
16802 @ifinfo
16803 @ref{Columns of a graph},
16804 @end ifinfo
16805 and @code{graph-body-print}.
16807 @need 800
16808 @item
16809 Copy the following expression:
16811 @smallexample
16812 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
16813 @end smallexample
16815 @item
16816 Switch to the @file{*scratch*} buffer and place the cursor where you
16817 want the graph to start.
16819 @item
16820 Type @kbd{M-:} (@code{eval-expression}).
16822 @item
16823 Yank the @code{graph-body-print} expression into the minibuffer
16824 with @kbd{C-y} (@code{yank)}.
16826 @item
16827 Press @key{RET} to evaluate the @code{graph-body-print} expression.
16828 @end enumerate
16830 @need 800
16831 Emacs will print a graph like this:
16833 @smallexample
16834 @group
16835                     *
16836                 *   **
16837                 *  ****
16838                *** ****
16839               ********* *
16840              ************
16841             *************
16842 @end group
16843 @end smallexample
16845 @node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph
16846 @section The @code{recursive-graph-body-print} Function
16847 @findex recursive-graph-body-print
16849 The @code{graph-body-print} function may also be written recursively.
16850 The recursive solution is divided into two parts: an outside `wrapper'
16851 that uses a @code{let} expression to determine the values of several
16852 variables that need only be found once, such as the maximum height of
16853 the graph, and an inside function that is called recursively to print
16854 the graph.
16856 @need 1250
16857 The `wrapper' is uncomplicated:
16859 @smallexample
16860 @group
16861 (defun recursive-graph-body-print (numbers-list)
16862   "Print a bar graph of the NUMBERS-LIST.
16863 The numbers-list consists of the Y-axis values."
16864   (let ((height (apply 'max numbers-list))
16865         (symbol-width (length graph-blank))
16866         from-position)
16867     (recursive-graph-body-print-internal
16868      numbers-list
16869      height
16870      symbol-width)))
16871 @end group
16872 @end smallexample
16874 The recursive function is a little more difficult.  It has four parts:
16875 the `do-again-test', the printing code, the recursive call, and the
16876 `next-step-expression'.  The `do-again-test' is a @code{when}
16877 expression that determines whether the @code{numbers-list} contains
16878 any remaining elements; if it does, the function prints one column of
16879 the graph using the printing code and calls itself again.  The
16880 function calls itself again according to the value produced by the
16881 `next-step-expression' which causes the call to act on a shorter
16882 version of the @code{numbers-list}.
16884 @smallexample
16885 @group
16886 (defun recursive-graph-body-print-internal
16887   (numbers-list height symbol-width)
16888   "Print a bar graph.
16889 Used within recursive-graph-body-print function."
16890 @end group
16892 @group
16893   (when numbers-list
16894         (setq from-position (point))
16895         (insert-rectangle
16896          (column-of-graph height (car numbers-list)))
16897 @end group
16898 @group
16899         (goto-char from-position)
16900         (forward-char symbol-width)
16901         (sit-for 0)     ; @r{Draw graph column by column.}
16902         (recursive-graph-body-print-internal
16903          (cdr numbers-list) height symbol-width)))
16904 @end group
16905 @end smallexample
16907 @need 1250
16908 After installation, this expression can be tested; here is a sample:
16910 @smallexample
16911 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
16912 @end smallexample
16914 @need 800
16915 Here is what @code{recursive-graph-body-print} produces:
16917 @smallexample
16918 @group
16919                 *
16920                **   *
16921               ****  *
16922               **** ***
16923             * *********
16924             ************
16925             *************
16926 @end group
16927 @end smallexample
16929 Either of these two functions, @code{graph-body-print} or
16930 @code{recursive-graph-body-print}, create the body of a graph.
16932 @node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph
16933 @section Need for Printed Axes
16935 A graph needs printed axes, so you can orient yourself.  For a do-once
16936 project, it may be reasonable to draw the axes by hand using Emacs'
16937 Picture mode; but a graph drawing function may be used more than once.
16939 For this reason, I have written enhancements to the basic
16940 @code{print-graph-body} function that automatically print labels for
16941 the horizontal and vertical axes.  Since the label printing functions
16942 do not contain much new material, I have placed their description in
16943 an appendix.  @xref{Full Graph, , A Graph with Labelled Axes}.
16945 @node Line Graph Exercise,  , Printed Axes, Readying a Graph
16946 @section Exercise
16948 Write a line graph version of the graph printing functions.
16950 @node Emacs Initialization, Debugging, Readying a Graph, Top
16951 @chapter Your @file{.emacs} File
16952 @cindex @file{.emacs} file
16953 @cindex Customizing your @file{.emacs} file
16954 @cindex Initialization file
16956 ``You don't have to like Emacs to like it'' -- this seemingly
16957 paradoxical statement is the secret of GNU Emacs.  The plain, `out of
16958 the box' Emacs is a generic tool.  Most people who use it, customize
16959 it to suit themselves.
16961 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
16962 expressions in Emacs Lisp you can change or extend Emacs.
16964 @menu
16965 * Default Configuration::
16966 * Site-wide Init::              You can write site-wide init files.
16967 * defcustom::                   Emacs will write code for you.
16968 * Beginning a .emacs File::     How to write a @code{.emacs file}.
16969 * Text and Auto-fill::          Automatically wrap lines.
16970 * Mail Aliases::                Use abbreviations for email addresses.
16971 * Indent Tabs Mode::            Don't use tabs with @TeX{}
16972 * Keybindings::                 Create some personal keybindings.
16973 * Keymaps::                     More about key binding.
16974 * Loading Files::               Load (i.e., evaluate) files automatically.
16975 * Autoload::                    Make functions available.
16976 * Simple Extension::            Define a function; bind it to a key.
16977 * X11 Colors::                  Colors in X.
16978 * Miscellaneous::
16979 * Mode Line::                   How to customize your mode line.
16980 @end menu
16982 @node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
16983 @ifnottex
16984 @unnumberedsec Emacs' Default Configuration
16985 @end ifnottex
16987 There are those who appreciate Emacs' default configuration.  After
16988 all, Emacs starts you in C mode when you edit a C file, starts you in
16989 Fortran mode when you edit a Fortran file, and starts you in
16990 Fundamental mode when you edit an unadorned file.  This all makes
16991 sense, if you do not know who is going to use Emacs.  Who knows what a
16992 person hopes to do with an unadorned file?  Fundamental mode is the
16993 right default for such a file, just as C mode is the right default for
16994 editing C code.  (Enough programming languages have syntaxes
16995 that enable them to share or nearly share features, so C mode is
16996 now provided by by CC mode, the `C Collection'.)
16998 But when you do know who is going to use Emacs---you,
16999 yourself---then it makes sense to customize Emacs.
17001 For example, I seldom want Fundamental mode when I edit an
17002 otherwise undistinguished file; I want Text mode.  This is why I
17003 customize Emacs: so it suits me.
17005 You can customize and extend Emacs by writing or adapting a
17006 @file{~/.emacs} file.  This is your personal initialization file; its
17007 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
17008 may also add @file{.el} to @file{~/.emacs} and call it a
17009 @file{~/.emacs.el} file.  In the past, you were forbidden to type the
17010 extra keystrokes that the name @file{~/.emacs.el} requires, but now
17011 you may.  The new format is consistent with the Emacs Lisp file
17012 naming conventions; the old format saves typing.}
17014 A @file{~/.emacs} file contains Emacs Lisp code.  You can write this
17015 code yourself; or you can use Emacs' @code{customize} feature to write
17016 the code for you.  You can combine your own expressions and
17017 auto-written Customize expressions in your @file{.emacs} file.
17019 (I myself prefer to write my own expressions, except for those,
17020 particularly fonts, that I find easier to manipulate using the
17021 @code{customize} command.  I combine the two methods.)
17023 Most of this chapter is about writing expressions yourself.  It
17024 describes a simple @file{.emacs} file; for more information, see
17025 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
17026 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
17027 Manual}.
17029 @node Site-wide Init, defcustom, Default Configuration, Emacs Initialization
17030 @section Site-wide Initialization Files
17032 @cindex @file{default.el} init file
17033 @cindex @file{site-init.el} init file
17034 @cindex @file{site-load.el} init file
17035 In addition to your personal initialization file, Emacs automatically
17036 loads various site-wide initialization files, if they exist.  These
17037 have the same form as your @file{.emacs} file, but are loaded by
17038 everyone.
17040 Two site-wide initialization files, @file{site-load.el} and
17041 @file{site-init.el}, are loaded into Emacs and then `dumped' if a
17042 `dumped' version of Emacs is created, as is most common.  (Dumped
17043 copies of Emacs load more quickly.  However, once a file is loaded and
17044 dumped, a change to it does not lead to a change in Emacs unless you
17045 load it yourself or re-dump Emacs.  @xref{Building Emacs, , Building
17046 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
17047 @file{INSTALL} file.)
17049 Three other site-wide initialization files are loaded automatically
17050 each time you start Emacs, if they exist.  These are
17051 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
17052 file, and @file{default.el}, and the terminal type file, which are both
17053 loaded @emph{after} your @file{.emacs} file.
17055 Settings and definitions in your @file{.emacs} file will overwrite
17056 conflicting settings and definitions in a @file{site-start.el} file,
17057 if it exists; but the settings and definitions in a @file{default.el}
17058 or terminal type file will overwrite those in your @file{.emacs} file.
17059 (You can prevent interference from a terminal type file by setting
17060 @code{term-file-prefix} to @code{nil}.  @xref{Simple Extension, , A
17061 Simple Extension}.)
17063 @c Rewritten to avoid overfull hbox.
17064 The @file{INSTALL} file that comes in the distribution contains
17065 descriptions of the @file{site-init.el} and @file{site-load.el} files.
17067 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
17068 control loading.  These files are in the @file{lisp} directory of the
17069 Emacs distribution and are worth perusing.
17071 The @file{loaddefs.el} file contains a good many suggestions as to
17072 what to put into your own @file{.emacs} file, or into a site-wide
17073 initialization file.
17075 @node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization
17076 @section Specifying Variables using @code{defcustom}
17077 @findex defcustom
17079 You can specify variables using @code{defcustom} so that you and
17080 others can then use Emacs' @code{customize} feature to set their
17081 values.  (You cannot use @code{customize} to write function
17082 definitions; but you can write @code{defuns} in your @file{.emacs}
17083 file.  Indeed, you can write any Lisp expression in your @file{.emacs}
17084 file.)
17086 The @code{customize} feature depends on the @code{defcustom} special
17087 form.  Although you can use @code{defvar} or @code{setq} for variables
17088 that users set, the @code{defcustom} special form is designed for the
17089 job.
17091 You can use your knowledge of @code{defvar} for writing the
17092 first three arguments for @code{defcustom}.  The first argument to
17093 @code{defcustom} is the name of the variable.  The second argument is
17094 the variable's initial value, if any; and this value is set only if
17095 the value has not already been set.  The third argument is the
17096 documentation.
17098 The fourth and subsequent arguments to @code{defcustom} specify types
17099 and options; these are not featured in @code{defvar}.  (These
17100 arguments are optional.)
17102 Each of these arguments consists of a keyword followed by a value.
17103 Each keyword starts with the colon character @samp{:}.
17105 @need 1250
17106 For example, the customizable user option variable
17107 @code{text-mode-hook} looks like this:
17109 @smallexample
17110 @group
17111 (defcustom text-mode-hook nil
17112   "Normal hook run when entering Text mode and many related modes."
17113   :type 'hook
17114   :options '(turn-on-auto-fill flyspell-mode)
17115   :group 'data)
17116 @end group
17117 @end smallexample
17119 @noindent
17120 The name of the variable is @code{text-mode-hook}; it has no default
17121 value; and its documentation string tells you what it does.
17123 The @code{:type} keyword tells Emacs the kind of data to which
17124 @code{text-mode-hook} should be set and how to display the value in a
17125 Customization buffer.
17127 The @code{:options} keyword specifies a suggested list of values for
17128 the variable.  Usually, @code{:options} applies to a hook.
17129 The list is only a suggestion; it is not exclusive; a person who sets
17130 the variable may set it to other values; the list shown following the
17131 @code{:options} keyword is intended to offer convenient choices to a
17132 user.
17134 Finally, the @code{:group} keyword tells the Emacs Customization
17135 command in which group the variable is located.  This tells where to
17136 find it.
17138 The @code{defcustom} function recognizes more than a dozen keywords.
17139 For more information, see @ref{Customization, , Writing Customization
17140 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
17142 Consider @code{text-mode-hook} as an example.
17144 There are two ways to customize this variable.  You can use the
17145 customization command or write the appropriate expressions yourself.
17147 @need 800
17148 Using the customization command,  you can type:
17150 @smallexample
17151 M-x customize
17152 @end smallexample
17154 @noindent
17155 and find that the group for editing files of data is called `data'.
17156 Enter that group.  Text Mode Hook is the first member.  You can click
17157 on its various options, such as @code{turn-on-auto-fill}, to set the
17158 values.  After you click on the button to
17160 @smallexample
17161 Save for Future Sessions
17162 @end smallexample
17164 @noindent
17165 Emacs will write an expression into your @file{.emacs} file.
17166 It will look like this:
17168 @smallexample
17169 @group
17170 (custom-set-variables
17171   ;; custom-set-variables was added by Custom.
17172   ;; If you edit it by hand, you could mess it up, so be careful.
17173   ;; Your init file should contain only one such instance.
17174   ;; If there is more than one, they won't work right.
17175  '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
17176 @end group
17177 @end smallexample
17179 @noindent
17180 (The @code{text-mode-hook-identify} function tells
17181 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.
17182 It comes on automatically.)
17184 The @code{custom-set-variables} function works somewhat differently
17185 than a @code{setq}.  While I have never learned the differences, I
17186 modify the @code{custom-set-variables} expressions in my @file{.emacs}
17187 file by hand:  I make the changes in what appears to me to be a
17188 reasonable manner and have not had any problems.  Others prefer to use
17189 the Customization command and let Emacs do the work for them.
17191 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
17192 This function sets the various font faces.  Over time, I have set a
17193 considerable number of faces.  Some of the time, I re-set them using
17194 @code{customize}; other times, I simply edit the
17195 @code{custom-set-faces} expression in my @file{.emacs} file itself.
17197 The second way to customize your @code{text-mode-hook} is to set it
17198 yourself in your @file{.emacs} file using code that has nothing to do
17199 with the @code{custom-set-@dots{}} functions.
17201 @need 800
17202 When you do this, and later use @code{customize}, you will see a
17203 message that says
17205 @smallexample
17206 CHANGED outside Customize; operating on it here may be unreliable.
17207 @end smallexample
17209 @need 800
17210 This message is only a warning.  If you click on the button to
17212 @smallexample
17213 Save for Future Sessions
17214 @end smallexample
17216 @noindent
17217 Emacs will write a @code{custom-set-@dots{}} expression near the end
17218 of your @file{.emacs} file that will be evaluated after your
17219 hand-written expression.  It will, therefore, overrule your
17220 hand-written expression.  No harm will be done.  When you do this,
17221 however, be careful to remember which expression is active; if you
17222 forget, you may confuse yourself.
17224 So long as you remember where the values are set, you will have no
17225 trouble.  In any event, the values are always set in your
17226 initialization file, which is usually called @file{.emacs}.
17228 I myself use @code{customize} for hardly anything.  Mostly, I write
17229 expressions myself.
17231 @findex defsubst
17232 @findex defconst
17233 Incidentally, to be more complete concerning defines:  @code{defsubst}
17234 defines an inline function.  The syntax is just like that of
17235 @code{defun}.  @code{defconst} defines a symbol as a constant.  The
17236 intent is that neither programs nor users should ever change a value
17237 set by @code{defconst}.  (You can change it; the value set is a
17238 variable; but please do not.)
17240 @node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization
17241 @section Beginning a @file{.emacs} File
17242 @cindex @file{.emacs} file, beginning of
17244 When you start Emacs, it loads your @file{.emacs} file unless you tell
17245 it not to by specifying @samp{-q} on the command line.  (The
17246 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
17248 A @file{.emacs} file contains Lisp expressions.  Often, these are no
17249 more than expressions to set values; sometimes they are function
17250 definitions.
17252 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
17253 Manual}, for a short description of initialization files.
17255 This chapter goes over some of the same ground, but is a walk among
17256 extracts from a complete, long-used @file{.emacs} file---my own.
17258 The first part of the file consists of comments: reminders to myself.
17259 By now, of course, I remember these things, but when I started, I did
17260 not.
17262 @need 1200
17263 @smallexample
17264 @group
17265 ;;;; Bob's .emacs file
17266 ; Robert J. Chassell
17267 ; 26 September 1985
17268 @end group
17269 @end smallexample
17271 @noindent
17272 Look at that date!  I started this file a long time ago.  I have been
17273 adding to it ever since.
17275 @smallexample
17276 @group
17277 ; Each section in this file is introduced by a
17278 ; line beginning with four semicolons; and each
17279 ; entry is introduced by a line beginning with
17280 ; three semicolons.
17281 @end group
17282 @end smallexample
17284 @noindent
17285 This describes the usual conventions for comments in Emacs Lisp.
17286 Everything on a line that follows a semicolon is a comment.  Two,
17287 three, and four semicolons are used as subsection and section markers.
17288 (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for
17289 more about comments.)
17291 @smallexample
17292 @group
17293 ;;;; The Help Key
17294 ; Control-h is the help key;
17295 ; after typing control-h, type a letter to
17296 ; indicate the subject about which you want help.
17297 ; For an explanation of the help facility,
17298 ; type control-h two times in a row.
17299 @end group
17300 @end smallexample
17302 @noindent
17303 Just remember: type @kbd{C-h} two times for help.
17305 @smallexample
17306 @group
17307 ; To find out about any mode, type control-h m
17308 ; while in that mode.  For example, to find out
17309 ; about mail mode, enter mail mode and then type
17310 ; control-h m.
17311 @end group
17312 @end smallexample
17314 @noindent
17315 `Mode help', as I call this, is very helpful.  Usually, it tells you
17316 all you need to know.
17318 Of course, you don't need to include comments like these in your
17319 @file{.emacs} file.  I included them in mine because I kept forgetting
17320 about Mode help or the conventions for comments---but I was able to
17321 remember to look here to remind myself.
17323 @node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization
17324 @section Text and Auto Fill Mode
17326 Now we come to the part that `turns on' Text mode and
17327 Auto Fill mode.
17329 @smallexample
17330 @group
17331 ;;; Text mode and Auto Fill mode
17332 ; The next two lines put Emacs into Text mode
17333 ; and Auto Fill mode, and are for writers who
17334 ; want to start writing prose rather than code.
17335 (setq default-major-mode 'text-mode)
17336 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17337 @end group
17338 @end smallexample
17340 Here is the first part of this @file{.emacs} file that does something
17341 besides remind a forgetful human!
17343 The first of the two lines in parentheses tells Emacs to turn on Text
17344 mode when you find a file, @emph{unless} that file should go into some
17345 other mode, such as C mode.
17347 @cindex Per-buffer, local variables list
17348 @cindex Local variables list, per-buffer,
17349 @cindex Automatic mode selection
17350 @cindex Mode selection, automatic
17351 When Emacs reads a file, it looks at the extension to the file name,
17352 if any.  (The extension is the part that comes after a @samp{.}.)  If
17353 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
17354 on C mode.  Also, Emacs looks at first nonblank line of the file; if
17355 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode.  Emacs
17356 possesses a list of extensions and specifications that it uses
17357 automatically.  In addition, Emacs looks near the last page for a
17358 per-buffer, ``local variables list'', if any.
17360 @ifinfo
17361 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
17362 Emacs Manual}.
17364 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17365 Manual}.
17366 @end ifinfo
17367 @iftex
17368 See sections ``How Major Modes are Chosen'' and ``Local Variables in
17369 Files'' in @cite{The GNU Emacs Manual}.
17370 @end iftex
17372 Now, back to the @file{.emacs} file.
17374 @need 800
17375 Here is the line again; how does it work?
17377 @cindex Text Mode turned on
17378 @smallexample
17379 (setq default-major-mode 'text-mode)
17380 @end smallexample
17382 @noindent
17383 This line is a short, but complete Emacs Lisp expression.
17385 We are already familiar with @code{setq}.  It sets the following variable,
17386 @code{default-major-mode}, to the subsequent value, which is
17387 @code{text-mode}.  The single quote mark before @code{text-mode} tells
17388 Emacs to deal directly with the @code{text-mode} variable, not with
17389 whatever it might stand for.  @xref{set & setq, , Setting the Value of
17390 a Variable}, for a reminder of how @code{setq} works.  The main point
17391 is that there is no difference between the procedure you use to set
17392 a value in your @file{.emacs} file and the procedure you use anywhere
17393 else in Emacs.
17395 @need 800
17396 Here is the next line:
17398 @cindex Auto Fill mode turned on
17399 @findex add-hook
17400 @smallexample
17401 (add-hook 'text-mode-hook 'turn-on-auto-fill)
17402 @end smallexample
17404 @noindent
17405 In this line, the @code{add-hook} command adds
17406 @code{turn-on-auto-fill} to the variable.
17408 @code{turn-on-auto-fill} is the name of a program, that, you guessed
17409 it!, turns on Auto Fill mode.
17411 Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
17412 onto Text mode.  So every time Emacs turns on Text mode, Emacs also
17413 turns on Auto Fill mode.
17415 In brief, the first line causes Emacs to enter Text mode when you edit a
17416 file, unless the file name extension, a first non-blank line, or local
17417 variables to tell Emacs otherwise.
17419 Text mode among other actions, sets the syntax table to work
17420 conveniently for writers.  In Text mode, Emacs considers an apostrophe
17421 as part of a word like a letter; but Emacs does not consider a period
17422 or a space as part of a word.  Thus, @kbd{M-f} moves you over
17423 @samp{it's}.  On the other hand, in C mode, @kbd{M-f} stops just after
17424 the @samp{t} of @samp{it's}.
17426 The second line causes Emacs to turn on Auto Fill mode when it turns
17427 on Text mode.  In Auto Fill mode, Emacs automatically breaks a line
17428 that is too wide and brings the excessively wide part of the line down
17429 to the next line.  Emacs breaks lines between words, not within them.
17431 When Auto Fill mode is turned off, lines continue to the right as you
17432 type them.  Depending on how you set the value of
17433 @code{truncate-lines}, the words you type either disappear off the
17434 right side of the screen, or else are shown, in a rather ugly and
17435 unreadable manner, as a continuation line on the screen.
17437 @need 1250
17438 In addition, in this part of my @file{.emacs} file, I tell the Emacs
17439 fill commands to insert two spaces after a colon:
17441 @smallexample
17442 (setq colon-double-space t)
17443 @end smallexample
17445 @node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization
17446 @section Mail Aliases
17448 Here is a @code{setq} that `turns on' mail aliases, along with more
17449 reminders.
17451 @smallexample
17452 @group
17453 ;;; Mail mode
17454 ; To enter mail mode, type `C-x m'
17455 ; To enter RMAIL (for reading mail),
17456 ; type `M-x rmail'
17457 (setq mail-aliases t)
17458 @end group
17459 @end smallexample
17461 @cindex Mail aliases
17462 @noindent
17463 This @code{setq} command sets the value of the variable
17464 @code{mail-aliases} to @code{t}.  Since @code{t} means true, the line
17465 says, in effect, ``Yes, use mail aliases.''
17467 Mail aliases are convenient short names for long email addresses or
17468 for lists of email addresses.  The file where you keep your `aliases'
17469 is @file{~/.mailrc}.  You write an alias like this:
17471 @smallexample
17472 alias geo george@@foobar.wiz.edu
17473 @end smallexample
17475 @noindent
17476 When you write a message to George, address it to @samp{geo}; the
17477 mailer will automatically expand @samp{geo} to the full address.
17479 @node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization
17480 @section Indent Tabs Mode
17481 @cindex Tabs, preventing
17482 @findex indent-tabs-mode
17484 By default, Emacs inserts tabs in place of multiple spaces when it
17485 formats a region.  (For example, you might indent many lines of text
17486 all at once with the @code{indent-region} command.)  Tabs look fine on
17487 a terminal or with ordinary printing, but they produce badly indented
17488 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
17490 @need 1250
17491 The following turns off Indent Tabs mode:
17493 @smallexample
17494 @group
17495 ;;; Prevent Extraneous Tabs
17496 (setq-default indent-tabs-mode nil)
17497 @end group
17498 @end smallexample
17500 Note that this line uses @code{setq-default} rather than the
17501 @code{setq} command that we have seen before.  The @code{setq-default}
17502 command sets values only in buffers that do not have their own local
17503 values for the variable.
17505 @ifinfo
17506 @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}.
17508 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
17509 Manual}.
17510 @end ifinfo
17511 @iftex
17512 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
17513 Files'' in @cite{The GNU Emacs Manual}.
17514 @end iftex
17516 @need 1700
17517 @node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization
17518 @section Some Keybindings
17520 Now for some personal keybindings:
17522 @smallexample
17523 @group
17524 ;;; Compare windows
17525 (global-set-key "\C-cw" 'compare-windows)
17526 @end group
17527 @end smallexample
17529 @findex compare-windows
17530 @code{compare-windows} is a nifty command that compares the text in
17531 your current window with text in the next window.  It makes the
17532 comparison by starting at point in each window, moving over text in
17533 each window as far as they match.  I use this command all the time.
17535 This also shows how to set a key globally, for all modes.
17537 @cindex Setting a key globally
17538 @cindex Global set key
17539 @cindex Key setting globally
17540 @findex global-set-key
17541 The command is @code{global-set-key}.  It is followed by the
17542 keybinding.  In a @file{.emacs} file, the keybinding is written as
17543 shown: @code{\C-c} stands for `control-c', which means `press the
17544 control key and the @key{c} key at the same time'.  The @code{w} means
17545 `press the @key{w} key'.  The keybinding is surrounded by double
17546 quotation marks.  In documentation, you would write this as
17547 @w{@kbd{C-c w}}.  (If you were binding a @key{META} key, such as
17548 @kbd{M-c}, rather than a @key{CTRL} key, you would write
17549 @w{@code{\M-c}} in your @file{.emacs} file.  @xref{Init Rebinding, ,
17550 Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
17551 details.)
17553 The command invoked by the keys is @code{compare-windows}.  Note that
17554 @code{compare-windows} is preceded by a single quote; otherwise, Emacs
17555 would first try to evaluate the symbol to determine its value.
17557 These three things, the double quotation marks, the backslash before
17558 the @samp{C}, and the single quote mark are necessary parts of
17559 keybinding that I tend to forget.  Fortunately, I have come to
17560 remember that I should look at my existing @file{.emacs} file, and
17561 adapt what is there.
17563 As for the keybinding itself: @kbd{C-c w}.  This combines the prefix
17564 key, @kbd{C-c}, with a single character, in this case, @kbd{w}.  This
17565 set of keys, @kbd{C-c} followed by a single character, is strictly
17566 reserved for individuals' own use.  (I call these `own' keys, since
17567 these are for my own use.)  You should always be able to create such a
17568 keybinding for your own use without stomping on someone else's
17569 keybinding.  If you ever write an extension to Emacs, please avoid
17570 taking any of these keys for public use.  Create a key like @kbd{C-c
17571 C-w} instead.  Otherwise, we will run out of `own' keys.
17573 @need 1250
17574 Here is another keybinding, with a comment:
17576 @smallexample
17577 @group
17578 ;;; Keybinding for `occur'
17579 ; I use occur a lot, so let's bind it to a key:
17580 (global-set-key "\C-co" 'occur)
17581 @end group
17582 @end smallexample
17584 @findex occur
17585 The @code{occur} command shows all the lines in the current buffer
17586 that contain a match for a regular expression.  Matching lines are
17587 shown in a buffer called @file{*Occur*}.  That buffer serves as a menu
17588 to jump to occurrences.
17590 @findex global-unset-key
17591 @cindex Unbinding key
17592 @cindex Key unbinding
17593 @need 1250
17594 Here is how to unbind a key, so it does not
17595 work:
17597 @smallexample
17598 @group
17599 ;;; Unbind `C-x f'
17600 (global-unset-key "\C-xf")
17601 @end group
17602 @end smallexample
17604 There is a reason for this unbinding: I found I inadvertently typed
17605 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}.  Rather than find a
17606 file, as I intended, I accidentally set the width for filled text,
17607 almost always to a width I did not want.  Since I hardly ever reset my
17608 default width, I simply unbound the key.
17610 @findex list-buffers, @r{rebound}
17611 @findex buffer-menu, @r{bound to key}
17612 @need 1250
17613 The following rebinds an existing key:
17615 @smallexample
17616 @group
17617 ;;; Rebind `C-x C-b' for `buffer-menu'
17618 (global-set-key "\C-x\C-b" 'buffer-menu)
17619 @end group
17620 @end smallexample
17622 By default, @kbd{C-x C-b} runs the
17623 @code{list-buffers} command.  This command lists
17624 your buffers in @emph{another} window.  Since I
17625 almost always want to do something in that
17626 window, I prefer the  @code{buffer-menu}
17627 command, which not only lists the buffers,
17628 but moves point into that window.
17630 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
17631 @section Keymaps
17632 @cindex Keymaps
17633 @cindex Rebinding keys
17635 Emacs uses @dfn{keymaps} to record which keys call which commands.
17636 When you use @code{global-set-key} to set the keybinding for a single
17637 command in all parts of Emacs, you are specifying the keybinding in
17638 @code{current-global-map}.
17640 Specific modes, such as C mode or Text mode, have their own keymaps;
17641 the mode-specific keymaps override the global map that is shared by
17642 all buffers.
17644 The @code{global-set-key} function binds, or rebinds, the global
17645 keymap.  For example, the following binds the key @kbd{C-x C-b} to the
17646 function @code{buffer-menu}:
17648 @smallexample
17649 (global-set-key "\C-x\C-b" 'buffer-menu)
17650 @end smallexample
17652 Mode-specific keymaps are bound using the @code{define-key} function,
17653 which takes a specific keymap as an argument, as well as the key and
17654 the command.  For example, my @file{.emacs} file contains the
17655 following expression to bind the @code{texinfo-insert-@@group} command
17656 to @kbd{C-c C-c g}:
17658 @smallexample
17659 @group
17660 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
17661 @end group
17662 @end smallexample
17664 @noindent
17665 The @code{texinfo-insert-@@group} function itself is a little extension
17666 to Texinfo mode that inserts @samp{@@group} into a Texinfo file.  I
17667 use this command all the time and prefer to type the three strokes
17668 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
17669 (@samp{@@group} and its matching @samp{@@end group} are commands that
17670 keep all enclosed text together on one page; many multi-line examples
17671 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
17673 @need 1250
17674 Here is the @code{texinfo-insert-@@group} function definition:
17676 @smallexample
17677 @group
17678 (defun texinfo-insert-@@group ()
17679   "Insert the string @@group in a Texinfo buffer."
17680   (interactive)
17681   (beginning-of-line)
17682   (insert "@@group\n"))
17683 @end group
17684 @end smallexample
17686 (Of course, I could have used Abbrev mode to save typing, rather than
17687 write a function to insert a word; but I prefer key strokes consistent
17688 with other Texinfo mode key bindings.)
17690 You will see numerous @code{define-key} expressions in
17691 @file{loaddefs.el} as well as in the various mode libraries, such as
17692 @file{cc-mode.el} and @file{lisp-mode.el}.
17694 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
17695 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
17696 Reference Manual}, for more information about keymaps.
17698 @node Loading Files, Autoload, Keymaps, Emacs Initialization
17699 @section Loading Files
17700 @cindex Loading files
17701 @c findex load
17703 Many people in the GNU Emacs community have written extensions to
17704 Emacs.  As time goes by, these extensions are often included in new
17705 releases.  For example, the Calendar and Diary packages are now part
17706 of the standard GNU Emacs, as is Calc.
17708 You can use a @code{load} command to evaluate a complete file and
17709 thereby install all the functions and variables in the file into Emacs.
17710 For example:
17712 @c (auto-compression-mode t)
17714 @smallexample
17715 (load "~/emacs/slowsplit")
17716 @end smallexample
17718 This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it
17719 exists, the faster, byte compiled @file{slowsplit.elc} file from the
17720 @file{emacs} sub-directory of your home directory.  The file contains
17721 the function @code{split-window-quietly}, which John Robinson wrote in
17722 1989.
17724 The @code{split-window-quietly} function splits a window with the
17725 minimum of redisplay.  I installed it in 1989 because it worked well
17726 with the slow 1200 baud terminals I was then using.  Nowadays, I only
17727 occasionally come across such a slow connection, but I continue to use
17728 the function because I like the way it leaves the bottom half of a
17729 buffer in the lower of the new windows and the top half in the upper
17730 window.
17732 @need 1250
17733 To replace the key binding for the default
17734 @code{split-window-vertically}, you must also unset that key and bind
17735 the keys to @code{split-window-quietly}, like this:
17737 @smallexample
17738 @group
17739 (global-unset-key "\C-x2")
17740 (global-set-key "\C-x2" 'split-window-quietly)
17741 @end group
17742 @end smallexample
17744 @vindex load-path
17745 If you load many extensions, as I do, then instead of specifying the
17746 exact location of the extension file, as shown above, you can specify
17747 that directory as part of Emacs' @code{load-path}.  Then, when Emacs
17748 loads a file, it will search that directory as well as its default
17749 list of directories.  (The default list is specified in @file{paths.h}
17750 when Emacs is built.)
17752 @need 1250
17753 The following command adds your @file{~/emacs} directory to the
17754 existing load path:
17756 @smallexample
17757 @group
17758 ;;; Emacs Load Path
17759 (setq load-path (cons "~/emacs" load-path))
17760 @end group
17761 @end smallexample
17763 Incidentally, @code{load-library} is an interactive interface to the
17764 @code{load} function.  The complete function looks like this:
17766 @findex load-library
17767 @smallexample
17768 @group
17769 (defun load-library (library)
17770   "Load the library named LIBRARY.
17771 This is an interface to the function `load'."
17772   (interactive
17773    (list (completing-read "Load library: "
17774                           'locate-file-completion
17775                           (cons load-path (get-load-suffixes)))))
17776   (load library))
17777 @end group
17778 @end smallexample
17780 The name of the function, @code{load-library}, comes from the use of
17781 `library' as a conventional synonym for `file'.  The source for the
17782 @code{load-library} command is in the @file{files.el} library.
17784 Another interactive command that does a slightly different job is
17785 @code{load-file}.  @xref{Lisp Libraries, , Libraries of Lisp Code for
17786 Emacs, emacs, The GNU Emacs Manual}, for information on the
17787 distinction between @code{load-library} and this command.
17789 @node Autoload, Simple Extension, Loading Files, Emacs Initialization
17790 @section Autoloading
17791 @findex autoload
17793 Instead of installing a function by loading the file that contains it,
17794 or by evaluating the function definition, you can make the function
17795 available but not actually install it until it is first called.  This
17796 is called @dfn{autoloading}.
17798 When you execute an autoloaded function, Emacs automatically evaluates
17799 the file that contains the definition, and then calls the function.
17801 Emacs starts quicker with autoloaded functions, since their libraries
17802 are not loaded right away; but you need to wait a moment when you
17803 first use such a function, while its containing file is evaluated.
17805 Rarely used functions are frequently autoloaded.  The
17806 @file{loaddefs.el} library contains hundreds of autoloaded functions,
17807 from @code{bookmark-set} to @code{wordstar-mode}.  Of course, you may
17808 come to use a `rare' function frequently.  When you do, you should
17809 load that function's file with a @code{load} expression in your
17810 @file{.emacs} file.
17812 In my @file{.emacs} file, I load 14 libraries that contain functions
17813 that would otherwise be autoloaded.  (Actually, it would have been
17814 better to include these files in my `dumped' Emacs, but I forgot.
17815 @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
17816 Reference Manual}, and the @file{INSTALL} file for more about
17817 dumping.)
17819 You may also want to include autoloaded expressions in your @file{.emacs}
17820 file.  @code{autoload} is a built-in function that takes up to five
17821 arguments, the final three of which are optional.  The first argument
17822 is the name of the function to be autoloaded; the second is the name
17823 of the file to be loaded.  The third argument is documentation for the
17824 function, and the fourth tells whether the function can be called
17825 interactively.  The fifth argument tells what type of
17826 object---@code{autoload} can handle a keymap or macro as well as a
17827 function (the default is a function).
17829 @need 800
17830 Here is a typical example:
17832 @smallexample
17833 @group
17834 (autoload 'html-helper-mode
17835   "html-helper-mode" "Edit HTML documents" t)
17836 @end group
17837 @end smallexample
17839 @noindent
17840 (@code{html-helper-mode} is an older alternative to @code{html-mode},
17841 which is a standard part of the distribution.)
17843 @noindent
17844 This expression autoloads the @code{html-helper-mode} function.  It
17845 takes it from the @file{html-helper-mode.el} file (or from the byte
17846 compiled file @file{html-helper-mode.elc}, if it exists.)  The file
17847 must be located in a directory specified by @code{load-path}.  The
17848 documentation says that this is a mode to help you edit documents
17849 written in the HyperText Markup Language.  You can call this mode
17850 interactively by typing @kbd{M-x html-helper-mode}.  (You need to
17851 duplicate the function's regular documentation in the autoload
17852 expression because the regular function is not yet loaded, so its
17853 documentation is not available.)
17855 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
17856 Manual}, for more information.
17858 @node Simple Extension, X11 Colors, Autoload, Emacs Initialization
17859 @section A Simple Extension: @code{line-to-top-of-window}
17860 @findex line-to-top-of-window
17861 @cindex Simple extension in @file{.emacs} file
17863 Here is a simple extension to Emacs that moves the line point is on to
17864 the top of the window.  I use this all the time, to make text easier
17865 to read.
17867 You can put the following code into a separate file and then load it
17868 from your @file{.emacs} file, or you can include it within your
17869 @file{.emacs} file.
17871 @need 1250
17872 Here is the definition:
17874 @smallexample
17875 @group
17876 ;;; Line to top of window;
17877 ;;; replace three keystroke sequence  C-u 0 C-l
17878 (defun line-to-top-of-window ()
17879   "Move the line point is on to top of window."
17880   (interactive)
17881   (recenter 0))
17882 @end group
17883 @end smallexample
17885 @need 1250
17886 Now for the keybinding.
17888 Nowadays, function keys as well as mouse button events and
17889 non-@sc{ascii} characters are written within square brackets, without
17890 quotation marks.  (In Emacs version 18 and before, you had to write
17891 different function key bindings for each different make of terminal.)
17893 I bind @code{line-to-top-of-window} to my @key{F6} function key like
17894 this:
17896 @smallexample
17897 (global-set-key [f6] 'line-to-top-of-window)
17898 @end smallexample
17900 For more information, see @ref{Init Rebinding, , Rebinding Keys in
17901 Your Init File, emacs, The GNU Emacs Manual}.
17903 @cindex Conditional 'twixt two versions of Emacs
17904 @cindex Version of Emacs, choosing
17905 @cindex Emacs version, choosing
17906 If you run two versions of GNU Emacs, such as versions 21 and 22, and
17907 use one @file{.emacs} file, you can select which code to evaluate with
17908 the following conditional:
17910 @smallexample
17911 @group
17912 (cond
17913  (= 21 emacs-major-version)
17914   ;; evaluate version 21 code
17915   ( @dots{} ))
17916  (= 22 emacs-major-version)
17917   ;; evaluate version 22 code
17918   ( @dots{} )))
17919 @end group
17920 @end smallexample
17922 For example, in contrast to version 20, more recent versions blink
17923 their cursors by default.  I hate such blinking, as well as other
17924 features, so I placed the following in my @file{.emacs}
17925 file@footnote{When I start instances of Emacs that do not load my
17926 @file{.emacs} file or any site file, I also turn off blinking:
17928 @smallexample
17929 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
17931 @exdent Or nowadays, using an even more sophisticated set of options,
17933 emacs -Q - D
17934 @end smallexample
17937 @smallexample
17938 @group
17939 (when (or (= 21 emacs-major-version)
17940           (= 22 emacs-major-version))
17941       (blink-cursor-mode 0)
17942       ;; Insert newline when you press `C-n' (next-line)
17943       ;; at the end of the buffer
17944       (setq next-line-add-newlines t)
17945 @end group
17946 @group
17947       ;; Turn on image viewing
17948       (auto-image-file-mode t)
17949 @end group
17950 @group
17951       ;; Turn on menu bar (this bar has text)
17952       ;; (Use numeric argument to turn on)
17953       (menu-bar-mode 1)
17954 @end group
17955 @group
17956       ;; Turn off tool bar (this bar has icons)
17957       ;; (Use numeric argument to turn on)
17958       (tool-bar-mode nil)
17959 @end group
17960 @group
17961       ;; Turn off tooltip mode for tool bar
17962       ;; (This mode causes icon explanations to pop up)
17963       ;; (Use numeric argument to turn on)
17964       (tooltip-mode nil)
17965       ;; If tooltips turned on, make tips appear promptly
17966       (setq tooltip-delay 0.1)  ; default is 0.7 second
17967        )
17968 @end group
17969 @end smallexample
17971 @need 1250
17972 Alternatively, since @code{blink-cursor-mode} has existed since Emacs
17973 version 21 and is likely to continue, you could write
17975 @smallexample
17976 @group
17977 (when (>= emacs-major-version 21)
17978   (blink-cursor-mode 0)
17979 @end group
17980 @end smallexample
17982 @noindent
17983 and add other expressions, too. 
17986 @node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
17987 @section X11 Colors
17989 You can specify colors when you use Emacs with the MIT X Windowing
17990 system.
17992 I dislike the default colors and specify my own.
17994 @need 1250
17995 Here are the expressions in my @file{.emacs}
17996 file that set values:
17998 @smallexample
17999 @group
18000 ;; Set cursor color
18001 (set-cursor-color "white")
18003 ;; Set mouse color
18004 (set-mouse-color "white")
18006 ;; Set foreground and background
18007 (set-foreground-color "white")
18008 (set-background-color "darkblue")
18009 @end group
18011 @group
18012 ;;; Set highlighting colors for isearch and drag
18013 (set-face-foreground 'highlight "white")
18014 (set-face-background 'highlight "blue")
18015 @end group
18017 @group
18018 (set-face-foreground 'region "cyan")
18019 (set-face-background 'region "blue")
18020 @end group
18022 @group
18023 (set-face-foreground 'secondary-selection "skyblue")
18024 (set-face-background 'secondary-selection "darkblue")
18025 @end group
18027 @group
18028 ;; Set calendar highlighting colors
18029 (setq calendar-load-hook
18030       '(lambda ()
18031          (set-face-foreground 'diary-face   "skyblue")
18032          (set-face-background 'holiday-face "slate blue")
18033          (set-face-foreground 'holiday-face "white")))
18034 @end group
18035 @end smallexample
18037 The various shades of blue soothe my eye and prevent me from seeing
18038 the screen flicker.
18040 Alternatively, I could have set my specifications in various X
18041 initialization files.  For example, I could set the foreground,
18042 background, cursor, and pointer (i.e., mouse) colors in my
18043 @file{~/.Xresources} file like this:
18045 @smallexample
18046 @group
18047 Emacs*foreground:   white
18048 Emacs*background:   darkblue
18049 Emacs*cursorColor:  white
18050 Emacs*pointerColor: white
18051 @end group
18052 @end smallexample
18054 In any event, since it is not part of Emacs, I set the root color of
18055 my X window in my @file{~/.xinitrc} file, like this@footnote{I also
18056 run more modern window managers, such as Enlightenment, Gnome, or KDE;
18057 in those cases, I often specify an image rather than a plain color.}:
18059 @smallexample
18060 xsetroot -solid Navy -fg white &
18061 @end smallexample
18063 @need 1700
18064 @node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
18065 @section Miscellaneous Settings for a @file{.emacs} File
18067 @need 1250
18068 Here are a few miscellaneous settings:
18069 @sp 1
18071 @itemize @minus
18072 @item
18073 Set the shape and color of the mouse cursor:
18075 @smallexample
18076 @group
18077 ; Cursor shapes are defined in
18078 ; `/usr/include/X11/cursorfont.h';
18079 ; for example, the `target' cursor is number 128;
18080 ; the `top_left_arrow' cursor is number 132.
18081 @end group
18083 @group
18084 (let ((mpointer (x-get-resource "*mpointer"
18085                                 "*emacs*mpointer")))
18086   ;; If you have not set your mouse pointer
18087   ;;     then set it, otherwise leave as is:
18088   (if (eq mpointer nil)
18089       (setq mpointer "132")) ; top_left_arrow
18090 @end group
18091 @group
18092   (setq x-pointer-shape (string-to-int mpointer))
18093   (set-mouse-color "white"))
18094 @end group
18095 @end smallexample
18097 @item
18098 Or you can set the values of a variety of features in an alist, like
18099 this:
18101 @smallexample
18102 @group
18103 (setq-default
18104  default-frame-alist
18105  '((cursor-color . "white")
18106    (mouse-color . "white")
18107    (foreground-color . "white")
18108    (background-color . "DodgerBlue4")
18109    ;; (cursor-type . bar)
18110    (cursor-type . box)
18111 @end group
18112 @group
18113    (tool-bar-lines . 0)
18114    (menu-bar-lines . 1)
18115    (width . 80)
18116    (height . 58)
18117    (font .
18118          "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
18119    ))
18120 @end group
18121 @end smallexample
18123 @item
18124 Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL}
18125 into @kbd{@key{CTRL}-h}.@*
18126 (Some older keyboards needed this, although I have not seen the
18127 problem recently.)
18129 @smallexample
18130 @group
18131 ;; Translate `C-h' to <DEL>.
18132 ; (keyboard-translate ?\C-h ?\C-?)
18134 ;; Translate <DEL> to `C-h'.
18135 (keyboard-translate ?\C-? ?\C-h)
18136 @end group
18137 @end smallexample
18139 @item Turn off a blinking cursor!
18141 @smallexample
18142 @group
18143 (if (fboundp 'blink-cursor-mode)
18144     (blink-cursor-mode -1))
18145 @end group
18146 @end smallexample
18148 @noindent
18149 or start GNU Emacs with the command @code{emacs -nbc}.
18151 @need 1250
18152 @item When using `grep'@*
18153 @samp{-i}@w{  }   Ignore case distinctions@*
18154 @samp{-n}@w{  }   Prefix each line of output with line number@*
18155 @samp{-H}@w{  }   Print the filename for each match.@*
18156 @samp{-e}@w{  }   Protect patterns beginning with a hyphen character, @samp{-}
18158 @smallexample
18159 (setq grep-command "grep -i -nH -e ")
18160 @end smallexample
18162 @ignore
18163 @c Evidently, no longer needed in GNU Emacs 22
18165 item Automatically uncompress compressed files when visiting them
18167 smallexample
18168 (load "uncompress")
18169 end smallexample
18171 @end ignore
18173 @item Find an existing buffer, even if it has a different name@*
18174 This avoids problems with symbolic links.
18176 @smallexample
18177 (setq find-file-existing-other-name t)
18178 @end smallexample
18180 @item Set your language environment and default input method
18182 @smallexample
18183 @group
18184 (set-language-environment "latin-1")
18185 ;; Remember you can enable or disable multilingual text input
18186 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
18187 (setq default-input-method "latin-1-prefix")
18188 @end group
18189 @end smallexample
18191 If you want to write with Chinese `GB' characters, set this instead:
18193 @smallexample
18194 @group
18195 (set-language-environment "Chinese-GB")
18196 (setq default-input-method "chinese-tonepy")
18197 @end group
18198 @end smallexample
18199 @end itemize
18201 @subsubheading Fixing Unpleasant Key Bindings
18202 @cindex Key bindings, fixing
18203 @cindex Bindings, key, fixing unpleasant
18205 Some systems bind keys unpleasantly.  Sometimes, for example, the
18206 @key{CTRL} key appears in an awkward spot rather than at the far left
18207 of the home row.
18209 Usually, when people fix these sorts of keybindings, they do not
18210 change their @file{~/.emacs} file.  Instead, they bind the proper keys
18211 on their consoles with the @code{loadkeys} or @code{install-keymap}
18212 commands in their boot script and then include @code{xmodmap} commands
18213 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
18215 @need 1250
18216 @noindent
18217 For a boot script:
18219 @smallexample
18220 @group
18221 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
18222 @exdent or
18223 install-keymap emacs2
18224 @end group
18225 @end smallexample
18227 @need 1250
18228 @noindent
18229 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
18230 Lock} key is at the far left of the home row:
18232 @smallexample
18233 @group
18234 # Bind the key labeled `Caps Lock' to `Control'
18235 # (Such a broken user interface suggests that keyboard manufacturers
18236 # think that computers are typewriters from 1885.)
18238 xmodmap -e "clear Lock"
18239 xmodmap -e "add Control = Caps_Lock"
18240 @end group
18241 @end smallexample
18243 @need 1250
18244 @noindent
18245 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
18246 key to a @key{META} key:
18248 @smallexample
18249 @group
18250 # Some ill designed keyboards have a key labeled ALT and no Meta
18251 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
18252 @end group
18253 @end smallexample
18255 @need 1700
18256 @node Mode Line,  , Miscellaneous, Emacs Initialization
18257 @section A Modified Mode Line
18258 @vindex default-mode-line-format
18259 @cindex Mode line format
18261 Finally, a feature I really like: a modified mode line.
18263 When I work over a network, I forget which machine I am using.  Also,
18264 I tend to I lose track of where I am, and which line point is on.
18266 So I reset my mode line to look like this:
18268 @smallexample
18269 -:-- foo.texi   rattlesnake:/home/bob/  Line 1  (Texinfo Fill) Top
18270 @end smallexample
18272 I am visiting a file called @file{foo.texi}, on my machine
18273 @file{rattlesnake} in my @file{/home/bob} buffer.  I am on line 1, in
18274 Texinfo mode, and am at the top of the buffer.
18276 @need 1200
18277 My @file{.emacs} file has a section that looks like this:
18279 @smallexample
18280 @group
18281 ;; Set a Mode Line that tells me which machine, which directory,
18282 ;; and which line I am on, plus the other customary information.
18283 (setq default-mode-line-format
18284  (quote
18285   (#("-" 0 1
18286      (help-echo
18287       "mouse-1: select window, mouse-2: delete others ..."))
18288    mode-line-mule-info
18289    mode-line-modified
18290    mode-line-frame-identification
18291    "    "
18292 @end group
18293 @group
18294    mode-line-buffer-identification
18295    "    "
18296    (:eval (substring
18297            (system-name) 0 (string-match "\\..+" (system-name))))
18298    ":"
18299    default-directory
18300    #(" " 0 1
18301      (help-echo
18302       "mouse-1: select window, mouse-2: delete others ..."))
18303    (line-number-mode " Line %l ")
18304    global-mode-string
18305 @end group
18306 @group
18307    #("   %[(" 0 6
18308      (help-echo
18309       "mouse-1: select window, mouse-2: delete others ..."))
18310    (:eval (mode-line-mode-name))
18311    mode-line-process
18312    minor-mode-alist
18313    #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
18314    ")%] "
18315    (-3 . "%P")
18316    ;;   "-%-"
18317    )))
18318 @end group
18319 @end smallexample
18321 @noindent
18322 Here, I redefine the default mode line.  Most of the parts are from
18323 the original; but I make a few changes.  I set the @emph{default} mode
18324 line format so as to permit various modes, such as Info, to override
18327 Many elements in the list are self-explanatory:
18328 @code{mode-line-modified} is a variable that tells whether the buffer
18329 has been modified, @code{mode-name} tells the name of the mode, and so
18330 on.  However, the format looks complicated because of two features we
18331 have not discussed.
18333 @cindex Properties, in mode line example
18334 The first string in the mode line is a dash or hyphen, @samp{-}.  In
18335 the old days, it would have been specified simply as @code{"-"}.  But
18336 nowadays, Emacs can add properties to a string, such as highlighting
18337 or, as in this case, a help feature.  If you place your mouse cursor
18338 over the hyphen, some help information appears (By default, you must
18339 wait seven-tenths of a second before the information appears.  You can
18340 change that timing by changing the value of @code{tooltip-delay}.)
18342 @need 1000
18343 The new string format has a special syntax:
18345 @smallexample
18346 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
18347 @end smallexample
18349 @noindent
18350 The @code{#(} begins a list.  The first element of the list is the
18351 string itself, just one @samp{-}.  The second and third
18352 elements specify the range over which the fourth element applies.  A
18353 range starts @emph{after} a character, so a zero means the range
18354 starts just before the first character; a 1 means that the range ends
18355 just after the first character.  The third element is the property for
18356 the range.  It consists of a property list,  a
18357 property name, in this case, @samp{help-echo}, followed by a value, in this
18358 case, a string.  The second, third, and fourth elements of this new
18359 string format can be repeated.
18361 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
18362 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
18363 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
18365 @code{mode-line-buffer-identification}
18366 displays the current buffer name.  It is a list
18367 beginning @code{(#("%12b" 0 4 @dots{}}.
18368 The @code{#(} begins the list.
18370 The @samp{"%12b"} displays the current buffer name, using the
18371 @code{buffer-name} function with which we are familiar; the `12'
18372 specifies the maximum number of characters that will be displayed.
18373 When a name has fewer characters, whitespace is added to fill out to
18374 this number.  (Buffer names can and often should be longer than 12
18375 characters; this length works well in a typical 80 column wide
18376 window.)
18378 @code{:eval} says to evaluate the following form and use the result as
18379 a string to display.  In this case, the expression displays the first
18380 component of the full system name.  The end of the first component is
18381 a @samp{.} (`period'), so I use the @code{string-match} function to
18382 tell me the length of the first component.  The substring from the
18383 zeroth character to that length is the name of the machine.
18385 @need 1250
18386 This is the expression:
18388 @smallexample
18389 @group
18390 (:eval (substring
18391         (system-name) 0 (string-match "\\..+" (system-name))))
18392 @end group
18393 @end smallexample
18395 @samp{%[} and @samp{%]} cause a pair of square brackets
18396 to appear for each recursive editing level.  @samp{%n} says `Narrow'
18397 when narrowing is in effect.  @samp{%P} tells you the percentage of
18398 the buffer that is above the bottom of the window, or `Top', `Bottom',
18399 or `All'.  (A lower case @samp{p} tell you the percentage above the
18400 @emph{top} of the window.)  @samp{%-} inserts enough dashes to fill
18401 out the line.
18403 Remember, ``You don't have to like Emacs to like it'' --- your own
18404 Emacs can have different colors, different commands, and different
18405 keys than a default Emacs.
18407 On the other hand, if you want to bring up a plain `out of the box'
18408 Emacs, with no customization, type:
18410 @smallexample
18411 emacs -q
18412 @end smallexample
18414 @noindent
18415 This will start an Emacs that does @emph{not} load your
18416 @file{~/.emacs} initialization file.  A plain, default Emacs.  Nothing
18417 more.
18419 @node Debugging, Conclusion, Emacs Initialization, Top
18420 @chapter Debugging
18421 @cindex debugging
18423 GNU Emacs has two debuggers, @code{debug} and @code{edebug}.  The
18424 first is built into the internals of Emacs and is always with you;
18425 the second requires that you instrument a function before you can use it.
18427 Both debuggers are described extensively in @ref{Debugging, ,
18428 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
18429 In this chapter, I will walk through a short example of each.
18431 @menu
18432 * debug::                       How to use the built-in debugger.
18433 * debug-on-entry::              Start debugging when you call a function.
18434 * debug-on-quit::               Start debugging when you quit with @kbd{C-g}.
18435 * edebug::                      How to use Edebug, a source level debugger.
18436 * Debugging Exercises::
18437 @end menu
18439 @node debug, debug-on-entry, Debugging, Debugging
18440 @section @code{debug}
18441 @findex debug
18443 Suppose you have written a function definition that is intended to
18444 return the sum of the numbers 1 through a given number.  (This is the
18445 @code{triangle} function discussed earlier.  @xref{Decrementing
18446 Example, , Example with Decrementing Counter}, for a discussion.)
18447 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
18449 However, your function definition has a bug.  You have mistyped
18450 @samp{1=} for @samp{1-}.  Here is the broken definition:
18452 @findex triangle-bugged
18453 @smallexample
18454 @group
18455 (defun triangle-bugged (number)
18456   "Return sum of numbers 1 through NUMBER inclusive."
18457   (let ((total 0))
18458     (while (> number 0)
18459       (setq total (+ total number))
18460       (setq number (1= number)))      ; @r{Error here.}
18461     total))
18462 @end group
18463 @end smallexample
18465 If you are reading this in Info, you can evaluate this definition in
18466 the normal fashion.  You will see @code{triangle-bugged} appear in the
18467 echo area.
18469 @need 1250
18470 Now evaluate the @code{triangle-bugged} function with an
18471 argument of 4:
18473 @smallexample
18474 (triangle-bugged 4)
18475 @end smallexample
18477 @noindent
18478 In a recent GNU Emacs, you will create and enter a @file{*Backtrace*}
18479 buffer that says:
18481 @noindent
18482 @smallexample
18483 @group
18484 ---------- Buffer: *Backtrace* ----------
18485 Debugger entered--Lisp error: (void-function 1=)
18486   (1= number)
18487   (setq number (1= number))
18488   (while (> number 0) (setq total (+ total number))
18489         (setq number (1= number)))
18490   (let ((total 0)) (while (> number 0) (setq total ...)
18491     (setq number ...)) total)
18492   triangle-bugged(4)
18493 @end group
18494 @group
18495   eval((triangle-bugged 4))
18496   eval-last-sexp-1(nil)
18497   eval-last-sexp(nil)
18498   call-interactively(eval-last-sexp)
18499 ---------- Buffer: *Backtrace* ----------
18500 @end group
18501 @end smallexample
18503 @noindent
18504 (I have reformatted this example slightly; the debugger does not fold
18505 long lines.  As usual, you can quit the debugger by typing @kbd{q} in
18506 the @file{*Backtrace*} buffer.)
18508 In practice, for a bug as simple as this, the `Lisp error' line will
18509 tell you what you need to know to correct the definition.  The
18510 function @code{1=} is `void'.
18512 @ignore
18513 @need 800
18514 In GNU Emacs 20 and before, you will see:
18516 @smallexample
18517 Symbol's function definition is void:@: 1=
18518 @end smallexample
18520 @noindent
18521 which has the same meaning as the @file{*Backtrace*} buffer line in
18522 version 21.
18523 @end ignore
18525 However, suppose you are not quite certain what is going on?
18526 You can read the complete backtrace.
18528 In this case, you need to run a recent GNU Emacs, which automatically
18529 starts the debugger that puts you in the @file{*Backtrace*} buffer; or
18530 else, you need to start the debugger manually as described below.
18532 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
18533 what Emacs did that led to the error.  Emacs made an interactive call
18534 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
18535 of the @code{triangle-bugged} expression.  Each line above tells you
18536 what the Lisp interpreter evaluated next.
18538 @need 1250
18539 The third line from the top of the buffer is
18541 @smallexample
18542 (setq number (1= number))
18543 @end smallexample
18545 @noindent
18546 Emacs tried to evaluate this expression; in order to do so, it tried
18547 to evaluate the inner expression shown on the second line from the
18548 top:
18550 @smallexample
18551 (1= number)
18552 @end smallexample
18554 @need 1250
18555 @noindent
18556 This is where the error occurred; as the top line says:
18558 @smallexample
18559 Debugger entered--Lisp error: (void-function 1=)
18560 @end smallexample
18562 @noindent
18563 You can correct the mistake, re-evaluate the function definition, and
18564 then run your test again.
18566 @node debug-on-entry, debug-on-quit, debug, Debugging
18567 @section @code{debug-on-entry}
18568 @findex debug-on-entry
18570 A recent GNU Emacs starts the debugger automatically when your
18571 function has an error.
18573 @ignore
18574 GNU Emacs version 20 and before did not; it simply
18575 presented you with an error message.  You had to start the debugger
18576 manually.
18577 @end ignore
18579 Incidentally, you can start the debugger manually for all versions of
18580 Emacs; the advantage is that the debugger runs even if you do not have
18581 a bug in your code.  Sometimes your code will be free of bugs!
18583 You can enter the debugger when you call the function by calling
18584 @code{debug-on-entry}.
18586 @need 1250
18587 @noindent
18588 Type:
18590 @smallexample
18591 M-x debug-on-entry RET triangle-bugged RET
18592 @end smallexample
18594 @need 1250
18595 @noindent
18596 Now, evaluate the following:
18598 @smallexample
18599 (triangle-bugged 5)
18600 @end smallexample
18602 @noindent
18603 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
18604 you that it is beginning to evaluate the @code{triangle-bugged}
18605 function:
18607 @smallexample
18608 @group
18609 ---------- Buffer: *Backtrace* ----------
18610 Debugger entered--entering a function:
18611 * triangle-bugged(5)
18612   eval((triangle-bugged 5))
18613 @end group
18614 @group
18615   eval-last-sexp-1(nil)
18616   eval-last-sexp(nil)
18617   call-interactively(eval-last-sexp)
18618 ---------- Buffer: *Backtrace* ----------
18619 @end group
18620 @end smallexample
18622 In the @file{*Backtrace*} buffer, type @kbd{d}.  Emacs will evaluate
18623 the first expression in @code{triangle-bugged}; the buffer will look
18624 like this:
18626 @smallexample
18627 @group
18628 ---------- Buffer: *Backtrace* ----------
18629 Debugger entered--beginning evaluation of function call form:
18630 * (let ((total 0)) (while (> number 0) (setq total ...)
18631         (setq number ...)) total)
18632 * triangle-bugged(5)
18633   eval((triangle-bugged 5))
18634 @end group
18635 @group
18636   eval-last-sexp-1(nil)
18637   eval-last-sexp(nil)
18638   call-interactively(eval-last-sexp)
18639 ---------- Buffer: *Backtrace* ----------
18640 @end group
18641 @end smallexample
18643 @noindent
18644 Now, type @kbd{d} again, eight times, slowly.  Each time you type
18645 @kbd{d}, Emacs will evaluate another expression in the function
18646 definition.
18648 @need 1750
18649 Eventually, the buffer will look like this:
18651 @smallexample
18652 @group
18653 ---------- Buffer: *Backtrace* ----------
18654 Debugger entered--beginning evaluation of function call form:
18655 * (setq number (1= number))
18656 * (while (> number 0) (setq total (+ total number))
18657         (setq number (1= number)))
18658 @group
18659 @end group
18660 * (let ((total 0)) (while (> number 0) (setq total ...)
18661         (setq number ...)) total)
18662 * triangle-bugged(5)
18663   eval((triangle-bugged 5))
18664 @group
18665 @end group
18666   eval-last-sexp-1(nil)
18667   eval-last-sexp(nil)
18668   call-interactively(eval-last-sexp)
18669 ---------- Buffer: *Backtrace* ----------
18670 @end group
18671 @end smallexample
18673 @need 1500
18674 @noindent
18675 Finally, after you type @kbd{d} two more times, Emacs will reach the
18676 error, and the top two lines of the @file{*Backtrace*} buffer will look
18677 like this:
18679 @smallexample
18680 @group
18681 ---------- Buffer: *Backtrace* ----------
18682 Debugger entered--Lisp error: (void-function 1=)
18683 * (1= number)
18684 @dots{}
18685 ---------- Buffer: *Backtrace* ----------
18686 @end group
18687 @end smallexample
18689 By typing @kbd{d}, you were able to step through the function.
18691 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
18692 quits the trace, but does not cancel @code{debug-on-entry}.
18694 @findex cancel-debug-on-entry
18695 To cancel the effect of @code{debug-on-entry}, call
18696 @code{cancel-debug-on-entry} and the name of the function, like this:
18698 @smallexample
18699 M-x cancel-debug-on-entry RET triangle-bugged RET
18700 @end smallexample
18702 @noindent
18703 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
18705 @node debug-on-quit, edebug, debug-on-entry, Debugging
18706 @section @code{debug-on-quit} and @code{(debug)}
18708 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
18709 there are two other ways to start @code{debug}.
18711 @findex debug-on-quit
18712 You can start @code{debug} whenever you type @kbd{C-g}
18713 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
18714 @code{t}.  This is useful for debugging infinite loops.
18716 @need 1500
18717 @cindex @code{(debug)} in code
18718 Or, you can insert a line that says @code{(debug)} into your code
18719 where you want the debugger to start, like this:
18721 @smallexample
18722 @group
18723 (defun triangle-bugged (number)
18724   "Return sum of numbers 1 through NUMBER inclusive."
18725   (let ((total 0))
18726     (while (> number 0)
18727       (setq total (+ total number))
18728       (debug)                         ; @r{Start debugger.}
18729       (setq number (1= number)))      ; @r{Error here.}
18730     total))
18731 @end group
18732 @end smallexample
18734 The @code{debug} function is described in detail in @ref{Debugger, ,
18735 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
18737 @node edebug, Debugging Exercises, debug-on-quit, Debugging
18738 @section The @code{edebug} Source Level Debugger
18739 @cindex Source level debugger
18740 @findex edebug
18742 Edebug is a source level debugger.  Edebug normally displays the
18743 source of the code you are debugging, with an arrow at the left that
18744 shows which line you are currently executing.
18746 You can walk through the execution of a function, line by line, or run
18747 quickly until reaching a @dfn{breakpoint} where execution stops.
18749 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
18750 Lisp Reference Manual}.
18752 @need 1250
18753 Here is a bugged function definition for @code{triangle-recursively}.
18754 @xref{Recursive triangle function, , Recursion in place of a counter},
18755 for a review of it.
18757 @smallexample
18758 @group
18759 (defun triangle-recursively-bugged (number)
18760   "Return sum of numbers 1 through NUMBER inclusive.
18761 Uses recursion."
18762   (if (= number 1)
18763       1
18764     (+ number
18765        (triangle-recursively-bugged
18766         (1= number)))))               ; @r{Error here.}
18767 @end group
18768 @end smallexample
18770 @noindent
18771 Normally, you would install this definition by positioning your cursor
18772 after the function's closing parenthesis and typing @kbd{C-x C-e}
18773 (@code{eval-last-sexp}) or else by positioning your cursor within the
18774 definition and typing @kbd{C-M-x} (@code{eval-defun}).  (By default,
18775 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
18776 Interactive mode.)
18778 @need 1500
18779 However, to prepare this function definition for Edebug, you must
18780 first @dfn{instrument} the code using a different command.  You can do
18781 this by positioning your cursor within or just after the definition
18782 and typing
18784 @smallexample
18785 M-x edebug-defun RET
18786 @end smallexample
18788 @noindent
18789 This will cause Emacs to load Edebug automatically if it is not
18790 already loaded, and properly instrument the function.
18792 After instrumenting the function, place your cursor after the
18793 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
18795 @smallexample
18796 (triangle-recursively-bugged 3)
18797 @end smallexample
18799 @noindent
18800 You will be jumped back to the source for
18801 @code{triangle-recursively-bugged} and the cursor positioned at the
18802 beginning of the @code{if} line of the function.  Also, you will see
18803 an arrowhead at the left hand side of that line.  The arrowhead marks
18804 the line where the function is executing.  (In the following examples,
18805 we show the arrowhead with @samp{=>}; in a windowing system, you may
18806 see the arrowhead as a solid triangle in the window `fringe'.)
18808 @smallexample
18809 =>@point{}(if (= number 1)
18810 @end smallexample
18812 @noindent
18813 @iftex
18814 In the example, the location of point is displayed with a star,
18815 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
18816 @end iftex
18817 @ifnottex
18818 In the example, the location of point is displayed as @samp{@point{}}
18819 (in a printed book, it is displayed with a five pointed star).
18820 @end ifnottex
18822 If you now press @key{SPC}, point will move to the next expression to
18823 be executed; the line will look like this:
18825 @smallexample
18826 =>(if @point{}(= number 1)
18827 @end smallexample
18829 @noindent
18830 As you continue to press @key{SPC}, point will move from expression to
18831 expression.  At the same time, whenever an expression returns a value,
18832 that value will be displayed in the echo area.  For example, after you
18833 move point past @code{number}, you will see the following:
18835 @smallexample
18836 Result: 3 (#o3, #x3, ?\C-c)
18837 @end smallexample
18839 @noindent
18840 This means the value of @code{number} is 3, which is octal three,
18841 hexadecimal three, and @sc{ascii} `control-c' (the third letter of the
18842 alphabet, in case you need to know this information).
18844 You can continue moving through the code until you reach the line with
18845 the error.  Before evaluation, that line looks like this:
18847 @smallexample
18848 =>        @point{}(1= number)))))               ; @r{Error here.}
18849 @end smallexample
18851 @need 1250
18852 @noindent
18853 When you press @key{SPC} once again, you will produce an error message
18854 that says:
18856 @smallexample
18857 Symbol's function definition is void:@: 1=
18858 @end smallexample
18860 @noindent
18861 This is the bug.
18863 Press @kbd{q} to quit Edebug.
18865 To remove instrumentation from a function definition, simply
18866 re-evaluate it with a command that does not instrument it.
18867 For example, you could place your cursor after the definition's
18868 closing parenthesis and type @kbd{C-x C-e}.
18870 Edebug does a great deal more than walk with you through a function.
18871 You can set it so it races through on its own, stopping only at an
18872 error or at specified stopping points; you can cause it to display the
18873 changing values of various expressions; you can find out how many
18874 times a function is called, and more.
18876 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
18877 Lisp Reference Manual}.
18879 @need 1500
18880 @node Debugging Exercises,  , edebug, Debugging
18881 @section Debugging Exercises
18883 @itemize @bullet
18884 @item
18885 Install the @code{count-words-region} function and then cause it to
18886 enter the built-in debugger when you call it.  Run the command on a
18887 region containing two words.  You will need to press @kbd{d} a
18888 remarkable number of times.  On your system, is a `hook' called after
18889 the command finishes?  (For information on hooks, see @ref{Command
18890 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
18891 Manual}.)
18893 @item
18894 Copy @code{count-words-region} into the @file{*scratch*} buffer,
18895 instrument the function for Edebug, and walk through its execution.
18896 The function does not need to have a bug, although you can introduce
18897 one if you wish.  If the function lacks a bug, the walk-through
18898 completes without problems.
18900 @item
18901 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
18902 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
18903 @kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix
18904 for commands made outside of the Edebug debugging buffer.)
18906 @item
18907 In the Edebug debugging buffer, use the @kbd{p}
18908 (@code{edebug-bounce-point}) command to see where in the region the
18909 @code{count-words-region} is working.
18911 @item
18912 Move point to some spot further down the function and then type the
18913 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
18915 @item
18916 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
18917 walk through the function on its own; use an upper case @kbd{T} for
18918 @code{edebug-Trace-fast-mode}.
18920 @item
18921 Set a breakpoint, then run Edebug in Trace mode until it reaches the
18922 stopping point.
18923 @end itemize
18925 @node Conclusion, the-the, Debugging, Top
18926 @chapter Conclusion
18928 We have now reached the end of this Introduction.  You have now
18929 learned enough about programming in Emacs Lisp to set values, to write
18930 simple @file{.emacs} files for yourself and your friends, and write
18931 simple customizations and extensions to Emacs.
18933 This is a place to stop.  Or, if you wish, you can now go onward, and
18934 teach yourself.
18936 You have learned some of the basic nuts and bolts of programming.  But
18937 only some.  There are a great many more brackets and hinges that are
18938 easy to use that we have not touched.
18940 A path you can follow right now lies among the sources to GNU Emacs
18941 and in
18942 @ifnotinfo
18943 @cite{The GNU Emacs Lisp Reference Manual}.
18944 @end ifnotinfo
18945 @ifinfo
18946 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
18947 Emacs Lisp Reference Manual}.
18948 @end ifinfo
18950 The Emacs Lisp sources are an adventure.  When you read the sources and
18951 come across a function or expression that is unfamiliar, you need to
18952 figure out or find out what it does.
18954 Go to the Reference Manual.  It is a thorough, complete, and fairly
18955 easy-to-read description of Emacs Lisp.  It is written not only for
18956 experts, but for people who know what you know.  (The @cite{Reference
18957 Manual} comes with the standard GNU Emacs distribution.  Like this
18958 introduction, it comes as a Texinfo source file, so you can read it
18959 on-line and as a typeset, printed book.)
18961 Go to the other on-line help that is part of GNU Emacs: the on-line
18962 documentation for all functions and variables, and @code{find-tags},
18963 the program that takes you to sources.
18965 Here is an example of how I explore the sources.  Because of its name,
18966 @file{simple.el} is the file I looked at first, a long time ago.  As
18967 it happens some of the functions in @file{simple.el} are complicated,
18968 or at least look complicated at first sight.  The @code{open-line}
18969 function, for example, looks complicated.
18971 You may want to walk through this function slowly, as we did with the
18972 @code{forward-sentence} function.  (@xref{forward-sentence, The
18973 @code{forward-sentence} function}.)  Or you may want to skip that
18974 function and look at another, such as @code{split-line}.  You don't
18975 need to read all the functions.  According to
18976 @code{count-words-in-defun}, the @code{split-line} function contains
18977 102 words and symbols.
18979 Even though it is short, @code{split-line} contains  expressions
18980 we have not studied: @code{skip-chars-forward}, @code{indent-to},
18981 @code{current-column} and @code{insert-and-inherit}.
18983 Consider the @code{skip-chars-forward} function.  (It is part of the
18984 function definition for @code{back-to-indentation}, which is shown in
18985 @ref{Review, , Review}.)
18987 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
18988 typing @kbd{C-h f} (@code{describe-function}) and the name of the
18989 function.  This gives you the function documentation.
18991 You may be able to guess what is done by a well named function such as
18992 @code{indent-to}; or you can look it up, too.  Incidentally, the
18993 @code{describe-function} function itself is in @file{help.el}; it is
18994 one of those long, but decipherable functions.  You can look up
18995 @code{describe-function} using the @kbd{C-h f} command!
18997 In this instance, since the code is Lisp, the @file{*Help*} buffer
18998 contains the name of the library containing the function's source.
18999 You can put point over the name of the library and press the RET key,
19000 which in this situation is bound to @code{help-follow}, and be taken
19001 directly to the source, in the same way as @kbd{M-.}
19002 (@code{find-tag}).
19004 The definition for @code{describe-function} illustrates how to
19005 customize the @code{interactive} expression without using the standard
19006 character codes; and it shows how to create a temporary buffer.
19008 (The @code{indent-to} function is written in C rather than Emacs Lisp;
19009 it is a `built-in' function.  @code{help-follow} takes you to its
19010 source as does @code{find-tag}, when properly set up.)
19012 You can look at a function's source using @code{find-tag}, which is
19013 bound to @kbd{M-.}  Finally, you can find out what the Reference
19014 Manual has to say by visiting the manual in Info, and typing @kbd{i}
19015 (@code{Info-index}) and the name of the function, or by looking up the
19016 function in the index to a printed copy of the manual.
19018 Similarly, you can find out what is meant by
19019 @code{insert-and-inherit}.
19021 Other interesting source files include @file{paragraphs.el},
19022 @file{loaddefs.el}, and @file{loadup.el}.  The @file{paragraphs.el}
19023 file includes short, easily understood functions as well as longer
19024 ones.  The @file{loaddefs.el} file contains the many standard
19025 autoloads and many keymaps.  I have never looked at it all; only at
19026 parts.  @file{loadup.el} is the file that loads the standard parts of
19027 Emacs; it tells you a great deal about how Emacs is built.
19028 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
19029 Reference Manual}, for more about building.)
19031 As I said, you have learned some nuts and bolts; however, and very
19032 importantly, we have hardly touched major aspects of programming; I
19033 have said nothing about how to sort information, except to use the
19034 predefined @code{sort} function; I have said nothing about how to store
19035 information, except to use variables and lists; I have said nothing
19036 about how to write programs that write programs.  These are topics for
19037 another, and different kind of book, a different kind of learning.
19039 What you have done is learn enough for much practical work with GNU
19040 Emacs.  What you have done is get started.  This is the end of a
19041 beginning.
19043 @c ================ Appendix ================
19045 @node the-the, Kill Ring, Conclusion, Top
19046 @appendix The @code{the-the} Function
19047 @findex the-the
19048 @cindex Duplicated words function
19049 @cindex Words, duplicated
19051 Sometimes when you you write text, you duplicate words---as with ``you
19052 you'' near the beginning of this sentence.  I find that most
19053 frequently, I duplicate ``the''; hence, I call the function for
19054 detecting duplicated words, @code{the-the}.
19056 @need 1250
19057 As a first step, you could use the following regular expression to
19058 search for duplicates:
19060 @smallexample
19061 \\(\\w+[ \t\n]+\\)\\1
19062 @end smallexample
19064 @noindent
19065 This regexp matches one or more word-constituent characters followed
19066 by one or more spaces, tabs, or newlines.  However, it does not detect
19067 duplicated words on different lines, since the ending of the first
19068 word, the end of the line, is different from the ending of the second
19069 word, a space.  (For more information about regular expressions, see
19070 @ref{Regexp Search, , Regular Expression Searches}, as well as
19071 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
19072 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
19073 The GNU Emacs Lisp Reference Manual}.)
19075 You might try searching just for duplicated word-constituent
19076 characters but that does not work since the pattern detects doubles
19077 such as the two occurrences of `th' in `with the'.
19079 Another possible regexp searches for word-constituent characters
19080 followed by non-word-constituent characters, reduplicated.  Here,
19081 @w{@samp{\\w+}} matches one or more word-constituent characters and
19082 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
19084 @smallexample
19085 \\(\\(\\w+\\)\\W*\\)\\1
19086 @end smallexample
19088 @noindent
19089 Again, not useful.
19091 Here is the pattern that I use.  It is not perfect, but good enough.
19092 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
19093 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
19094 any characters that are @emph{not} an @@-sign, space, newline, or tab.
19096 @smallexample
19097 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
19098 @end smallexample
19100 One can write more complicated expressions, but I found that this
19101 expression is good enough, so I use it.
19103 Here is the @code{the-the} function, as I include it in my
19104 @file{.emacs} file, along with a handy global key binding:
19106 @smallexample
19107 @group
19108 (defun the-the ()
19109   "Search forward for for a duplicated word."
19110   (interactive)
19111   (message "Searching for for duplicated words ...")
19112   (push-mark)
19113 @end group
19114 @group
19115   ;; This regexp is not perfect
19116   ;; but is fairly good over all:
19117   (if (re-search-forward
19118        "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
19119       (message "Found duplicated word.")
19120     (message "End of buffer")))
19121 @end group
19123 @group
19124 ;; Bind `the-the' to  C-c \
19125 (global-set-key "\C-c\\" 'the-the)
19126 @end group
19127 @end smallexample
19129 @sp 1
19130 Here is test text:
19132 @smallexample
19133 @group
19134 one two two three four five
19135 five six seven
19136 @end group
19137 @end smallexample
19139 You can substitute the other regular expressions shown above in the
19140 function definition and try each of them on this list.
19142 @node Kill Ring, Full Graph, the-the, Top
19143 @appendix Handling the Kill Ring
19144 @cindex Kill ring handling
19145 @cindex Handling the kill ring
19146 @cindex Ring, making a list like a
19148 The kill ring is a list that is transformed into a ring by the
19149 workings of the @code{current-kill} function.  The @code{yank} and
19150 @code{yank-pop} commands use the @code{current-kill} function.
19152 This appendix describes the @code{current-kill} function as well as
19153 both the @code{yank} and the @code{yank-pop} commands, but first,
19154 consider the workings of the kill ring.
19156 @menu
19157 * What the Kill Ring Does::
19158 * current-kill::
19159 * yank::                        Paste a copy of a clipped element.
19160 * yank-pop::                    Insert element pointed to.
19161 * ring file::
19162 @end menu
19164 @node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring
19165 @ifnottex
19166 @unnumberedsec What the Kill Ring Does
19167 @end ifnottex
19169 @need 1250
19170 The kill ring has a default maximum length of sixty items; this number
19171 is too large for an explanation.  Instead, set it to four.  Please
19172 evaluate the following:
19174 @smallexample
19175 @group
19176 (setq old-kill-ring-max kill-ring-max)
19177 (setq kill-ring-max 4)
19178 @end group
19179 @end smallexample
19181 @noindent
19182 Then, please copy each line of the following indented example into the
19183 kill ring.  You may kill each line with @kbd{C-k} or mark it and copy
19184 it with @kbd{M-w}.
19186 @noindent
19187 (In a read-only buffer, such as the @file{*info*} buffer, the kill
19188 command, @kbd{C-k} (@code{kill-line}), will not remove the text,
19189 merely copy it to the kill ring.  However, your machine may beep at
19190 you.  Alternatively, for silence, you may copy the region of each line
19191 with the @kbd{M-w} (@code{kill-ring-save}) command.  You must mark
19192 each line for this command to succeed, but it does not matter at which
19193 end you put point or mark.)
19195 @need 1250
19196 @noindent
19197 Please invoke the calls in order, so that five elements attempt to
19198 fill the kill ring:
19200 @smallexample
19201 @group
19202 first some text
19203 second piece of text
19204 third line
19205 fourth line of text
19206 fifth bit of text
19207 @end group
19208 @end smallexample
19210 @need 1250
19211 @noindent
19212 Then find the value of @code{kill-ring} by evaluating
19214 @smallexample
19215 kill-ring
19216 @end smallexample
19218 @need 800
19219 @noindent
19220 It is:
19222 @smallexample
19223 @group
19224 ("fifth bit of text" "fourth line of text"
19225 "third line" "second piece of text")
19226 @end group
19227 @end smallexample
19229 @noindent
19230 The first element, @samp{first some text}, was dropped.
19232 @need 1250
19233 To return to the old value for the length of the kill ring, evaluate:
19235 @smallexample
19236 (setq kill-ring-max old-kill-ring-max)
19237 @end smallexample
19239 @node current-kill, yank, What the Kill Ring Does, Kill Ring
19240 @comment  node-name,  next,  previous,  up
19241 @appendixsec The @code{current-kill} Function
19242 @findex current-kill
19244 The @code{current-kill} function changes the element in the kill ring
19245 to which @code{kill-ring-yank-pointer} points.  (Also, the
19246 @code{kill-new} function sets @code{kill-ring-yank-pointer} to point
19247 to the latest element of the the kill ring.  The @code{kill-new}
19248 function is used directly or indirectly by @code{kill-append},
19249 @code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
19250 and @code{kill-region}.)
19252 @menu
19253 * Code for current-kill::
19254 * Understanding current-kill::
19255 @end menu
19257 @node Code for current-kill, Understanding current-kill, current-kill, current-kill
19258 @ifnottex
19259 @unnumberedsubsec The code for @code{current-kill}
19260 @end ifnottex
19263 @need 1500
19264 The @code{current-kill} function is used by @code{yank} and by
19265 @code{yank-pop}.  Here is the code for @code{current-kill}:
19267 @smallexample
19268 @group
19269 (defun current-kill (n &optional do-not-move)
19270   "Rotate the yanking point by N places, and then return that kill.
19271 If N is zero, `interprogram-paste-function' is set, and calling it
19272 returns a string, then that string is added to the front of the
19273 kill ring and returned as the latest kill.
19274 @end group
19275 @group
19276 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
19277 yanking point; just return the Nth kill forward."
19278   (let ((interprogram-paste (and (= n 0)
19279                                  interprogram-paste-function
19280                                  (funcall interprogram-paste-function))))
19281 @end group
19282 @group
19283     (if interprogram-paste
19284         (progn
19285           ;; Disable the interprogram cut function when we add the new
19286           ;; text to the kill ring, so Emacs doesn't try to own the
19287           ;; selection, with identical text.
19288           (let ((interprogram-cut-function nil))
19289             (kill-new interprogram-paste))
19290           interprogram-paste)
19291 @end group
19292 @group
19293       (or kill-ring (error "Kill ring is empty"))
19294       (let ((ARGth-kill-element
19295              (nthcdr (mod (- n (length kill-ring-yank-pointer))
19296                           (length kill-ring))
19297                      kill-ring)))
19298         (or do-not-move
19299             (setq kill-ring-yank-pointer ARGth-kill-element))
19300         (car ARGth-kill-element)))))
19301 @end group
19302 @end smallexample
19304 Remember also that the @code{kill-new} function sets
19305 @code{kill-ring-yank-pointer} to the latest element of the the kill
19306 ring, which means that all the functions that call it set the value
19307 indirectly: @code{kill-append}, @code{copy-region-as-kill},
19308 @code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.
19310 @need 1500
19311 Here is the line in @code{kill-new}, which is explained in
19312 @ref{kill-new function, , The @code{kill-new} function}.
19314 @smallexample
19315 (setq kill-ring-yank-pointer kill-ring)
19316 @end smallexample
19318 @node Understanding current-kill,  , Code for current-kill, current-kill
19319 @ifnottex
19320 @unnumberedsubsec @code{current-kill} in Outline
19321 @end ifnottex
19323 The @code{current-kill} function looks complex, but as usual, it can
19324 be understood by taking it apart piece by piece.  First look at it in
19325 skeletal form:
19327 @smallexample
19328 @group
19329 (defun current-kill (n &optional do-not-move)
19330   "Rotate the yanking point by N places, and then return that kill."
19331   (let @var{varlist}
19332     @var{body}@dots{})
19333 @end group
19334 @end smallexample
19336 This function takes two arguments, one of which is optional.  It has a
19337 documentation string.  It is @emph{not} interactive.
19339 @menu
19340 * Body of current-kill::
19341 * Digression concerning error::  How to mislead humans, but not computers.
19342 * Determining the Element::
19343 @end menu
19345 @node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill
19346 @ifnottex
19347 @unnumberedsubsubsec The Body of @code{current-kill}
19348 @end ifnottex
19350 The body of the function definition is a @code{let} expression, which
19351 itself has a body as well as a @var{varlist}.
19353 The @code{let} expression declares a variable that will be only usable
19354 within the bounds of this function.  This variable is called
19355 @code{interprogram-paste} and is for copying to another program.  It
19356 is not for copying within this instance of GNU Emacs.  Most window
19357 systems provide a facility for interprogram pasting.  Sadly, that
19358 facility usually provides only for the last element.  Most windowing
19359 systems have not adopted a ring of many possibilities, even though
19360 Emacs has provided it for decades.
19362 The @code{if} expression has two parts, one if there exists
19363 @code{interprogram-paste} and one if not.
19365 @need 2000
19366 Let us consider the `if not' or else-part of the @code{current-kill}
19367 function.  (The then-part uses the the @code{kill-new} function, which
19368 we have already described.  @xref{kill-new function, , The
19369 @code{kill-new} function}.)
19371 @smallexample
19372 @group
19373 (or kill-ring (error "Kill ring is empty"))
19374 (let ((ARGth-kill-element
19375        (nthcdr (mod (- n (length kill-ring-yank-pointer))
19376                     (length kill-ring))
19377                kill-ring)))
19378   (or do-not-move
19379       (setq kill-ring-yank-pointer ARGth-kill-element))
19380   (car ARGth-kill-element))
19381 @end group
19382 @end smallexample
19384 @noindent
19385 The code first checks whether the kill ring has content; otherwise it
19386 signals an error.
19388 @need 1000
19389 Note that the @code{or} expression is very similar to testing length
19390 with an @code{if}:
19392 @findex zerop
19393 @findex error
19394 @smallexample
19395 @group
19396 (if (zerop (length kill-ring))          ; @r{if-part}
19397     (error "Kill ring is empty"))       ; @r{then-part}
19398   ;; No else-part
19399 @end group
19400 @end smallexample
19402 @noindent
19403 If there is not anything in the kill ring, its length must be zero and
19404 an error message sent to the user: @samp{Kill ring is empty}.  The
19405 @code{current-kill} function uses an @code{or} expression which is
19406 simpler.  But an @code{if} expression reminds us what goes on.
19408 This @code{if} expression uses the function @code{zerop} which returns
19409 true if the value it is testing is zero.  When @code{zerop} tests
19410 true, the then-part of the @code{if} is evaluated.  The then-part is a
19411 list starting with the function @code{error}, which is a function that
19412 is similar to the @code{message} function
19413 (@pxref{message, , The @code{message} Function}) in that
19414 it prints a one-line message in the echo area.  However, in addition
19415 to printing a message, @code{error} also stops evaluation of the
19416 function within which it is embedded.  This means that the rest of the
19417 function will not be evaluated if the length of the kill ring is zero.
19419 Then the @code{current-kill} function selects the element to return.
19420 The selection depends on the number of places that @code{current-kill}
19421 rotates and on where @code{kill-ring-yank-pointer} points.
19423 Next, either the optional @code{do-not-move} argument is true or the
19424 current value of @code{kill-ring-yank-pointer} is set to point to the
19425 list.  Finally, another expression returns the first element of the
19426 list even if the @code{do-not-move} argument is true.
19428 @node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill
19429 @ifnottex
19430 @unnumberedsubsubsec Digression about the word `error'
19431 @end ifnottex
19433 In my opinion, it is slightly misleading, at least to humans, to use
19434 the term `error' as the name of the @code{error} function.  A better
19435 term would be `cancel'.  Strictly speaking, of course, you cannot
19436 point to, much less rotate a pointer to a list that has no length, so
19437 from the point of view of the computer, the word `error' is correct.
19438 But a human expects to attempt this sort of thing, if only to find out
19439 whether the kill ring is full or empty.  This is an act of
19440 exploration.
19442 From the human point of view, the act of exploration and discovery is
19443 not necessarily an error, and therefore should not be labelled as one,
19444 even in the bowels of a computer.  As it is, the code in Emacs implies
19445 that a human who is acting virtuously, by exploring his or her
19446 environment, is making an error.  This is bad.  Even though the computer
19447 takes the same steps as it does when there is an `error', a term such as
19448 `cancel' would have a clearer connotation.
19450 @node Determining the Element,  , Digression concerning error, Understanding current-kill
19451 @ifnottex
19452 @unnumberedsubsubsec Determining the Element
19453 @end ifnottex
19455 Among other actions, the else-part of the @code{if} expression sets
19456 the value of @code{kill-ring-yank-pointer} to
19457 @code{ARGth-kill-element} when the kill ring has something in it and
19458 the value of @code{do-not-move} is @code{nil}.
19460 @need 800
19461 The code looks like this:
19463 @smallexample
19464 @group
19465 (nthcdr (mod (- n (length kill-ring-yank-pointer))
19466              (length kill-ring))
19467         kill-ring)))
19468 @end group
19469 @end smallexample
19471 This needs some examination.  Unless it is not supposed to move the
19472 pointer, the @code{current-kill} function changes where
19473 @code{kill-ring-yank-pointer} points.
19474 That is what the
19475 @w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
19476 expression does.  Also, clearly, @code{ARGth-kill-element} is being
19477 set to be equal to some @sc{cdr} of the kill ring, using the
19478 @code{nthcdr} function that is described in an earlier section.
19479 (@xref{copy-region-as-kill}.)  How does it do this?
19481 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
19482 works by repeatedly taking the @sc{cdr} of a list---it takes the
19483 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
19485 @need 800
19486 The two following expressions produce the same result:
19488 @smallexample
19489 @group
19490 (setq kill-ring-yank-pointer (cdr kill-ring))
19492 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
19493 @end group
19494 @end smallexample
19496 However, the @code{nthcdr} expression is more complicated.  It uses
19497 the @code{mod} function to determine which @sc{cdr} to select.
19499 (You will remember to look at inner functions first; indeed, we will
19500 have to go inside the @code{mod}.)
19502 The @code{mod} function returns the value of its first argument modulo
19503 the second; that is to say, it returns the remainder after dividing
19504 the first argument by the second.  The value returned has the same
19505 sign as the second argument.
19507 @need 800
19508 Thus,
19510 @smallexample
19511 @group
19512 (mod 12 4)
19513   @result{} 0  ;; @r{because there is no remainder}
19514 (mod 13 4)
19515   @result{} 1
19516 @end group
19517 @end smallexample
19519 @need 1250
19520 In this case, the first argument is often smaller than the second.
19521 That is fine.
19523 @smallexample
19524 @group
19525 (mod 0 4)
19526   @result{} 0
19527 (mod 1 4)
19528   @result{} 1
19529 @end group
19530 @end smallexample
19532 We can guess what the @code{-} function does.  It is like @code{+} but
19533 subtracts instead of adds; the @code{-} function subtracts its second
19534 argument from its first.  Also, we already know what the @code{length}
19535 function does (@pxref{length}).  It returns the length of a list.
19537 And @code{n} is the name of the required argument to the
19538 @code{current-kill} function.
19540 @need 1250
19541 So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
19542 expression returns the whole list, as you can see by evaluating the
19543 following:
19545 @smallexample
19546 @group
19547 ;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
19548 ;; @r{and} (mod (- 0 4) 4) @result{} 0
19549 (nthcdr (mod (- 0 4) 4)
19550         '("fourth line of text"
19551           "third line"
19552           "second piece of text"
19553           "first some text"))
19554 @end group
19555 @end smallexample
19557 @need 1250
19558 When the first argument to the @code{current-kill} function is one,
19559 the @code{nthcdr} expression returns the list without its first
19560 element.
19562 @smallexample
19563 @group
19564 (nthcdr (mod (- 1 4) 4)
19565         '("fourth line of text"
19566           "third line"
19567           "second piece of text"
19568           "first some text"))
19569 @end group
19570 @end smallexample
19572 @cindex @samp{global variable} defined
19573 @cindex @samp{variable, global}, defined
19574 Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer}
19575 are @dfn{global variables}.  That means that any expression in Emacs
19576 Lisp can access them.  They are not like the local variables set by
19577 @code{let} or like the symbols in an argument list.
19578 Local variables can only be accessed
19579 within the @code{let} that defines them or the function that specifies
19580 them in an argument list (and within expressions called by them).
19582 @ignore
19583 @c texi2dvi fails when the name of the section is within ifnottex ...
19584 (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
19585 @ref{defun, , The @code{defun} Special Form}.)
19586 @end ignore
19588 @node yank, yank-pop, current-kill, Kill Ring
19589 @comment  node-name,  next,  previous,  up
19590 @appendixsec @code{yank}
19591 @findex yank
19593 After learning about @code{current-kill}, the code for the
19594 @code{yank} function is almost easy.
19596 The @code{yank} function does not use the
19597 @code{kill-ring-yank-pointer} variable directly.  It calls
19598 @code{insert-for-yank} which calls @code{current-kill} which sets the
19599 @code{kill-ring-yank-pointer} variable.
19601 @need 1250
19602 The code looks like this:
19604 @c in GNU Emacs 22
19605 @smallexample
19606 @group
19607 (defun yank (&optional arg)
19608   "Reinsert (\"paste\") the last stretch of killed text.
19609 More precisely, reinsert the stretch of killed text most recently
19610 killed OR yanked.  Put point at end, and set mark at beginning.
19611 With just \\[universal-argument] as argument, same but put point at
19612 beginning (and mark at end).  With argument N, reinsert the Nth most
19613 recently killed stretch of killed text.
19615 When this command inserts killed text into the buffer, it honors
19616 `yank-excluded-properties' and `yank-handler' as described in the
19617 doc string for `insert-for-yank-1', which see.
19619 See also the command \\[yank-pop]."
19620 @end group
19621 @group
19622   (interactive "*P")
19623   (setq yank-window-start (window-start))
19624   ;; If we don't get all the way thru, make last-command indicate that
19625   ;; for the following command.
19626   (setq this-command t)
19627   (push-mark (point))
19628 @end group
19629 @group
19630   (insert-for-yank (current-kill (cond
19631                                   ((listp arg) 0)
19632                                   ((eq arg '-) -2)
19633                                   (t (1- arg)))))
19634   (if (consp arg)
19635       ;; This is like exchange-point-and-mark,
19636       ;;     but doesn't activate the mark.
19637       ;; It is cleaner to avoid activation, even though the command
19638       ;; loop would deactivate the mark because we inserted text.
19639       (goto-char (prog1 (mark t)
19640                    (set-marker (mark-marker) (point) (current-buffer)))))
19641 @end group
19642 @group
19643   ;; If we do get all the way thru, make this-command indicate that.
19644   (if (eq this-command t)
19645       (setq this-command 'yank))
19646   nil)
19647 @end group
19648 @end smallexample
19650 The key expression is @code{insert-for-yank}, which inserts the string
19651 returned by @code{current-kill}, but removes some text properties from
19654 However, before getting to that expression, the function sets the value
19655 of @code{yank-window-start} to the position returned by the
19656 @code{(window-start)} expression, the position at which the display
19657 currently starts.  The @code{yank} function also sets
19658 @code{this-command} and pushes the mark.
19660 After it yanks the appropriate element, if the optional argument is a
19661 @sc{cons} rather than a number or nothing, it puts point at beginning
19662 of the yanked text and mark at its end.
19664 (The @code{prog1} function is like @code{progn} but returns the value
19665 of its first argument rather than the value of its last argument.  Its
19666 first argument is forced to return the buffer's mark as an integer.
19667 You can see the documentation for these functions by placing point
19668 over them in this buffer and then typing @kbd{C-h f}
19669 (@code{describe-function}) followed by a @kbd{RET}; the default is the
19670 function.)
19672 The last part of the function tells what to do when it succeeds.
19674 @node yank-pop, ring file, yank, Kill Ring
19675 @comment  node-name,  next,  previous,  up
19676 @appendixsec @code{yank-pop}
19677 @findex yank-pop
19679 After understanding @code{yank} and @code{current-kill}, you know how
19680 to approach the @code{yank-pop} function.  Leaving out the
19681 documentation to save space, it looks like this:
19683 @c GNU Emacs 22
19684 @smallexample
19685 @group
19686 (defun yank-pop (&optional arg)
19687   "@dots{}"
19688   (interactive "*p")
19689   (if (not (eq last-command 'yank))
19690       (error "Previous command was not a yank"))
19691 @end group
19692 @group
19693   (setq this-command 'yank)
19694   (unless arg (setq arg 1))
19695   (let ((inhibit-read-only t)
19696         (before (< (point) (mark t))))
19697 @end group
19698 @group
19699     (if before
19700         (funcall (or yank-undo-function 'delete-region) (point) (mark t))
19701       (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
19702     (setq yank-undo-function nil)
19703 @end group
19704 @group
19705     (set-marker (mark-marker) (point) (current-buffer))
19706     (insert-for-yank (current-kill arg))
19707     ;; Set the window start back where it was in the yank command,
19708     ;; if possible.
19709     (set-window-start (selected-window) yank-window-start t)
19710 @end group
19711 @group
19712     (if before
19713         ;; This is like exchange-point-and-mark,
19714         ;;     but doesn't activate the mark.
19715         ;; It is cleaner to avoid activation, even though the command
19716         ;; loop would deactivate the mark because we inserted text.
19717         (goto-char (prog1 (mark t)
19718                      (set-marker (mark-marker)
19719                                  (point)
19720                                  (current-buffer))))))
19721   nil)
19722 @end group
19723 @end smallexample
19725 The function is interactive with a small @samp{p} so the prefix
19726 argument is processed and passed to the function.  The command can
19727 only be used after a previous yank; otherwise an error message is
19728 sent.  This check uses the variable @code{last-command} which is set
19729 by @code{yank} and is discussed elsewhere.
19730 (@xref{copy-region-as-kill}.)
19732 The @code{let} clause sets the variable @code{before} to true or false
19733 depending whether point is before or after mark and then the region
19734 between point and mark is deleted.  This is the region that was just
19735 inserted by the previous yank and it is this text that will be
19736 replaced.
19738 @code{funcall} calls its first argument as a function, passing
19739 remaining arguments to it.  The first argument is whatever the
19740 @code{or} expression returns.  The two remaining arguments are the
19741 positions of point and mark set by the preceding @code{yank} command.
19743 There is more, but that is the hardest part.
19745 @node ring file,  , yank-pop, Kill Ring
19746 @comment  node-name,  next,  previous,  up
19747 @appendixsec The @file{ring.el} File
19748 @cindex @file{ring.el} file
19750 Interestingly, GNU Emacs posses a file called @file{ring.el} that
19751 provides many of the features we just discussed.  But functions such
19752 as @code{kill-ring-yank-pointer} do not use this library, possibly
19753 because they were written earlier.
19755 @node Full Graph, Free Software and Free Manuals, Kill Ring, Top
19756 @appendix A Graph with Labelled Axes
19758 Printed axes help you understand a graph.  They convey scale.  In an
19759 earlier chapter (@pxref{Readying a Graph, ,  Readying a Graph}), we
19760 wrote the code to print the body of a graph.  Here we write the code
19761 for printing and labelling vertical and horizontal axes, along with the
19762 body itself.
19764 @menu
19765 * Labelled Example::
19766 * print-graph Varlist::         @code{let} expression in @code{print-graph}.
19767 * print-Y-axis::                Print a label for the vertical axis.
19768 * print-X-axis::                Print a horizontal label.
19769 * Print Whole Graph::           The function to print a complete graph.
19770 @end menu
19772 @node Labelled Example, print-graph Varlist, Full Graph, Full Graph
19773 @ifnottex
19774 @unnumberedsec Labelled Example Graph
19775 @end ifnottex
19777 Since insertions fill a buffer to the right and below point, the new
19778 graph printing function should first print the Y or vertical axis,
19779 then the body of the graph, and finally the X or horizontal axis.
19780 This sequence lays out for us the contents of the function:
19782 @enumerate
19783 @item
19784 Set up code.
19786 @item
19787 Print Y axis.
19789 @item
19790 Print body of graph.
19792 @item
19793 Print X axis.
19794 @end enumerate
19796 @need 800
19797 Here is an example of how a finished graph should look:
19799 @smallexample
19800 @group
19801     10 -
19802                   *
19803                   *  *
19804                   *  **
19805                   *  ***
19806      5 -      *   *******
19807             * *** *******
19808             *************
19809           ***************
19810      1 - ****************
19811          |   |    |    |
19812          1   5   10   15
19813 @end group
19814 @end smallexample
19816 @noindent
19817 In this graph, both the vertical and the horizontal axes are labelled
19818 with numbers.  However, in some graphs, the horizontal axis is time
19819 and would be better labelled with months, like this:
19821 @smallexample
19822 @group
19823      5 -      *
19824             * ** *
19825             *******
19826           ********** **
19827      1 - **************
19828          |    ^      |
19829          Jan  June   Jan
19830 @end group
19831 @end smallexample
19833 Indeed, with a little thought, we can easily come up with a variety of
19834 vertical and horizontal labelling schemes.  Our task could become
19835 complicated.  But complications breed confusion.  Rather than permit
19836 this, it is better choose a simple labelling scheme for our first
19837 effort, and to modify or replace it later.
19839 @need 1200
19840 These considerations suggest the following outline for the
19841 @code{print-graph} function:
19843 @smallexample
19844 @group
19845 (defun print-graph (numbers-list)
19846   "@var{documentation}@dots{}"
19847   (let ((height  @dots{}
19848         @dots{}))
19849 @end group
19850 @group
19851     (print-Y-axis height @dots{} )
19852     (graph-body-print numbers-list)
19853     (print-X-axis @dots{} )))
19854 @end group
19855 @end smallexample
19857 We can work on each part of the @code{print-graph} function definition
19858 in turn.
19860 @node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph
19861 @comment  node-name,  next,  previous,  up
19862 @appendixsec The @code{print-graph} Varlist
19863 @cindex @code{print-graph} varlist
19865 In writing the @code{print-graph} function, the first task is to write
19866 the varlist in the @code{let} expression.  (We will leave aside for the
19867 moment any thoughts about making the function interactive or about the
19868 contents of its documentation string.)
19870 The varlist should set several values.  Clearly, the top of the label
19871 for the vertical axis must be at least the height of the graph, which
19872 means that we must obtain this information here.  Note that the
19873 @code{print-graph-body} function also requires this information.  There
19874 is no reason to calculate the height of the graph in two different
19875 places, so we should change @code{print-graph-body} from the way we
19876 defined it earlier to take advantage of the calculation.
19878 Similarly, both the function for printing the X axis labels and the
19879 @code{print-graph-body} function need to learn the value of the width of
19880 each symbol.  We can perform the calculation here and change the
19881 definition for @code{print-graph-body} from the way we defined it in the
19882 previous chapter.
19884 The length of the label for the horizontal axis must be at least as long
19885 as the graph.  However, this information is used only in the function
19886 that prints the horizontal axis, so it does not need to be calculated here.
19888 These thoughts lead us directly to the following form for the varlist
19889 in the @code{let} for @code{print-graph}:
19891 @smallexample
19892 @group
19893 (let ((height (apply 'max numbers-list)) ; @r{First version.}
19894       (symbol-width (length graph-blank)))
19895 @end group
19896 @end smallexample
19898 @noindent
19899 As we shall see, this expression is not quite right.
19901 @need 2000
19902 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph
19903 @comment  node-name,  next,  previous,  up
19904 @appendixsec The @code{print-Y-axis} Function
19905 @cindex Axis, print vertical
19906 @cindex Y axis printing
19907 @cindex Vertical axis printing
19908 @cindex Print vertical axis
19910 The job of the @code{print-Y-axis} function is to print a label for
19911 the vertical axis that looks like this:
19913 @smallexample
19914 @group
19915     10 -
19920      5 -
19924      1 -
19925 @end group
19926 @end smallexample
19928 @noindent
19929 The function should be passed the height of the graph, and then should
19930 construct and insert the appropriate numbers and marks.
19932 @menu
19933 * print-Y-axis in Detail::
19934 * Height of label::             What height for the Y axis?
19935 * Compute a Remainder::         How to compute the remainder of a division.
19936 * Y Axis Element::              Construct a line for the Y axis.
19937 * Y-axis-column::               Generate a list of Y axis labels.
19938 * print-Y-axis Penultimate::    A not quite final version.
19939 @end menu
19941 @node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis
19942 @ifnottex
19943 @unnumberedsubsec The @code{print-Y-axis} Function in Detail
19944 @end ifnottex
19946 It is easy enough to see in the figure what the Y axis label should
19947 look like; but to say in words, and then to write a function
19948 definition to do the job is another matter.  It is not quite true to
19949 say that we want a number and a tic every five lines: there are only
19950 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
19951 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
19952 and 9).  It is better to say that we want a number and a tic mark on
19953 the base line (number 1) and then that we want a number and a tic on
19954 the fifth line from the bottom and on every line that is a multiple of
19955 five.
19957 @node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis
19958 @ifnottex
19959 @unnumberedsubsec What height should the label be?
19960 @end ifnottex
19962 The next issue is what height the label should be?  Suppose the maximum
19963 height of tallest column of the graph is seven.  Should the highest
19964 label on the Y axis be @samp{5 -}, and should the graph stick up above
19965 the label?  Or should the highest label be @samp{7 -}, and mark the peak
19966 of the graph?  Or should the highest label be @code{10 -}, which is a
19967 multiple of five, and be higher than the topmost value of the graph?
19969 The latter form is preferred.  Most graphs are drawn within rectangles
19970 whose sides are an integral number of steps long---5, 10, 15, and so
19971 on for a step distance of five.  But as soon as we decide to use a
19972 step height for the vertical axis, we discover that the simple
19973 expression in the varlist for computing the height is wrong.  The
19974 expression is @code{(apply 'max numbers-list)}.  This returns the
19975 precise height, not the maximum height plus whatever is necessary to
19976 round up to the nearest multiple of five.  A more complex expression
19977 is required.
19979 As usual in cases like this, a complex problem becomes simpler if it is
19980 divided into several smaller problems.
19982 First, consider the case when the highest value of the graph is an
19983 integral multiple of five---when it is 5, 10, 15, or some higher
19984 multiple of five.  We can use this value as the Y axis height.
19986 A fairly simply way to determine whether a number is a multiple of
19987 five is to divide it by five and see if the division results in a
19988 remainder.  If there is no remainder, the number is a multiple of
19989 five.  Thus, seven divided by five has a remainder of two, and seven
19990 is not an integral multiple of five.  Put in slightly different
19991 language, more reminiscent of the classroom, five goes into seven
19992 once, with a remainder of two.  However, five goes into ten twice,
19993 with no remainder: ten is an integral multiple of five.
19995 @node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis
19996 @appendixsubsec Side Trip: Compute a Remainder
19998 @findex % @r{(remainder function)}
19999 @cindex Remainder function, @code{%}
20000 In Lisp, the function for computing a remainder is @code{%}.  The
20001 function returns the remainder of its first argument divided by its
20002 second argument.  As it happens, @code{%} is a function in Emacs Lisp
20003 that you cannot discover using @code{apropos}: you find nothing if you
20004 type @kbd{M-x apropos @key{RET} remainder @key{RET}}.  The only way to
20005 learn of the existence of @code{%} is to read about it in a book such
20006 as this or in the Emacs Lisp sources.
20008 You can try the @code{%} function by evaluating the following two
20009 expressions:
20011 @smallexample
20012 @group
20013 (% 7 5)
20015 (% 10 5)
20016 @end group
20017 @end smallexample
20019 @noindent
20020 The first expression returns 2 and the second expression returns 0.
20022 To test whether the returned value is zero or some other number, we
20023 can use the @code{zerop} function.  This function returns @code{t} if
20024 its argument, which must be a number, is zero.
20026 @smallexample
20027 @group
20028 (zerop (% 7 5))
20029      @result{} nil
20031 (zerop (% 10 5))
20032      @result{} t
20033 @end group
20034 @end smallexample
20036 Thus, the following expression will return @code{t} if the height
20037 of the graph is evenly divisible by five:
20039 @smallexample
20040 (zerop (% height 5))
20041 @end smallexample
20043 @noindent
20044 (The value of @code{height}, of course, can be found from @code{(apply
20045 'max numbers-list)}.)
20047 On the other hand, if the value of @code{height} is not a multiple of
20048 five, we want to reset the value to the next higher multiple of five.
20049 This is straightforward arithmetic using functions with which we are
20050 already familiar.  First, we divide the value of @code{height} by five
20051 to determine how many times five goes into the number.  Thus, five
20052 goes into twelve twice.  If we add one to this quotient and multiply by
20053 five, we will obtain the value of the next multiple of five that is
20054 larger than the height.  Five goes into twelve twice.  Add one to two,
20055 and multiply by five; the result is fifteen, which is the next multiple
20056 of five that is higher than twelve.  The Lisp expression for this is:
20058 @smallexample
20059 (* (1+ (/ height 5)) 5)
20060 @end smallexample
20062 @noindent
20063 For example, if you evaluate the following, the result is 15:
20065 @smallexample
20066 (* (1+ (/ 12 5)) 5)
20067 @end smallexample
20069 All through this discussion, we have been using `five' as the value
20070 for spacing labels on the Y axis; but we may want to use some other
20071 value.  For generality, we should replace `five' with a variable to
20072 which we can assign a value.  The best name I can think of for this
20073 variable is @code{Y-axis-label-spacing}.
20075 @need 1250
20076 Using this term, and an @code{if} expression, we produce the
20077 following:
20079 @smallexample
20080 @group
20081 (if (zerop (% height Y-axis-label-spacing))
20082     height
20083   ;; @r{else}
20084   (* (1+ (/ height Y-axis-label-spacing))
20085      Y-axis-label-spacing))
20086 @end group
20087 @end smallexample
20089 @noindent
20090 This expression returns the value of @code{height} itself if the height
20091 is an even multiple of the value of the @code{Y-axis-label-spacing} or
20092 else it computes and returns a value of @code{height} that is equal to
20093 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
20095 We can now include this expression in the @code{let} expression of the
20096 @code{print-graph} function (after first setting the value of
20097 @code{Y-axis-label-spacing}):
20098 @vindex Y-axis-label-spacing
20100 @smallexample
20101 @group
20102 (defvar Y-axis-label-spacing 5
20103   "Number of lines from one Y axis label to next.")
20104 @end group
20106 @group
20107 @dots{}
20108 (let* ((height (apply 'max numbers-list))
20109        (height-of-top-line
20110         (if (zerop (% height Y-axis-label-spacing))
20111             height
20112 @end group
20113 @group
20114           ;; @r{else}
20115           (* (1+ (/ height Y-axis-label-spacing))
20116              Y-axis-label-spacing)))
20117        (symbol-width (length graph-blank))))
20118 @dots{}
20119 @end group
20120 @end smallexample
20122 @noindent
20123 (Note use of the  @code{let*} function: the initial value of height is
20124 computed once by the @code{(apply 'max numbers-list)} expression and
20125 then the resulting value of  @code{height} is used to compute its
20126 final value.  @xref{fwd-para let, , The @code{let*} expression}, for
20127 more about @code{let*}.)
20129 @node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis
20130 @appendixsubsec Construct a Y Axis Element
20132 When we print the vertical axis, we want to insert strings such as
20133 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
20134 Moreover, we want the numbers and dashes to line up, so shorter
20135 numbers must be padded with leading spaces.  If some of the strings
20136 use two digit numbers, the strings with single digit numbers must
20137 include a leading blank space before the number.
20139 @findex number-to-string
20140 To figure out the length of the number, the @code{length} function is
20141 used.  But the @code{length} function works only with a string, not with
20142 a number.  So the number has to be converted from being a number to
20143 being a string.  This is done with the @code{number-to-string} function.
20144 For example,
20146 @smallexample
20147 @group
20148 (length (number-to-string 35))
20149      @result{} 2
20151 (length (number-to-string 100))
20152      @result{} 3
20153 @end group
20154 @end smallexample
20156 @noindent
20157 (@code{number-to-string} is also called @code{int-to-string}; you will
20158 see this alternative name in various sources.)
20160 In addition, in each label, each number is followed by a string such
20161 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
20162 This variable is defined with @code{defvar}:
20164 @vindex Y-axis-tic
20165 @smallexample
20166 @group
20167 (defvar Y-axis-tic " - "
20168    "String that follows number in a Y axis label.")
20169 @end group
20170 @end smallexample
20172 The length of the Y label is the sum of the length of the Y axis tic
20173 mark and the length of the number of the top of the graph.
20175 @smallexample
20176 (length (concat (number-to-string height) Y-axis-tic)))
20177 @end smallexample
20179 This value will be calculated by the @code{print-graph} function in
20180 its varlist as @code{full-Y-label-width} and passed on.  (Note that we
20181 did not think to include this in the varlist when we first proposed it.)
20183 To make a complete vertical axis label, a tic mark is concatenated
20184 with a number; and the two together may be preceded by one or more
20185 spaces depending on how long the number is.  The label consists of
20186 three parts: the (optional) leading spaces, the number, and the tic
20187 mark.  The function is passed the value of the number for the specific
20188 row, and the value of the width of the top line, which is calculated
20189 (just once) by @code{print-graph}.
20191 @smallexample
20192 @group
20193 (defun Y-axis-element (number full-Y-label-width)
20194   "Construct a NUMBERed label element.
20195 A numbered element looks like this `  5 - ',
20196 and is padded as needed so all line up with
20197 the element for the largest number."
20198 @end group
20199 @group
20200   (let* ((leading-spaces
20201          (- full-Y-label-width
20202             (length
20203              (concat (number-to-string number)
20204                      Y-axis-tic)))))
20205 @end group
20206 @group
20207     (concat
20208      (make-string leading-spaces ? )
20209      (number-to-string number)
20210      Y-axis-tic)))
20211 @end group
20212 @end smallexample
20214 The @code{Y-axis-element} function concatenates together the leading
20215 spaces, if any; the number, as a string; and the tic mark.
20217 To figure out how many leading spaces the label will need, the
20218 function subtracts the actual length of the label---the length of the
20219 number plus the length of the tic mark---from the desired label width.
20221 @findex make-string
20222 Blank spaces are inserted using the @code{make-string} function.  This
20223 function takes two arguments: the first tells it how long the string
20224 will be and the second is a symbol for the character to insert, in a
20225 special format.  The format is a question mark followed by a blank
20226 space, like this, @samp{? }.  @xref{Character Type, , Character Type,
20227 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
20228 syntax for characters.  (Of course, you might want to replace the
20229 blank space by some other character @dots{}  You know what to do.)
20231 The @code{number-to-string} function is used in the concatenation
20232 expression, to convert the number to a string that is concatenated
20233 with the leading spaces and the tic mark.
20235 @node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis
20236 @appendixsubsec Create a Y Axis Column
20238 The preceding functions provide all the tools needed to construct a
20239 function that generates a list of numbered and blank strings to insert
20240 as the label for the vertical axis:
20242 @findex Y-axis-column
20243 @smallexample
20244 @group
20245 (defun Y-axis-column (height width-of-label)
20246   "Construct list of Y axis labels and blank strings.
20247 For HEIGHT of line above base and WIDTH-OF-LABEL."
20248   (let (Y-axis)
20249 @group
20250 @end group
20251     (while (> height 1)
20252       (if (zerop (% height Y-axis-label-spacing))
20253           ;; @r{Insert label.}
20254           (setq Y-axis
20255                 (cons
20256                  (Y-axis-element height width-of-label)
20257                  Y-axis))
20258 @group
20259 @end group
20260         ;; @r{Else, insert blanks.}
20261         (setq Y-axis
20262               (cons
20263                (make-string width-of-label ? )
20264                Y-axis)))
20265       (setq height (1- height)))
20266     ;; @r{Insert base line.}
20267     (setq Y-axis
20268           (cons (Y-axis-element 1 width-of-label) Y-axis))
20269     (nreverse Y-axis)))
20270 @end group
20271 @end smallexample
20273 In this function, we start with the value of @code{height} and
20274 repetitively subtract one from its value.  After each subtraction, we
20275 test to see whether the value is an integral multiple of the
20276 @code{Y-axis-label-spacing}.  If it is, we construct a numbered label
20277 using the @code{Y-axis-element} function; if not, we construct a
20278 blank label using the @code{make-string} function.  The base line
20279 consists of the number one followed by a tic mark.
20281 @need 2000
20282 @node print-Y-axis Penultimate,  , Y-axis-column, print-Y-axis
20283 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
20285 The list constructed by the @code{Y-axis-column} function is passed to
20286 the @code{print-Y-axis} function, which inserts the list as a column.
20288 @findex print-Y-axis
20289 @smallexample
20290 @group
20291 (defun print-Y-axis (height full-Y-label-width)
20292   "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
20293 Height must be the maximum height of the graph.
20294 Full width is the width of the highest label element."
20295 ;; Value of height and full-Y-label-width
20296 ;; are passed by `print-graph'.
20297 @end group
20298 @group
20299   (let ((start (point)))
20300     (insert-rectangle
20301      (Y-axis-column height full-Y-label-width))
20302     ;; @r{Place point ready for inserting graph.}
20303     (goto-char start)
20304     ;; @r{Move point forward by value of} full-Y-label-width
20305     (forward-char full-Y-label-width)))
20306 @end group
20307 @end smallexample
20309 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
20310 insert the Y axis labels created by the @code{Y-axis-column} function.
20311 In addition, it places point at the correct position for printing the body of
20312 the graph.
20314 You can test @code{print-Y-axis}:
20316 @enumerate
20317 @item
20318 Install
20320 @smallexample
20321 @group
20322 Y-axis-label-spacing
20323 Y-axis-tic
20324 Y-axis-element
20325 Y-axis-column
20326 print-Y-axis
20327 @end group
20328 @end smallexample
20330 @item
20331 Copy the following expression:
20333 @smallexample
20334 (print-Y-axis 12 5)
20335 @end smallexample
20337 @item
20338 Switch to the @file{*scratch*} buffer and place the cursor where you
20339 want the axis labels to start.
20341 @item
20342 Type @kbd{M-:} (@code{eval-expression}).
20344 @item
20345 Yank the @code{graph-body-print} expression into the minibuffer
20346 with @kbd{C-y} (@code{yank)}.
20348 @item
20349 Press @key{RET} to evaluate the expression.
20350 @end enumerate
20352 Emacs will print labels vertically, the top one being @w{@samp{10 -@w{
20353 }}}.  (The @code{print-graph} function will pass the value of
20354 @code{height-of-top-line}, which in this case will end up as 15,
20355 thereby getting rid of what might appear as a bug.)
20357 @need 2000
20358 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph
20359 @appendixsec The @code{print-X-axis} Function
20360 @cindex Axis, print horizontal
20361 @cindex X axis printing
20362 @cindex Print horizontal axis
20363 @cindex Horizontal axis printing
20365 X axis labels are much like Y axis labels, except that the ticks are on a
20366 line above the numbers.  Labels should look like this:
20368 @smallexample
20369 @group
20370     |   |    |    |
20371     1   5   10   15
20372 @end group
20373 @end smallexample
20375 The first tic is under the first column of the graph and is preceded by
20376 several blank spaces.  These spaces provide room in rows above for the Y
20377 axis labels.  The second, third, fourth, and subsequent ticks are all
20378 spaced equally, according to the value of @code{X-axis-label-spacing}.
20380 The second row of the X axis consists of numbers, preceded by several
20381 blank spaces and also separated according to the value of the variable
20382 @code{X-axis-label-spacing}.
20384 The value of the variable @code{X-axis-label-spacing} should itself be
20385 measured in units of @code{symbol-width}, since you may want to change
20386 the width of the symbols that you are using to print the body of the
20387 graph without changing the ways the graph is labelled.
20389 @menu
20390 * Similarities differences::    Much like @code{print-Y-axis}, but not exactly.
20391 * X Axis Tic Marks::            Create tic marks for the horizontal axis.
20392 @end menu
20394 @node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
20395 @ifnottex
20396 @unnumberedsubsec Similarities and differences
20397 @end ifnottex
20399 The @code{print-X-axis} function is constructed in more or less the
20400 same fashion as the @code{print-Y-axis} function except that it has
20401 two lines: the line of tic marks and the numbers.  We will write a
20402 separate function to print each line and then combine them within the
20403 @code{print-X-axis} function.
20405 This is a three step process:
20407 @enumerate
20408 @item
20409 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
20411 @item
20412 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
20414 @item
20415 Write a function to print both lines, the @code{print-X-axis} function,
20416 using @code{print-X-axis-tic-line} and
20417 @code{print-X-axis-numbered-line}.
20418 @end enumerate
20420 @node X Axis Tic Marks,  , Similarities differences, print-X-axis
20421 @appendixsubsec X Axis Tic Marks
20423 The first function should print the X axis tic marks.  We must specify
20424 the tic marks themselves and their spacing:
20426 @smallexample
20427 @group
20428 (defvar X-axis-label-spacing
20429   (if (boundp 'graph-blank)
20430       (* 5 (length graph-blank)) 5)
20431   "Number of units from one X axis label to next.")
20432 @end group
20433 @end smallexample
20435 @noindent
20436 (Note that the value of @code{graph-blank} is set by another
20437 @code{defvar}.  The @code{boundp} predicate checks whether it has
20438 already been set; @code{boundp} returns @code{nil} if it has not.  If
20439 @code{graph-blank} were unbound and we did not use this conditional
20440 construction, in a recent GNU Emacs, we would enter the debugger and
20441 see an error message saying @samp{@w{Debugger entered--Lisp error:}
20442 @w{(void-variable graph-blank)}}.)
20444 @need 1200
20445 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
20447 @smallexample
20448 @group
20449 (defvar X-axis-tic-symbol "|"
20450   "String to insert to point to a column in X axis.")
20451 @end group
20452 @end smallexample
20454 @need 1250
20455 The goal is to make a line that looks like this:
20457 @smallexample
20458        |   |    |    |
20459 @end smallexample
20461 The first tic is indented so that it is under the first column, which is
20462 indented to provide space for the Y axis labels.
20464 A tic element consists of the blank spaces that stretch from one tic to
20465 the next plus a tic symbol.  The number of blanks is determined by the
20466 width of the tic symbol and the @code{X-axis-label-spacing}.
20468 @need 1250
20469 The code looks like this:
20471 @smallexample
20472 @group
20473 ;;; X-axis-tic-element
20474 @dots{}
20475 (concat
20476  (make-string
20477   ;; @r{Make a string of blanks.}
20478   (-  (* symbol-width X-axis-label-spacing)
20479       (length X-axis-tic-symbol))
20480   ? )
20481  ;; @r{Concatenate blanks with tic symbol.}
20482  X-axis-tic-symbol)
20483 @dots{}
20484 @end group
20485 @end smallexample
20487 Next, we determine how many blanks are needed to indent the first tic
20488 mark to the first column of the graph.  This uses the value of
20489 @code{full-Y-label-width} passed it by the @code{print-graph} function.
20491 @need 1250
20492 The code to make @code{X-axis-leading-spaces}
20493 looks like this:
20495 @smallexample
20496 @group
20497 ;; X-axis-leading-spaces
20498 @dots{}
20499 (make-string full-Y-label-width ? )
20500 @dots{}
20501 @end group
20502 @end smallexample
20504 We also need to determine the length of the horizontal axis, which is
20505 the length of the numbers list, and the number of ticks in the horizontal
20506 axis:
20508 @smallexample
20509 @group
20510 ;; X-length
20511 @dots{}
20512 (length numbers-list)
20513 @end group
20515 @group
20516 ;; tic-width
20517 @dots{}
20518 (* symbol-width X-axis-label-spacing)
20519 @end group
20521 @group
20522 ;; number-of-X-ticks
20523 (if (zerop (% (X-length tic-width)))
20524     (/ (X-length tic-width))
20525   (1+ (/ (X-length tic-width))))
20526 @end group
20527 @end smallexample
20529 @need 1250
20530 All this leads us directly to the function for printing the X axis tic line:
20532 @findex print-X-axis-tic-line
20533 @smallexample
20534 @group
20535 (defun print-X-axis-tic-line
20536   (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
20537   "Print ticks for X axis."
20538     (insert X-axis-leading-spaces)
20539     (insert X-axis-tic-symbol)  ; @r{Under first column.}
20540 @end group
20541 @group
20542     ;; @r{Insert second tic in the right spot.}
20543     (insert (concat
20544              (make-string
20545               (-  (* symbol-width X-axis-label-spacing)
20546                   ;; @r{Insert white space up to second tic symbol.}
20547                   (* 2 (length X-axis-tic-symbol)))
20548               ? )
20549              X-axis-tic-symbol))
20550 @end group
20551 @group
20552     ;; @r{Insert remaining ticks.}
20553     (while (> number-of-X-tics 1)
20554       (insert X-axis-tic-element)
20555       (setq number-of-X-tics (1- number-of-X-tics))))
20556 @end group
20557 @end smallexample
20559 The line of numbers is equally straightforward:
20561 @need 1250
20562 First, we create a numbered element with blank spaces before each number:
20564 @findex X-axis-element
20565 @smallexample
20566 @group
20567 (defun X-axis-element (number)
20568   "Construct a numbered X axis element."
20569   (let ((leading-spaces
20570          (-  (* symbol-width X-axis-label-spacing)
20571              (length (number-to-string number)))))
20572     (concat (make-string leading-spaces ? )
20573             (number-to-string number))))
20574 @end group
20575 @end smallexample
20577 Next, we create the function to print the numbered line, starting with
20578 the number ``1'' under the first column:
20580 @findex print-X-axis-numbered-line
20581 @smallexample
20582 @group
20583 (defun print-X-axis-numbered-line
20584   (number-of-X-tics X-axis-leading-spaces)
20585   "Print line of X-axis numbers"
20586   (let ((number X-axis-label-spacing))
20587     (insert X-axis-leading-spaces)
20588     (insert "1")
20589 @end group
20590 @group
20591     (insert (concat
20592              (make-string
20593               ;; @r{Insert white space up to next number.}
20594               (-  (* symbol-width X-axis-label-spacing) 2)
20595               ? )
20596              (number-to-string number)))
20597 @end group
20598 @group
20599     ;; @r{Insert remaining numbers.}
20600     (setq number (+ number X-axis-label-spacing))
20601     (while (> number-of-X-tics 1)
20602       (insert (X-axis-element number))
20603       (setq number (+ number X-axis-label-spacing))
20604       (setq number-of-X-tics (1- number-of-X-tics)))))
20605 @end group
20606 @end smallexample
20608 Finally, we need to write the @code{print-X-axis} that uses
20609 @code{print-X-axis-tic-line} and
20610 @code{print-X-axis-numbered-line}.
20612 The function must determine the local values of the variables used by both
20613 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
20614 then it must call them.  Also, it must print the carriage return that
20615 separates the two lines.
20617 The function consists of a varlist that specifies five local variables,
20618 and calls to each of the two line printing functions:
20620 @findex print-X-axis
20621 @smallexample
20622 @group
20623 (defun print-X-axis (numbers-list)
20624   "Print X axis labels to length of NUMBERS-LIST."
20625   (let* ((leading-spaces
20626           (make-string full-Y-label-width ? ))
20627 @end group
20628 @group
20629        ;; symbol-width @r{is provided by} graph-body-print
20630        (tic-width (* symbol-width X-axis-label-spacing))
20631        (X-length (length numbers-list))
20632 @end group
20633 @group
20634        (X-tic
20635         (concat
20636          (make-string
20637 @end group
20638 @group
20639           ;; @r{Make a string of blanks.}
20640           (-  (* symbol-width X-axis-label-spacing)
20641               (length X-axis-tic-symbol))
20642           ? )
20643 @end group
20644 @group
20645          ;; @r{Concatenate blanks with tic symbol.}
20646          X-axis-tic-symbol))
20647 @end group
20648 @group
20649        (tic-number
20650         (if (zerop (% X-length tic-width))
20651             (/ X-length tic-width)
20652           (1+ (/ X-length tic-width)))))
20653 @end group
20654 @group
20655     (print-X-axis-tic-line tic-number leading-spaces X-tic)
20656     (insert "\n")
20657     (print-X-axis-numbered-line tic-number leading-spaces)))
20658 @end group
20659 @end smallexample
20661 @need 1250
20662 You can test @code{print-X-axis}:
20664 @enumerate
20665 @item
20666 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
20667 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
20668 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
20670 @item
20671 Copy the following expression:
20673 @smallexample
20674 @group
20675 (progn
20676  (let ((full-Y-label-width 5)
20677        (symbol-width 1))
20678    (print-X-axis
20679     '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
20680 @end group
20681 @end smallexample
20683 @item
20684 Switch to the @file{*scratch*} buffer and place the cursor where you
20685 want the axis labels to start.
20687 @item
20688 Type @kbd{M-:} (@code{eval-expression}).
20690 @item
20691 Yank the test expression into the minibuffer
20692 with @kbd{C-y} (@code{yank)}.
20694 @item
20695 Press @key{RET} to evaluate the expression.
20696 @end enumerate
20698 @need 1250
20699 Emacs will print the horizontal axis like this:
20700 @sp 1
20702 @smallexample
20703 @group
20704      |   |    |    |    |
20705      1   5   10   15   20
20706 @end group
20707 @end smallexample
20709 @node Print Whole Graph,  , print-X-axis, Full Graph
20710 @appendixsec Printing the Whole Graph
20711 @cindex Printing the whole graph
20712 @cindex Whole graph printing
20713 @cindex Graph, printing all
20715 Now we are nearly ready to print the whole graph.
20717 The function to print the graph with the proper labels follows the
20718 outline we created earlier (@pxref{Full Graph, , A Graph with Labelled
20719 Axes}), but with additions.
20721 @need 1250
20722 Here is the outline:
20724 @smallexample
20725 @group
20726 (defun print-graph (numbers-list)
20727   "@var{documentation}@dots{}"
20728   (let ((height  @dots{}
20729         @dots{}))
20730 @end group
20731 @group
20732     (print-Y-axis height @dots{} )
20733     (graph-body-print numbers-list)
20734     (print-X-axis @dots{} )))
20735 @end group
20736 @end smallexample
20738 @menu
20739 * The final version::           A few changes.
20740 * Test print-graph::            Run a short test.
20741 * Graphing words in defuns::    Executing the final code.
20742 * lambda::                      How to write an anonymous function.
20743 * mapcar::                      Apply a function to elements of a list.
20744 * Another Bug::                 Yet another bug @dots{} most insidious.
20745 * Final printed graph::         The graph itself!
20746 @end menu
20748 @node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
20749 @ifnottex
20750 @unnumberedsubsec Changes for the Final Version
20751 @end ifnottex
20753 The final version is different from what we planned in two ways:
20754 first, it contains additional values calculated once in the varlist;
20755 second, it carries an option to specify the labels' increment per row.
20756 This latter feature turns out to be essential; otherwise, a graph may
20757 have more rows than fit on a display or on a sheet of paper.
20759 @need 1500
20760 This new feature requires a change to the @code{Y-axis-column}
20761 function, to add @code{vertical-step} to it.  The function looks like
20762 this:
20764 @findex Y-axis-column @r{Final version.}
20765 @smallexample
20766 @group
20767 ;;; @r{Final version.}
20768 (defun Y-axis-column
20769   (height width-of-label &optional vertical-step)
20770   "Construct list of labels for Y axis.
20771 HEIGHT is maximum height of graph.
20772 WIDTH-OF-LABEL is maximum width of label.
20773 VERTICAL-STEP, an option, is a positive integer
20774 that specifies how much a Y axis label increments
20775 for each line.  For example, a step of 5 means
20776 that each line is five units of the graph."
20777 @end group
20778 @group
20779   (let (Y-axis
20780         (number-per-line (or vertical-step 1)))
20781     (while (> height 1)
20782       (if (zerop (% height Y-axis-label-spacing))
20783 @end group
20784 @group
20785           ;; @r{Insert label.}
20786           (setq Y-axis
20787                 (cons
20788                  (Y-axis-element
20789                   (* height number-per-line)
20790                   width-of-label)
20791                  Y-axis))
20792 @end group
20793 @group
20794         ;; @r{Else, insert blanks.}
20795         (setq Y-axis
20796               (cons
20797                (make-string width-of-label ? )
20798                Y-axis)))
20799       (setq height (1- height)))
20800 @end group
20801 @group
20802     ;; @r{Insert base line.}
20803     (setq Y-axis (cons (Y-axis-element
20804                         (or vertical-step 1)
20805                         width-of-label)
20806                        Y-axis))
20807     (nreverse Y-axis)))
20808 @end group
20809 @end smallexample
20811 The values for the maximum height of graph and the width of a symbol
20812 are computed by @code{print-graph} in its @code{let} expression; so
20813 @code{graph-body-print} must be changed to accept them.
20815 @findex graph-body-print @r{Final version.}
20816 @smallexample
20817 @group
20818 ;;; @r{Final version.}
20819 (defun graph-body-print (numbers-list height symbol-width)
20820   "Print a bar graph of the NUMBERS-LIST.
20821 The numbers-list consists of the Y-axis values.
20822 HEIGHT is maximum height of graph.
20823 SYMBOL-WIDTH is number of each column."
20824 @end group
20825 @group
20826   (let (from-position)
20827     (while numbers-list
20828       (setq from-position (point))
20829       (insert-rectangle
20830        (column-of-graph height (car numbers-list)))
20831       (goto-char from-position)
20832       (forward-char symbol-width)
20833 @end group
20834 @group
20835       ;; @r{Draw graph column by column.}
20836       (sit-for 0)
20837       (setq numbers-list (cdr numbers-list)))
20838     ;; @r{Place point for X axis labels.}
20839     (forward-line height)
20840     (insert "\n")))
20841 @end group
20842 @end smallexample
20844 @need 1250
20845 Finally, the code for the @code{print-graph} function:
20847 @findex print-graph @r{Final version.}
20848 @smallexample
20849 @group
20850 ;;; @r{Final version.}
20851 (defun print-graph
20852   (numbers-list &optional vertical-step)
20853   "Print labelled bar graph of the NUMBERS-LIST.
20854 The numbers-list consists of the Y-axis values.
20855 @end group
20857 @group
20858 Optionally, VERTICAL-STEP, a positive integer,
20859 specifies how much a Y axis label increments for
20860 each line.  For example, a step of 5 means that
20861 each row is five units."
20862 @end group
20863 @group
20864   (let* ((symbol-width (length graph-blank))
20865          ;; @code{height} @r{is both the largest number}
20866          ;; @r{and the number with the most digits.}
20867          (height (apply 'max numbers-list))
20868 @end group
20869 @group
20870          (height-of-top-line
20871           (if (zerop (% height Y-axis-label-spacing))
20872               height
20873             ;; @r{else}
20874             (* (1+ (/ height Y-axis-label-spacing))
20875                Y-axis-label-spacing)))
20876 @end group
20877 @group
20878          (vertical-step (or vertical-step 1))
20879          (full-Y-label-width
20880           (length
20881 @end group
20882 @group
20883            (concat
20884             (number-to-string
20885              (* height-of-top-line vertical-step))
20886             Y-axis-tic))))
20887 @end group
20889 @group
20890     (print-Y-axis
20891      height-of-top-line full-Y-label-width vertical-step)
20892 @end group
20893 @group
20894     (graph-body-print
20895      numbers-list height-of-top-line symbol-width)
20896     (print-X-axis numbers-list)))
20897 @end group
20898 @end smallexample
20900 @node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph
20901 @appendixsubsec Testing @code{print-graph}
20903 @need 1250
20904 We can test the @code{print-graph} function with a short list of numbers:
20906 @enumerate
20907 @item
20908 Install the final versions of @code{Y-axis-column},
20909 @code{graph-body-print}, and @code{print-graph} (in addition to the
20910 rest of the code.)
20912 @item
20913 Copy the following expression:
20915 @smallexample
20916 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
20917 @end smallexample
20919 @item
20920 Switch to the @file{*scratch*} buffer and place the cursor where you
20921 want the axis labels to start.
20923 @item
20924 Type @kbd{M-:} (@code{eval-expression}).
20926 @item
20927 Yank the test expression into the minibuffer
20928 with @kbd{C-y} (@code{yank)}.
20930 @item
20931 Press @key{RET} to evaluate the expression.
20932 @end enumerate
20934 @need 1250
20935 Emacs will print a graph that looks like this:
20937 @smallexample
20938 @group
20939 10 -
20942          *
20943         **   *
20944  5 -   ****  *
20945        **** ***
20946      * *********
20947      ************
20948  1 - *************
20950      |   |    |    |
20951      1   5   10   15
20952 @end group
20953 @end smallexample
20955 @need 1200
20956 On the other hand, if you pass @code{print-graph} a
20957 @code{vertical-step} value of 2, by evaluating this expression:
20959 @smallexample
20960 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
20961 @end smallexample
20963 @need 1250
20964 @noindent
20965 The graph looks like this:
20967 @smallexample
20968 @group
20969 20 -
20972          *
20973         **   *
20974 10 -   ****  *
20975        **** ***
20976      * *********
20977      ************
20978  2 - *************
20980      |   |    |    |
20981      1   5   10   15
20982 @end group
20983 @end smallexample
20985 @noindent
20986 (A question: is the `2' on the bottom of the vertical axis a bug or a
20987 feature?  If you think it is a bug, and should be a `1' instead, (or
20988 even a `0'), you can modify the sources.)
20990 @node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph
20991 @appendixsubsec Graphing Numbers of Words and Symbols
20993 Now for the graph for which all this code was written: a graph that
20994 shows how many function definitions contain fewer than 10 words and
20995 symbols, how many contain between 10 and 19 words and symbols, how
20996 many contain between 20 and 29 words and symbols, and so on.
20998 This is a multi-step process.  First make sure you have loaded all the
20999 requisite code.
21001 @need 1500
21002 It is a good idea to reset the value of @code{top-of-ranges} in case
21003 you have set it to some different value.  You can evaluate the
21004 following:
21006 @smallexample
21007 @group
21008 (setq top-of-ranges
21009  '(10  20  30  40  50
21010    60  70  80  90 100
21011   110 120 130 140 150
21012   160 170 180 190 200
21013   210 220 230 240 250
21014   260 270 280 290 300)
21015 @end group
21016 @end smallexample
21018 @noindent
21019 Next create a list of the number of words and symbols in each range.
21021 @need 1500
21022 @noindent
21023 Evaluate the following:
21025 @smallexample
21026 @group
21027 (setq list-for-graph
21028        (defuns-per-range
21029          (sort
21030           (recursive-lengths-list-many-files
21031            (directory-files "/usr/local/emacs/lisp"
21032                             t ".+el$"))
21033           '<)
21034          top-of-ranges))
21035 @end group
21036 @end smallexample
21038 @noindent
21039 On my old machine, this took about an hour.  It looked though 303 Lisp
21040 files in my copy of Emacs version 19.23.  After all that computing,
21041 the @code{list-for-graph} had this value:
21043 @smallexample
21044 @group
21045 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
21046 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
21047 @end group
21048 @end smallexample
21050 @noindent
21051 This means that my copy of Emacs had 537 function definitions with
21052 fewer than 10 words or symbols in them, 1,027 function definitions
21053 with 10 to 19 words or symbols in them, 955 function definitions with
21054 20 to 29 words or symbols in them, and so on.
21056 Clearly, just by looking at this list we can see that most function
21057 definitions contain ten to thirty words and symbols.
21059 Now for printing.  We do @emph{not} want to print a graph that is
21060 1,030 lines high @dots{}  Instead, we should print a graph that is
21061 fewer than twenty-five lines high.  A graph that height can be
21062 displayed on almost any monitor, and easily printed on a sheet of paper.
21064 This means that each value in @code{list-for-graph} must be reduced to
21065 one-fiftieth its present value.
21067 Here is a short function to do just that, using two functions we have
21068 not yet seen, @code{mapcar} and @code{lambda}.
21070 @smallexample
21071 @group
21072 (defun one-fiftieth (full-range)
21073   "Return list, each number one-fiftieth of previous."
21074  (mapcar '(lambda (arg) (/ arg 50)) full-range))
21075 @end group
21076 @end smallexample
21078 @node lambda, mapcar, Graphing words in defuns, Print Whole Graph
21079 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
21080 @cindex Anonymous function
21081 @findex lambda
21083 @code{lambda} is the symbol for an anonymous function, a function
21084 without a name.  Every time you use an anonymous function, you need to
21085 include its whole body.
21087 @need 1250
21088 @noindent
21089 Thus,
21091 @smallexample
21092 (lambda (arg) (/ arg 50))
21093 @end smallexample
21095 @noindent
21096 is a function definition that says `return the value resulting from
21097 dividing whatever is passed to me as @code{arg} by 50'.
21099 @need 1200
21100 Earlier, for example, we had a function @code{multiply-by-seven}; it
21101 multiplied its argument by 7.  This function is similar, except it
21102 divides its argument by 50; and, it has no name.  The anonymous
21103 equivalent of @code{multiply-by-seven} is:
21105 @smallexample
21106 (lambda (number) (* 7 number))
21107 @end smallexample
21109 @noindent
21110 (@xref{defun, ,  The @code{defun} Special Form}.)
21112 @need 1250
21113 @noindent
21114 If we want to multiply 3 by 7, we can write:
21116 @c !!! Clear print-postscript-figures if the computer formatting this
21117 @c     document is too small and cannot handle all the diagrams and figures.
21118 @c clear print-postscript-figures
21119 @c set print-postscript-figures
21120 @c lambda example diagram #1
21121 @ifnottex
21122 @smallexample
21123 @group
21124 (multiply-by-seven 3)
21125  \_______________/ ^
21126          |         |
21127       function  argument
21128 @end group
21129 @end smallexample
21130 @end ifnottex
21131 @ifset print-postscript-figures
21132 @sp 1
21133 @tex
21134 @center @image{lambda-1}
21135 %%%% old method of including an image
21136 % \input /usr/local/lib/tex/inputs/psfig.tex
21137 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
21138 % \catcode`\@=0 %
21139 @end tex
21140 @sp 1
21141 @end ifset
21142 @ifclear print-postscript-figures
21143 @iftex
21144 @smallexample
21145 @group
21146 (multiply-by-seven 3)
21147  \_______________/ ^
21148          |         |
21149       function  argument
21150 @end group
21151 @end smallexample
21152 @end iftex
21153 @end ifclear
21155 @noindent
21156 This expression returns 21.
21158 @need 1250
21159 @noindent
21160 Similarly, we can write:
21162 @c lambda example diagram #2
21163 @ifnottex
21164 @smallexample
21165 @group
21166 ((lambda (number) (* 7 number)) 3)
21167  \____________________________/ ^
21168                |                |
21169       anonymous function     argument
21170 @end group
21171 @end smallexample
21172 @end ifnottex
21173 @ifset print-postscript-figures
21174 @sp 1
21175 @tex
21176 @center @image{lambda-2}
21177 %%%% old method of including an image
21178 % \input /usr/local/lib/tex/inputs/psfig.tex
21179 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
21180 % \catcode`\@=0 %
21181 @end tex
21182 @sp 1
21183 @end ifset
21184 @ifclear print-postscript-figures
21185 @iftex
21186 @smallexample
21187 @group
21188 ((lambda (number) (* 7 number)) 3)
21189  \____________________________/ ^
21190                |                |
21191       anonymous function     argument
21192 @end group
21193 @end smallexample
21194 @end iftex
21195 @end ifclear
21197 @need 1250
21198 @noindent
21199 If we want to divide 100 by 50, we can write:
21201 @c lambda example diagram #3
21202 @ifnottex
21203 @smallexample
21204 @group
21205 ((lambda (arg) (/ arg 50)) 100)
21206  \______________________/  \_/
21207              |              |
21208     anonymous function   argument
21209 @end group
21210 @end smallexample
21211 @end ifnottex
21212 @ifset print-postscript-figures
21213 @sp 1
21214 @tex
21215 @center @image{lambda-3}
21216 %%%% old method of including an image
21217 % \input /usr/local/lib/tex/inputs/psfig.tex
21218 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
21219 % \catcode`\@=0 %
21220 @end tex
21221 @sp 1
21222 @end ifset
21223 @ifclear print-postscript-figures
21224 @iftex
21225 @smallexample
21226 @group
21227 ((lambda (arg) (/ arg 50)) 100)
21228  \______________________/  \_/
21229              |              |
21230     anonymous function   argument
21231 @end group
21232 @end smallexample
21233 @end iftex
21234 @end ifclear
21236 @noindent
21237 This expression returns 2.  The 100 is passed to the function, which
21238 divides that number by 50.
21240 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
21241 Lisp Reference Manual}, for more about @code{lambda}.  Lisp and lambda
21242 expressions derive from the Lambda Calculus.
21244 @node mapcar, Another Bug, lambda, Print Whole Graph
21245 @appendixsubsec The @code{mapcar} Function
21246 @findex mapcar
21248 @code{mapcar} is a function that calls its first argument with each
21249 element of its second argument, in turn.  The second argument must be
21250 a sequence.
21252 The @samp{map} part of the name comes from the mathematical phrase,
21253 `mapping over a domain', meaning to apply a function to each of the
21254 elements in a domain.  The mathematical phrase is based on the
21255 metaphor of a surveyor walking, one step at a time, over an area he is
21256 mapping.  And @samp{car}, of course, comes from the Lisp notion of the
21257 first of a list.
21259 @need 1250
21260 @noindent
21261 For example,
21263 @smallexample
21264 @group
21265 (mapcar '1+ '(2 4 6))
21266      @result{} (3 5 7)
21267 @end group
21268 @end smallexample
21270 @noindent
21271 The function @code{1+} which adds one to its argument, is executed on
21272 @emph{each} element of the list, and a new list is returned.
21274 Contrast this with @code{apply}, which applies its first argument to
21275 all the remaining.
21276 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
21277 @code{apply}.)
21279 @need 1250
21280 In the definition of @code{one-fiftieth}, the first argument is the
21281 anonymous function:
21283 @smallexample
21284 (lambda (arg) (/ arg 50))
21285 @end smallexample
21287 @noindent
21288 and the second argument is @code{full-range}, which will be bound to
21289 @code{list-for-graph}.
21291 @need 1250
21292 The whole expression looks like this:
21294 @smallexample
21295 (mapcar '(lambda (arg) (/ arg 50)) full-range))
21296 @end smallexample
21298 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
21299 Lisp Reference Manual}, for more about @code{mapcar}.
21301 Using the @code{one-fiftieth} function, we can generate a list in
21302 which each element is one-fiftieth the size of the corresponding
21303 element in @code{list-for-graph}.
21305 @smallexample
21306 @group
21307 (setq fiftieth-list-for-graph
21308       (one-fiftieth list-for-graph))
21309 @end group
21310 @end smallexample
21312 @need 1250
21313 The resulting list looks like this:
21315 @smallexample
21316 @group
21317 (10 20 19 15 11 9 6 5 4 3 3 2 2
21318 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
21319 @end group
21320 @end smallexample
21322 @noindent
21323 This, we are almost ready to print!  (We also notice the loss of
21324 information: many of the higher ranges are 0, meaning that fewer than
21325 50 defuns had that many words or symbols---but not necessarily meaning
21326 that none had that many words or symbols.)
21328 @node Another Bug, Final printed graph, mapcar, Print Whole Graph
21329 @appendixsubsec Another Bug @dots{} Most Insidious
21330 @cindex Bug, most insidious type
21331 @cindex Insidious type of bug
21333 I said `almost ready to print'!  Of course, there is a bug in the
21334 @code{print-graph} function @dots{}  It has a @code{vertical-step}
21335 option, but not a @code{horizontal-step} option.  The
21336 @code{top-of-range} scale goes from 10 to 300 by tens.  But the
21337 @code{print-graph} function will print only by ones.
21339 This is a classic example of what some consider the most insidious
21340 type of bug, the bug of omission.  This is not the kind of bug you can
21341 find by studying the code, for it is not in the code; it is an omitted
21342 feature.  Your best actions are to try your program early and often;
21343 and try to arrange, as much as you can, to write code that is easy to
21344 understand and easy to change.  Try to be aware, whenever you can,
21345 that whatever you have written, @emph{will} be rewritten, if not soon,
21346 eventually.  A hard maxim to follow.
21348 It is the @code{print-X-axis-numbered-line} function that needs the
21349 work; and then the @code{print-X-axis} and the @code{print-graph}
21350 functions need to be adapted.  Not much needs to be done; there is one
21351 nicety: the numbers ought to line up under the tic marks.  This takes
21352 a little thought.
21354 @need 1250
21355 Here is the corrected @code{print-X-axis-numbered-line}:
21357 @smallexample
21358 @group
21359 (defun print-X-axis-numbered-line
21360   (number-of-X-tics X-axis-leading-spaces
21361    &optional horizontal-step)
21362   "Print line of X-axis numbers"
21363   (let ((number X-axis-label-spacing)
21364         (horizontal-step (or horizontal-step 1)))
21365 @end group
21366 @group
21367     (insert X-axis-leading-spaces)
21368     ;; @r{Delete extra leading spaces.}
21369     (delete-char
21370      (- (1-
21371          (length (number-to-string horizontal-step)))))
21372     (insert (concat
21373              (make-string
21374 @end group
21375 @group
21376               ;; @r{Insert white space.}
21377               (-  (* symbol-width
21378                      X-axis-label-spacing)
21379                   (1-
21380                    (length
21381                     (number-to-string horizontal-step)))
21382                   2)
21383               ? )
21384              (number-to-string
21385               (* number horizontal-step))))
21386 @end group
21387 @group
21388     ;; @r{Insert remaining numbers.}
21389     (setq number (+ number X-axis-label-spacing))
21390     (while (> number-of-X-tics 1)
21391       (insert (X-axis-element
21392                (* number horizontal-step)))
21393       (setq number (+ number X-axis-label-spacing))
21394       (setq number-of-X-tics (1- number-of-X-tics)))))
21395 @end group
21396 @end smallexample
21398 @need 1500
21399 If you are reading this in Info, you can see the new versions of
21400 @code{print-X-axis} @code{print-graph} and evaluate them.  If you are
21401 reading this in a printed book, you can see the changed lines here
21402 (the full text is too much to print).
21404 @iftex
21405 @smallexample
21406 @group
21407 (defun print-X-axis (numbers-list horizontal-step)
21408   @dots{}
21409     (print-X-axis-numbered-line
21410      tic-number leading-spaces horizontal-step))
21411 @end group
21412 @end smallexample
21414 @smallexample
21415 @group
21416 (defun print-graph
21417   (numbers-list
21418    &optional vertical-step horizontal-step)
21419   @dots{}
21420     (print-X-axis numbers-list horizontal-step))
21421 @end group
21422 @end smallexample
21423 @end iftex
21425 @ifnottex
21426 @smallexample
21427 @group
21428 (defun print-X-axis (numbers-list horizontal-step)
21429   "Print X axis labels to length of NUMBERS-LIST.
21430 Optionally, HORIZONTAL-STEP, a positive integer,
21431 specifies how much an X  axis label increments for
21432 each column."
21433 @end group
21434 @group
21435 ;; Value of symbol-width and full-Y-label-width
21436 ;; are passed by `print-graph'.
21437   (let* ((leading-spaces
21438           (make-string full-Y-label-width ? ))
21439        ;; symbol-width @r{is provided by} graph-body-print
21440        (tic-width (* symbol-width X-axis-label-spacing))
21441        (X-length (length numbers-list))
21442 @end group
21443 @group
21444        (X-tic
21445         (concat
21446          (make-string
21447           ;; @r{Make a string of blanks.}
21448           (-  (* symbol-width X-axis-label-spacing)
21449               (length X-axis-tic-symbol))
21450           ? )
21451 @end group
21452 @group
21453          ;; @r{Concatenate blanks with tic symbol.}
21454          X-axis-tic-symbol))
21455        (tic-number
21456         (if (zerop (% X-length tic-width))
21457             (/ X-length tic-width)
21458           (1+ (/ X-length tic-width)))))
21459 @end group
21461 @group
21462     (print-X-axis-tic-line
21463      tic-number leading-spaces X-tic)
21464     (insert "\n")
21465     (print-X-axis-numbered-line
21466      tic-number leading-spaces horizontal-step)))
21467 @end group
21468 @end smallexample
21470 @smallexample
21471 @group
21472 (defun print-graph
21473   (numbers-list &optional vertical-step horizontal-step)
21474   "Print labelled bar graph of the NUMBERS-LIST.
21475 The numbers-list consists of the Y-axis values.
21476 @end group
21478 @group
21479 Optionally, VERTICAL-STEP, a positive integer,
21480 specifies how much a Y axis label increments for
21481 each line.  For example, a step of 5 means that
21482 each row is five units.
21483 @end group
21485 @group
21486 Optionally, HORIZONTAL-STEP, a positive integer,
21487 specifies how much an X  axis label increments for
21488 each column."
21489   (let* ((symbol-width (length graph-blank))
21490          ;; @code{height} @r{is both the largest number}
21491          ;; @r{and the number with the most digits.}
21492          (height (apply 'max numbers-list))
21493 @end group
21494 @group
21495          (height-of-top-line
21496           (if (zerop (% height Y-axis-label-spacing))
21497               height
21498             ;; @r{else}
21499             (* (1+ (/ height Y-axis-label-spacing))
21500                Y-axis-label-spacing)))
21501 @end group
21502 @group
21503          (vertical-step (or vertical-step 1))
21504          (full-Y-label-width
21505           (length
21506            (concat
21507             (number-to-string
21508              (* height-of-top-line vertical-step))
21509             Y-axis-tic))))
21510 @end group
21511 @group
21512     (print-Y-axis
21513      height-of-top-line full-Y-label-width vertical-step)
21514     (graph-body-print
21515         numbers-list height-of-top-line symbol-width)
21516     (print-X-axis numbers-list horizontal-step)))
21517 @end group
21518 @end smallexample
21519 @end ifnottex
21521 @c qqq
21522 @ignore
21523 Graphing Definitions Re-listed
21525 @need 1250
21526 Here are all the graphing definitions in their final form:
21528 @smallexample
21529 @group
21530 (defvar top-of-ranges
21531  '(10  20  30  40  50
21532    60  70  80  90 100
21533   110 120 130 140 150
21534   160 170 180 190 200
21535   210 220 230 240 250)
21536  "List specifying ranges for `defuns-per-range'.")
21537 @end group
21539 @group
21540 (defvar graph-symbol "*"
21541   "String used as symbol in graph, usually an asterisk.")
21542 @end group
21544 @group
21545 (defvar graph-blank " "
21546   "String used as blank in graph, usually a blank space.
21547 graph-blank must be the same number of columns wide
21548 as graph-symbol.")
21549 @end group
21551 @group
21552 (defvar Y-axis-tic " - "
21553    "String that follows number in a Y axis label.")
21554 @end group
21556 @group
21557 (defvar Y-axis-label-spacing 5
21558   "Number of lines from one Y axis label to next.")
21559 @end group
21561 @group
21562 (defvar X-axis-tic-symbol "|"
21563   "String to insert to point to a column in X axis.")
21564 @end group
21566 @group
21567 (defvar X-axis-label-spacing
21568   (if (boundp 'graph-blank)
21569       (* 5 (length graph-blank)) 5)
21570   "Number of units from one X axis label to next.")
21571 @end group
21572 @end smallexample
21574 @smallexample
21575 @group
21576 (defun count-words-in-defun ()
21577   "Return the number of words and symbols in a defun."
21578   (beginning-of-defun)
21579   (let ((count 0)
21580         (end (save-excursion (end-of-defun) (point))))
21581 @end group
21583 @group
21584     (while
21585         (and (< (point) end)
21586              (re-search-forward
21587               "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
21588               end t))
21589       (setq count (1+ count)))
21590     count))
21591 @end group
21592 @end smallexample
21594 @smallexample
21595 @group
21596 (defun lengths-list-file (filename)
21597   "Return list of definitions' lengths within FILE.
21598 The returned list is a list of numbers.
21599 Each number is the number of words or
21600 symbols in one function definition."
21601 @end group
21603 @group
21604   (message "Working on `%s' ... " filename)
21605   (save-excursion
21606     (let ((buffer (find-file-noselect filename))
21607           (lengths-list))
21608       (set-buffer buffer)
21609       (setq buffer-read-only t)
21610       (widen)
21611       (goto-char (point-min))
21612 @end group
21614 @group
21615       (while (re-search-forward "^(defun" nil t)
21616         (setq lengths-list
21617               (cons (count-words-in-defun) lengths-list)))
21618       (kill-buffer buffer)
21619       lengths-list)))
21620 @end group
21621 @end smallexample
21623 @smallexample
21624 @group
21625 (defun lengths-list-many-files (list-of-files)
21626   "Return list of lengths of defuns in LIST-OF-FILES."
21627   (let (lengths-list)
21628 ;;; @r{true-or-false-test}
21629     (while list-of-files
21630       (setq lengths-list
21631             (append
21632              lengths-list
21633 @end group
21634 @group
21635 ;;; @r{Generate a lengths' list.}
21636              (lengths-list-file
21637               (expand-file-name (car list-of-files)))))
21638 ;;; @r{Make files' list shorter.}
21639       (setq list-of-files (cdr list-of-files)))
21640 ;;; @r{Return final value of lengths' list.}
21641     lengths-list))
21642 @end group
21643 @end smallexample
21645 @smallexample
21646 @group
21647 (defun defuns-per-range (sorted-lengths top-of-ranges)
21648   "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
21649   (let ((top-of-range (car top-of-ranges))
21650         (number-within-range 0)
21651         defuns-per-range-list)
21652 @end group
21654 @group
21655     ;; @r{Outer loop.}
21656     (while top-of-ranges
21658       ;; @r{Inner loop.}
21659       (while (and
21660               ;; @r{Need number for numeric test.}
21661               (car sorted-lengths)
21662               (< (car sorted-lengths) top-of-range))
21664         ;; @r{Count number of definitions within current range.}
21665         (setq number-within-range (1+ number-within-range))
21666         (setq sorted-lengths (cdr sorted-lengths)))
21667 @end group
21669 @group
21670       ;; @r{Exit inner loop but remain within outer loop.}
21672       (setq defuns-per-range-list
21673             (cons number-within-range defuns-per-range-list))
21674       (setq number-within-range 0)      ; @r{Reset count to zero.}
21676       ;; @r{Move to next range.}
21677       (setq top-of-ranges (cdr top-of-ranges))
21678       ;; @r{Specify next top of range value.}
21679       (setq top-of-range (car top-of-ranges)))
21680 @end group
21682 @group
21683     ;; @r{Exit outer loop and count the number of defuns larger than}
21684     ;; @r{  the largest top-of-range value.}
21685     (setq defuns-per-range-list
21686           (cons
21687            (length sorted-lengths)
21688            defuns-per-range-list))
21690     ;; @r{Return a list of the number of definitions within each range,}
21691     ;; @r{  smallest to largest.}
21692     (nreverse defuns-per-range-list)))
21693 @end group
21694 @end smallexample
21696 @smallexample
21697 @group
21698 (defun column-of-graph (max-graph-height actual-height)
21699   "Return list of MAX-GRAPH-HEIGHT strings;
21700 ACTUAL-HEIGHT are graph-symbols.
21701 The graph-symbols are contiguous entries at the end
21702 of the list.
21703 The list will be inserted as one column of a graph.
21704 The strings are either graph-blank or graph-symbol."
21705 @end group
21707 @group
21708   (let ((insert-list nil)
21709         (number-of-top-blanks
21710          (- max-graph-height actual-height)))
21712     ;; @r{Fill in @code{graph-symbols}.}
21713     (while (> actual-height 0)
21714       (setq insert-list (cons graph-symbol insert-list))
21715       (setq actual-height (1- actual-height)))
21716 @end group
21718 @group
21719     ;; @r{Fill in @code{graph-blanks}.}
21720     (while (> number-of-top-blanks 0)
21721       (setq insert-list (cons graph-blank insert-list))
21722       (setq number-of-top-blanks
21723             (1- number-of-top-blanks)))
21725     ;; @r{Return whole list.}
21726     insert-list))
21727 @end group
21728 @end smallexample
21730 @smallexample
21731 @group
21732 (defun Y-axis-element (number full-Y-label-width)
21733   "Construct a NUMBERed label element.
21734 A numbered element looks like this `  5 - ',
21735 and is padded as needed so all line up with
21736 the element for the largest number."
21737 @end group
21738 @group
21739   (let* ((leading-spaces
21740          (- full-Y-label-width
21741             (length
21742              (concat (number-to-string number)
21743                      Y-axis-tic)))))
21744 @end group
21745 @group
21746     (concat
21747      (make-string leading-spaces ? )
21748      (number-to-string number)
21749      Y-axis-tic)))
21750 @end group
21751 @end smallexample
21753 @smallexample
21754 @group
21755 (defun print-Y-axis
21756   (height full-Y-label-width &optional vertical-step)
21757   "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
21758 Height must be the  maximum height of the graph.
21759 Full width is the width of the highest label element.
21760 Optionally, print according to VERTICAL-STEP."
21761 @end group
21762 @group
21763 ;; Value of height and full-Y-label-width
21764 ;; are passed by `print-graph'.
21765   (let ((start (point)))
21766     (insert-rectangle
21767      (Y-axis-column height full-Y-label-width vertical-step))
21768 @end group
21769 @group
21770     ;; @r{Place point ready for inserting graph.}
21771     (goto-char start)
21772     ;; @r{Move point forward by value of} full-Y-label-width
21773     (forward-char full-Y-label-width)))
21774 @end group
21775 @end smallexample
21777 @smallexample
21778 @group
21779 (defun print-X-axis-tic-line
21780   (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
21781   "Print ticks for X axis."
21782     (insert X-axis-leading-spaces)
21783     (insert X-axis-tic-symbol)  ; @r{Under first column.}
21784 @end group
21785 @group
21786     ;; @r{Insert second tic in the right spot.}
21787     (insert (concat
21788              (make-string
21789               (-  (* symbol-width X-axis-label-spacing)
21790                   ;; @r{Insert white space up to second tic symbol.}
21791                   (* 2 (length X-axis-tic-symbol)))
21792               ? )
21793              X-axis-tic-symbol))
21794 @end group
21795 @group
21796     ;; @r{Insert remaining ticks.}
21797     (while (> number-of-X-tics 1)
21798       (insert X-axis-tic-element)
21799       (setq number-of-X-tics (1- number-of-X-tics))))
21800 @end group
21801 @end smallexample
21803 @smallexample
21804 @group
21805 (defun X-axis-element (number)
21806   "Construct a numbered X axis element."
21807   (let ((leading-spaces
21808          (-  (* symbol-width X-axis-label-spacing)
21809              (length (number-to-string number)))))
21810     (concat (make-string leading-spaces ? )
21811             (number-to-string number))))
21812 @end group
21813 @end smallexample
21815 @smallexample
21816 @group
21817 (defun graph-body-print (numbers-list height symbol-width)
21818   "Print a bar graph of the NUMBERS-LIST.
21819 The numbers-list consists of the Y-axis values.
21820 HEIGHT is maximum height of graph.
21821 SYMBOL-WIDTH is number of each column."
21822 @end group
21823 @group
21824   (let (from-position)
21825     (while numbers-list
21826       (setq from-position (point))
21827       (insert-rectangle
21828        (column-of-graph height (car numbers-list)))
21829       (goto-char from-position)
21830       (forward-char symbol-width)
21831 @end group
21832 @group
21833       ;; @r{Draw graph column by column.}
21834       (sit-for 0)
21835       (setq numbers-list (cdr numbers-list)))
21836     ;; @r{Place point for X axis labels.}
21837     (forward-line height)
21838     (insert "\n")))
21839 @end group
21840 @end smallexample
21842 @smallexample
21843 @group
21844 (defun Y-axis-column
21845   (height width-of-label &optional vertical-step)
21846   "Construct list of labels for Y axis.
21847 HEIGHT is maximum height of graph.
21848 WIDTH-OF-LABEL is maximum width of label.
21849 @end group
21850 @group
21851 VERTICAL-STEP, an option, is a positive integer
21852 that specifies how much a Y axis label increments
21853 for each line.  For example, a step of 5 means
21854 that each line is five units of the graph."
21855   (let (Y-axis
21856         (number-per-line (or vertical-step 1)))
21857 @end group
21858 @group
21859     (while (> height 1)
21860       (if (zerop (% height Y-axis-label-spacing))
21861           ;; @r{Insert label.}
21862           (setq Y-axis
21863                 (cons
21864                  (Y-axis-element
21865                   (* height number-per-line)
21866                   width-of-label)
21867                  Y-axis))
21868 @end group
21869 @group
21870         ;; @r{Else, insert blanks.}
21871         (setq Y-axis
21872               (cons
21873                (make-string width-of-label ? )
21874                Y-axis)))
21875       (setq height (1- height)))
21876 @end group
21877 @group
21878     ;; @r{Insert base line.}
21879     (setq Y-axis (cons (Y-axis-element
21880                         (or vertical-step 1)
21881                         width-of-label)
21882                        Y-axis))
21883     (nreverse Y-axis)))
21884 @end group
21885 @end smallexample
21887 @smallexample
21888 @group
21889 (defun print-X-axis-numbered-line
21890   (number-of-X-tics X-axis-leading-spaces
21891    &optional horizontal-step)
21892   "Print line of X-axis numbers"
21893   (let ((number X-axis-label-spacing)
21894         (horizontal-step (or horizontal-step 1)))
21895 @end group
21896 @group
21897     (insert X-axis-leading-spaces)
21898     ;; line up number
21899     (delete-char (- (1- (length (number-to-string horizontal-step)))))
21900     (insert (concat
21901              (make-string
21902               ;; @r{Insert white space up to next number.}
21903               (-  (* symbol-width X-axis-label-spacing)
21904                   (1- (length (number-to-string horizontal-step)))
21905                   2)
21906               ? )
21907              (number-to-string (* number horizontal-step))))
21908 @end group
21909 @group
21910     ;; @r{Insert remaining numbers.}
21911     (setq number (+ number X-axis-label-spacing))
21912     (while (> number-of-X-tics 1)
21913       (insert (X-axis-element (* number horizontal-step)))
21914       (setq number (+ number X-axis-label-spacing))
21915       (setq number-of-X-tics (1- number-of-X-tics)))))
21916 @end group
21917 @end smallexample
21919 @smallexample
21920 @group
21921 (defun print-X-axis (numbers-list horizontal-step)
21922   "Print X axis labels to length of NUMBERS-LIST.
21923 Optionally, HORIZONTAL-STEP, a positive integer,
21924 specifies how much an X  axis label increments for
21925 each column."
21926 @end group
21927 @group
21928 ;; Value of symbol-width and full-Y-label-width
21929 ;; are passed by `print-graph'.
21930   (let* ((leading-spaces
21931           (make-string full-Y-label-width ? ))
21932        ;; symbol-width @r{is provided by} graph-body-print
21933        (tic-width (* symbol-width X-axis-label-spacing))
21934        (X-length (length numbers-list))
21935 @end group
21936 @group
21937        (X-tic
21938         (concat
21939          (make-string
21940           ;; @r{Make a string of blanks.}
21941           (-  (* symbol-width X-axis-label-spacing)
21942               (length X-axis-tic-symbol))
21943           ? )
21944 @end group
21945 @group
21946          ;; @r{Concatenate blanks with tic symbol.}
21947          X-axis-tic-symbol))
21948        (tic-number
21949         (if (zerop (% X-length tic-width))
21950             (/ X-length tic-width)
21951           (1+ (/ X-length tic-width)))))
21952 @end group
21954 @group
21955     (print-X-axis-tic-line
21956      tic-number leading-spaces X-tic)
21957     (insert "\n")
21958     (print-X-axis-numbered-line
21959      tic-number leading-spaces horizontal-step)))
21960 @end group
21961 @end smallexample
21963 @smallexample
21964 @group
21965 (defun one-fiftieth (full-range)
21966   "Return list, each number of which is 1/50th previous."
21967  (mapcar '(lambda (arg) (/ arg 50)) full-range))
21968 @end group
21969 @end smallexample
21971 @smallexample
21972 @group
21973 (defun print-graph
21974   (numbers-list &optional vertical-step horizontal-step)
21975   "Print labelled bar graph of the NUMBERS-LIST.
21976 The numbers-list consists of the Y-axis values.
21977 @end group
21979 @group
21980 Optionally, VERTICAL-STEP, a positive integer,
21981 specifies how much a Y axis label increments for
21982 each line.  For example, a step of 5 means that
21983 each row is five units.
21984 @end group
21986 @group
21987 Optionally, HORIZONTAL-STEP, a positive integer,
21988 specifies how much an X  axis label increments for
21989 each column."
21990   (let* ((symbol-width (length graph-blank))
21991          ;; @code{height} @r{is both the largest number}
21992          ;; @r{and the number with the most digits.}
21993          (height (apply 'max numbers-list))
21994 @end group
21995 @group
21996          (height-of-top-line
21997           (if (zerop (% height Y-axis-label-spacing))
21998               height
21999             ;; @r{else}
22000             (* (1+ (/ height Y-axis-label-spacing))
22001                Y-axis-label-spacing)))
22002 @end group
22003 @group
22004          (vertical-step (or vertical-step 1))
22005          (full-Y-label-width
22006           (length
22007            (concat
22008             (number-to-string
22009              (* height-of-top-line vertical-step))
22010             Y-axis-tic))))
22011 @end group
22012 @group
22014     (print-Y-axis
22015      height-of-top-line full-Y-label-width vertical-step)
22016     (graph-body-print
22017         numbers-list height-of-top-line symbol-width)
22018     (print-X-axis numbers-list horizontal-step)))
22019 @end group
22020 @end smallexample
22021 @c qqq
22022 @end ignore
22024 @page
22025 @node Final printed graph,  , Another Bug, Print Whole Graph
22026 @appendixsubsec The Printed Graph
22028 When made and installed, you can call the @code{print-graph} command
22029 like this:
22030 @sp 1
22032 @smallexample
22033 @group
22034 (print-graph fiftieth-list-for-graph 50 10)
22035 @end group
22036 @end smallexample
22037 @sp 1
22039 @noindent
22040 Here is the graph:
22041 @sp 2
22043 @smallexample
22044 @group
22045 1000 -  *
22046         **
22047         **
22048         **
22049         **
22050  750 -  ***
22051         ***
22052         ***
22053         ***
22054         ****
22055  500 - *****
22056        ******
22057        ******
22058        ******
22059        *******
22060  250 - ********
22061        *********                     *
22062        ***********                   *
22063        *************                 *
22064   50 - ***************** *           *
22065        |   |    |    |    |    |    |    |
22066       10  50  100  150  200  250  300  350
22067 @end group
22068 @end smallexample
22070 @sp 2
22072 @noindent
22073 The largest group of functions contain 10 -- 19 words and symbols each.
22075 @node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top
22076 @appendix Free Software and Free Manuals
22078 @strong{by Richard M. Stallman}
22079 @sp 1
22081 The biggest deficiency in free operating systems is not in the
22082 software---it is the lack of good free manuals that we can include in
22083 these systems.  Many of our most important programs do not come with
22084 full manuals.  Documentation is an essential part of any software
22085 package; when an important free software package does not come with a
22086 free manual, that is a major gap.  We have many such gaps today.
22088 Once upon a time, many years ago, I thought I would learn Perl.  I got
22089 a copy of a free manual, but I found it hard to read.  When I asked
22090 Perl users about alternatives, they told me that there were better
22091 introductory manuals---but those were not free.
22093 Why was this?  The authors of the good manuals had written them for
22094 O'Reilly Associates, which published them with restrictive terms---no
22095 copying, no modification, source files not available---which exclude
22096 them from the free software community.
22098 That wasn't the first time this sort of thing has happened, and (to
22099 our community's great loss) it was far from the last.  Proprietary
22100 manual publishers have enticed a great many authors to restrict their
22101 manuals since then.  Many times I have heard a GNU user eagerly tell me
22102 about a manual that he is writing, with which he expects to help the
22103 GNU project---and then had my hopes dashed, as he proceeded to explain
22104 that he had signed a contract with a publisher that would restrict it
22105 so that we cannot use it.
22107 Given that writing good English is a rare skill among programmers, we
22108 can ill afford to lose manuals this way.
22110 @c (texinfo)uref
22111 (The Free Software Foundation
22112 @uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, ,
22113 sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html,
22114 GNU manuals}, too.)
22116 Free documentation, like free software, is a matter of freedom, not
22117 price.  The problem with these manuals was not that O'Reilly Associates
22118 charged a price for printed copies---that in itself is fine.  (The Free
22119 Software Foundation sells printed copies of free GNU manuals, too.)
22120 But GNU manuals are available in source code form, while these manuals
22121 are available only on paper.  GNU manuals come with permission to copy
22122 and modify; the Perl manuals do not.  These restrictions are the
22123 problems.
22125 The criterion for a free manual is pretty much the same as for free
22126 software: it is a matter of giving all users certain
22127 freedoms.  Redistribution (including commercial redistribution) must be
22128 permitted, so that the manual can accompany every copy of the program,
22129 on-line or on paper.  Permission for modification is crucial too.
22131 As a general rule, I don't believe that it is essential for people to
22132 have permission to modify all sorts of articles and books.  The issues
22133 for writings are not necessarily the same as those for software.  For
22134 example, I don't think you or I are obliged to give permission to
22135 modify articles like this one, which describe our actions and our
22136 views.
22138 But there is a particular reason why the freedom to modify is crucial
22139 for documentation for free software.  When people exercise their right
22140 to modify the software, and add or change its features, if they are
22141 conscientious they will change the manual too---so they can provide
22142 accurate and usable documentation with the modified program.  A manual
22143 which forbids programmers to be conscientious and finish the job, or
22144 more precisely requires them to write a new manual from scratch if
22145 they change the program, does not fill our community's needs.
22147 While a blanket prohibition on modification is unacceptable, some
22148 kinds of limits on the method of modification pose no problem.  For
22149 example, requirements to preserve the original author's copyright
22150 notice, the distribution terms, or the list of authors, are ok.  It is
22151 also no problem to require modified versions to include notice that
22152 they were modified, even to have entire sections that may not be
22153 deleted or changed, as long as these sections deal with nontechnical
22154 topics.  (Some GNU manuals have them.)
22156 These kinds of restrictions are not a problem because, as a practical
22157 matter, they don't stop the conscientious programmer from adapting the
22158 manual to fit the modified program.  In other words, they don't block
22159 the free software community from making full use of the manual.
22161 However, it must be possible to modify all the technical content of
22162 the manual, and then distribute the result in all the usual media,
22163 through all the usual channels; otherwise, the restrictions do block
22164 the community, the manual is not free, and so we need another manual.
22166 Unfortunately, it is often hard to find someone to write another
22167 manual when a proprietary manual exists.  The obstacle is that many
22168 users think that a proprietary manual is good enough---so they don't
22169 see the need to write a free manual.  They do not see that the free
22170 operating system has a gap that needs filling.
22172 Why do users think that proprietary manuals are good enough? Some have
22173 not considered the issue.  I hope this article will do something to
22174 change that.
22176 Other users consider proprietary manuals acceptable for the same
22177 reason so many people consider proprietary software acceptable: they
22178 judge in purely practical terms, not using freedom as a
22179 criterion.  These people are entitled to their opinions, but since
22180 those opinions spring from values which do not include freedom, they
22181 are no guide for those of us who do value freedom.
22183 Please spread the word about this issue.  We continue to lose manuals
22184 to proprietary publishing.  If we spread the word that proprietary
22185 manuals are not sufficient, perhaps the next person who wants to help
22186 GNU by writing documentation will realize, before it is too late, that
22187 he must above all make it free.
22189 We can also encourage commercial publishers to sell free, copylefted
22190 manuals instead of proprietary ones.  One way you can help this is to
22191 check the distribution terms of a manual before you buy it, and prefer
22192 copylefted manuals to non-copylefted ones.
22194 @sp 2
22195 @noindent
22196 Note: The Free Software Foundation maintains a page on its Web site
22197 that lists free books available from other publishers:@*
22198 @uref{http://www.gnu.org/doc/other-free-books.html}
22200 @node GNU Free Documentation License, Index, Free Software and Free Manuals, Top
22201 @appendix GNU Free Documentation License
22203 @cindex FDL, GNU Free Documentation License
22204 @center Version 1.2, November 2002
22206 @display
22207 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
22208 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
22210 Everyone is permitted to copy and distribute verbatim copies
22211 of this license document, but changing it is not allowed.
22212 @end display
22214 @enumerate 0
22215 @item
22216 PREAMBLE
22218 The purpose of this License is to make a manual, textbook, or other
22219 functional and useful document @dfn{free} in the sense of freedom: to
22220 assure everyone the effective freedom to copy and redistribute it,
22221 with or without modifying it, either commercially or noncommercially.
22222 Secondarily, this License preserves for the author and publisher a way
22223 to get credit for their work, while not being considered responsible
22224 for modifications made by others.
22226 This License is a kind of ``copyleft'', which means that derivative
22227 works of the document must themselves be free in the same sense.  It
22228 complements the GNU General Public License, which is a copyleft
22229 license designed for free software.
22231 We have designed this License in order to use it for manuals for free
22232 software, because free software needs free documentation: a free
22233 program should come with manuals providing the same freedoms that the
22234 software does.  But this License is not limited to software manuals;
22235 it can be used for any textual work, regardless of subject matter or
22236 whether it is published as a printed book.  We recommend this License
22237 principally for works whose purpose is instruction or reference.
22239 @item
22240 APPLICABILITY AND DEFINITIONS
22242 This License applies to any manual or other work, in any medium, that
22243 contains a notice placed by the copyright holder saying it can be
22244 distributed under the terms of this License.  Such a notice grants a
22245 world-wide, royalty-free license, unlimited in duration, to use that
22246 work under the conditions stated herein.  The ``Document'', below,
22247 refers to any such manual or work.  Any member of the public is a
22248 licensee, and is addressed as ``you''.  You accept the license if you
22249 copy, modify or distribute the work in a way requiring permission
22250 under copyright law.
22252 A ``Modified Version'' of the Document means any work containing the
22253 Document or a portion of it, either copied verbatim, or with
22254 modifications and/or translated into another language.
22256 A ``Secondary Section'' is a named appendix or a front-matter section
22257 of the Document that deals exclusively with the relationship of the
22258 publishers or authors of the Document to the Document's overall
22259 subject (or to related matters) and contains nothing that could fall
22260 directly within that overall subject.  (Thus, if the Document is in
22261 part a textbook of mathematics, a Secondary Section may not explain
22262 any mathematics.)  The relationship could be a matter of historical
22263 connection with the subject or with related matters, or of legal,
22264 commercial, philosophical, ethical or political position regarding
22265 them.
22267 The ``Invariant Sections'' are certain Secondary Sections whose titles
22268 are designated, as being those of Invariant Sections, in the notice
22269 that says that the Document is released under this License.  If a
22270 section does not fit the above definition of Secondary then it is not
22271 allowed to be designated as Invariant.  The Document may contain zero
22272 Invariant Sections.  If the Document does not identify any Invariant
22273 Sections then there are none.
22275 The ``Cover Texts'' are certain short passages of text that are listed,
22276 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
22277 the Document is released under this License.  A Front-Cover Text may
22278 be at most 5 words, and a Back-Cover Text may be at most 25 words.
22280 A ``Transparent'' copy of the Document means a machine-readable copy,
22281 represented in a format whose specification is available to the
22282 general public, that is suitable for revising the document
22283 straightforwardly with generic text editors or (for images composed of
22284 pixels) generic paint programs or (for drawings) some widely available
22285 drawing editor, and that is suitable for input to text formatters or
22286 for automatic translation to a variety of formats suitable for input
22287 to text formatters.  A copy made in an otherwise Transparent file
22288 format whose markup, or absence of markup, has been arranged to thwart
22289 or discourage subsequent modification by readers is not Transparent.
22290 An image format is not Transparent if used for any substantial amount
22291 of text.  A copy that is not ``Transparent'' is called ``Opaque''.
22293 Examples of suitable formats for Transparent copies include plain
22294 @sc{ascii} without markup, Texinfo input format, La@TeX{} input
22295 format, @acronym{SGML} or @acronym{XML} using a publicly available
22296 @acronym{DTD}, and standard-conforming simple @acronym{HTML},
22297 PostScript or @acronym{PDF} designed for human modification.  Examples
22298 of transparent image formats include @acronym{PNG}, @acronym{XCF} and
22299 @acronym{JPG}.  Opaque formats include proprietary formats that can be
22300 read and edited only by proprietary word processors, @acronym{SGML} or
22301 @acronym{XML} for which the @acronym{DTD} and/or processing tools are
22302 not generally available, and the machine-generated @acronym{HTML},
22303 PostScript or @acronym{PDF} produced by some word processors for
22304 output purposes only.
22306 The ``Title Page'' means, for a printed book, the title page itself,
22307 plus such following pages as are needed to hold, legibly, the material
22308 this License requires to appear in the title page.  For works in
22309 formats which do not have any title page as such, ``Title Page'' means
22310 the text near the most prominent appearance of the work's title,
22311 preceding the beginning of the body of the text.
22313 A section ``Entitled XYZ'' means a named subunit of the Document whose
22314 title either is precisely XYZ or contains XYZ in parentheses following
22315 text that translates XYZ in another language.  (Here XYZ stands for a
22316 specific section name mentioned below, such as ``Acknowledgements'',
22317 ``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
22318 of such a section when you modify the Document means that it remains a
22319 section ``Entitled XYZ'' according to this definition.
22321 The Document may include Warranty Disclaimers next to the notice which
22322 states that this License applies to the Document.  These Warranty
22323 Disclaimers are considered to be included by reference in this
22324 License, but only as regards disclaiming warranties: any other
22325 implication that these Warranty Disclaimers may have is void and has
22326 no effect on the meaning of this License.
22328 @item
22329 VERBATIM COPYING
22331 You may copy and distribute the Document in any medium, either
22332 commercially or noncommercially, provided that this License, the
22333 copyright notices, and the license notice saying this License applies
22334 to the Document are reproduced in all copies, and that you add no other
22335 conditions whatsoever to those of this License.  You may not use
22336 technical measures to obstruct or control the reading or further
22337 copying of the copies you make or distribute.  However, you may accept
22338 compensation in exchange for copies.  If you distribute a large enough
22339 number of copies you must also follow the conditions in section 3.
22341 You may also lend copies, under the same conditions stated above, and
22342 you may publicly display copies.
22344 @item
22345 COPYING IN QUANTITY
22347 If you publish printed copies (or copies in media that commonly have
22348 printed covers) of the Document, numbering more than 100, and the
22349 Document's license notice requires Cover Texts, you must enclose the
22350 copies in covers that carry, clearly and legibly, all these Cover
22351 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
22352 the back cover.  Both covers must also clearly and legibly identify
22353 you as the publisher of these copies.  The front cover must present
22354 the full title with all words of the title equally prominent and
22355 visible.  You may add other material on the covers in addition.
22356 Copying with changes limited to the covers, as long as they preserve
22357 the title of the Document and satisfy these conditions, can be treated
22358 as verbatim copying in other respects.
22360 If the required texts for either cover are too voluminous to fit
22361 legibly, you should put the first ones listed (as many as fit
22362 reasonably) on the actual cover, and continue the rest onto adjacent
22363 pages.
22365 If you publish or distribute Opaque copies of the Document numbering
22366 more than 100, you must either include a machine-readable Transparent
22367 copy along with each Opaque copy, or state in or with each Opaque copy
22368 a computer-network location from which the general network-using
22369 public has access to download using public-standard network protocols
22370 a complete Transparent copy of the Document, free of added material.
22371 If you use the latter option, you must take reasonably prudent steps,
22372 when you begin distribution of Opaque copies in quantity, to ensure
22373 that this Transparent copy will remain thus accessible at the stated
22374 location until at least one year after the last time you distribute an
22375 Opaque copy (directly or through your agents or retailers) of that
22376 edition to the public.
22378 It is requested, but not required, that you contact the authors of the
22379 Document well before redistributing any large number of copies, to give
22380 them a chance to provide you with an updated version of the Document.
22382 @item
22383 MODIFICATIONS
22385 You may copy and distribute a Modified Version of the Document under
22386 the conditions of sections 2 and 3 above, provided that you release
22387 the Modified Version under precisely this License, with the Modified
22388 Version filling the role of the Document, thus licensing distribution
22389 and modification of the Modified Version to whoever possesses a copy
22390 of it.  In addition, you must do these things in the Modified Version:
22392 @enumerate A
22393 @item
22394 Use in the Title Page (and on the covers, if any) a title distinct
22395 from that of the Document, and from those of previous versions
22396 (which should, if there were any, be listed in the History section
22397 of the Document).  You may use the same title as a previous version
22398 if the original publisher of that version gives permission.
22400 @item
22401 List on the Title Page, as authors, one or more persons or entities
22402 responsible for authorship of the modifications in the Modified
22403 Version, together with at least five of the principal authors of the
22404 Document (all of its principal authors, if it has fewer than five),
22405 unless they release you from this requirement.
22407 @item
22408 State on the Title page the name of the publisher of the
22409 Modified Version, as the publisher.
22411 @item
22412 Preserve all the copyright notices of the Document.
22414 @item
22415 Add an appropriate copyright notice for your modifications
22416 adjacent to the other copyright notices.
22418 @item
22419 Include, immediately after the copyright notices, a license notice
22420 giving the public permission to use the Modified Version under the
22421 terms of this License, in the form shown in the Addendum below.
22423 @item
22424 Preserve in that license notice the full lists of Invariant Sections
22425 and required Cover Texts given in the Document's license notice.
22427 @item
22428 Include an unaltered copy of this License.
22430 @item
22431 Preserve the section Entitled ``History'', Preserve its Title, and add
22432 to it an item stating at least the title, year, new authors, and
22433 publisher of the Modified Version as given on the Title Page.  If
22434 there is no section Entitled ``History'' in the Document, create one
22435 stating the title, year, authors, and publisher of the Document as
22436 given on its Title Page, then add an item describing the Modified
22437 Version as stated in the previous sentence.
22439 @item
22440 Preserve the network location, if any, given in the Document for
22441 public access to a Transparent copy of the Document, and likewise
22442 the network locations given in the Document for previous versions
22443 it was based on.  These may be placed in the ``History'' section.
22444 You may omit a network location for a work that was published at
22445 least four years before the Document itself, or if the original
22446 publisher of the version it refers to gives permission.
22448 @item
22449 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
22450 the Title of the section, and preserve in the section all the
22451 substance and tone of each of the contributor acknowledgements and/or
22452 dedications given therein.
22454 @item
22455 Preserve all the Invariant Sections of the Document,
22456 unaltered in their text and in their titles.  Section numbers
22457 or the equivalent are not considered part of the section titles.
22459 @item
22460 Delete any section Entitled ``Endorsements''.  Such a section
22461 may not be included in the Modified Version.
22463 @item
22464 Do not retitle any existing section to be Entitled ``Endorsements'' or
22465 to conflict in title with any Invariant Section.
22467 @item
22468 Preserve any Warranty Disclaimers.
22469 @end enumerate
22471 If the Modified Version includes new front-matter sections or
22472 appendices that qualify as Secondary Sections and contain no material
22473 copied from the Document, you may at your option designate some or all
22474 of these sections as invariant.  To do this, add their titles to the
22475 list of Invariant Sections in the Modified Version's license notice.
22476 These titles must be distinct from any other section titles.
22478 You may add a section Entitled ``Endorsements'', provided it contains
22479 nothing but endorsements of your Modified Version by various
22480 parties---for example, statements of peer review or that the text has
22481 been approved by an organization as the authoritative definition of a
22482 standard.
22484 You may add a passage of up to five words as a Front-Cover Text, and a
22485 passage of up to 25 words as a Back-Cover Text, to the end of the list
22486 of Cover Texts in the Modified Version.  Only one passage of
22487 Front-Cover Text and one of Back-Cover Text may be added by (or
22488 through arrangements made by) any one entity.  If the Document already
22489 includes a cover text for the same cover, previously added by you or
22490 by arrangement made by the same entity you are acting on behalf of,
22491 you may not add another; but you may replace the old one, on explicit
22492 permission from the previous publisher that added the old one.
22494 The author(s) and publisher(s) of the Document do not by this License
22495 give permission to use their names for publicity for or to assert or
22496 imply endorsement of any Modified Version.
22498 @item
22499 COMBINING DOCUMENTS
22501 You may combine the Document with other documents released under this
22502 License, under the terms defined in section 4 above for modified
22503 versions, provided that you include in the combination all of the
22504 Invariant Sections of all of the original documents, unmodified, and
22505 list them all as Invariant Sections of your combined work in its
22506 license notice, and that you preserve all their Warranty Disclaimers.
22508 The combined work need only contain one copy of this License, and
22509 multiple identical Invariant Sections may be replaced with a single
22510 copy.  If there are multiple Invariant Sections with the same name but
22511 different contents, make the title of each such section unique by
22512 adding at the end of it, in parentheses, the name of the original
22513 author or publisher of that section if known, or else a unique number.
22514 Make the same adjustment to the section titles in the list of
22515 Invariant Sections in the license notice of the combined work.
22517 In the combination, you must combine any sections Entitled ``History''
22518 in the various original documents, forming one section Entitled
22519 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
22520 and any sections Entitled ``Dedications''.  You must delete all
22521 sections Entitled ``Endorsements.''
22523 @item
22524 COLLECTIONS OF DOCUMENTS
22526 You may make a collection consisting of the Document and other documents
22527 released under this License, and replace the individual copies of this
22528 License in the various documents with a single copy that is included in
22529 the collection, provided that you follow the rules of this License for
22530 verbatim copying of each of the documents in all other respects.
22532 You may extract a single document from such a collection, and distribute
22533 it individually under this License, provided you insert a copy of this
22534 License into the extracted document, and follow this License in all
22535 other respects regarding verbatim copying of that document.
22537 @item
22538 AGGREGATION WITH INDEPENDENT WORKS
22540 A compilation of the Document or its derivatives with other separate
22541 and independent documents or works, in or on a volume of a storage or
22542 distribution medium, is called an ``aggregate'' if the copyright
22543 resulting from the compilation is not used to limit the legal rights
22544 of the compilation's users beyond what the individual works permit.
22545 When the Document is included in an aggregate, this License does not
22546 apply to the other works in the aggregate which are not themselves
22547 derivative works of the Document.
22549 If the Cover Text requirement of section 3 is applicable to these
22550 copies of the Document, then if the Document is less than one half of
22551 the entire aggregate, the Document's Cover Texts may be placed on
22552 covers that bracket the Document within the aggregate, or the
22553 electronic equivalent of covers if the Document is in electronic form.
22554 Otherwise they must appear on printed covers that bracket the whole
22555 aggregate.
22557 @item
22558 TRANSLATION
22560 Translation is considered a kind of modification, so you may
22561 distribute translations of the Document under the terms of section 4.
22562 Replacing Invariant Sections with translations requires special
22563 permission from their copyright holders, but you may include
22564 translations of some or all Invariant Sections in addition to the
22565 original versions of these Invariant Sections.  You may include a
22566 translation of this License, and all the license notices in the
22567 Document, and any Warranty Disclaimers, provided that you also include
22568 the original English version of this License and the original versions
22569 of those notices and disclaimers.  In case of a disagreement between
22570 the translation and the original version of this License or a notice
22571 or disclaimer, the original version will prevail.
22573 If a section in the Document is Entitled ``Acknowledgements'',
22574 ``Dedications'', or ``History'', the requirement (section 4) to Preserve
22575 its Title (section 1) will typically require changing the actual
22576 title.
22578 @item
22579 TERMINATION
22581 You may not copy, modify, sublicense, or distribute the Document except
22582 as expressly provided for under this License.  Any other attempt to
22583 copy, modify, sublicense or distribute the Document is void, and will
22584 automatically terminate your rights under this License.  However,
22585 parties who have received copies, or rights, from you under this
22586 License will not have their licenses terminated so long as such
22587 parties remain in full compliance.
22589 @item
22590 FUTURE REVISIONS OF THIS LICENSE
22592 The Free Software Foundation may publish new, revised versions
22593 of the GNU Free Documentation License from time to time.  Such new
22594 versions will be similar in spirit to the present version, but may
22595 differ in detail to address new problems or concerns.  See
22596 @uref{http://www.gnu.org/copyleft/}.
22598 Each version of the License is given a distinguishing version number.
22599 If the Document specifies that a particular numbered version of this
22600 License ``or any later version'' applies to it, you have the option of
22601 following the terms and conditions either of that specified version or
22602 of any later version that has been published (not as a draft) by the
22603 Free Software Foundation.  If the Document does not specify a version
22604 number of this License, you may choose any version ever published (not
22605 as a draft) by the Free Software Foundation.
22606 @end enumerate
22608 @page
22609 @appendixsubsec ADDENDUM: How to use this License for your documents
22611 To use this License in a document you have written, include a copy of
22612 the License in the document and put the following copyright and
22613 license notices just after the title page:
22615 @smallexample
22616 @group
22617 Copyright (C)  @var{year}  @var{your name}.
22618 Permission is granted to copy, distribute and/or modify this document
22619 under the terms of the GNU Free Documentation License, Version 1.2
22620 or any later version published by the Free Software Foundation;
22621 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
22622 A copy of the license is included in the section entitled ``GNU
22623 Free Documentation License''.
22624 @end group
22625 @end smallexample
22627 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
22628 replace the ``with...Texts.'' line with this:
22630 @smallexample
22631 @group
22632 with the Invariant Sections being @var{list their titles}, with
22633 the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
22634 being @var{list}.
22635 @end group
22636 @end smallexample
22638 If you have Invariant Sections without Cover Texts, or some other
22639 combination of the three, merge those two alternatives to suit the
22640 situation.
22642 If your document contains nontrivial examples of program code, we
22643 recommend releasing these examples in parallel under your choice of
22644 free software license, such as the GNU General Public License,
22645 to permit their use in free software.
22647 @node Index, About the Author, GNU Free Documentation License, Top
22648 @comment  node-name,  next,  previous,  up
22649 @unnumbered Index
22651 @ignore
22652 MENU ENTRY: NODE NAME.
22653 @end ignore
22655 @printindex cp
22657 @iftex
22658 @c Place biographical information on right-hand (verso) page
22660 @tex
22661 \ifodd\pageno
22662     \par\vfill\supereject
22663     \global\evenheadline={\hfil} \global\evenfootline={\hfil}
22664     \global\oddheadline={\hfil} \global\oddfootline={\hfil}
22665     \page\hbox{}\page
22666 \else
22667     \par\vfill\supereject
22668     \par\vfill\supereject
22669     \global\evenheadline={\hfil} \global\evenfootline={\hfil}
22670     \global\oddheadline={\hfil} \global\oddfootline={\hfil}
22671     \page\hbox{}\page
22672     \page\hbox{}\page
22674 @end tex
22676 @page
22677 @w{ }
22679 @c ================ Biographical information ================
22681 @w{ }
22682 @sp 8
22683 @center About the Author
22684 @sp 1
22685 @end iftex
22687 @ifnottex
22688 @node About the Author,  , Index, Top
22689 @unnumbered About the Author
22690 @end ifnottex
22692 @quotation
22693 Robert J. Chassell has worked with GNU Emacs since 1985.  He writes
22694 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
22695 world on software freedom.  Chassell was a founding Director and
22696 Treasurer of the Free Software Foundation, Inc.  He is co-author of
22697 the @cite{Texinfo} manual, and has edited more than a dozen other
22698 books.  He graduated from Cambridge University, in England.  He has an
22699 abiding interest in social and economic history and flies his own
22700 airplane.
22701 @end quotation
22703 @page
22704 @w{ }
22706 @c Prevent page number on blank verso, so eject it first.
22707 @tex
22708 \par\vfill\supereject
22709 @end tex
22711 @iftex
22712 @headings off
22713 @evenheading @thispage @| @| @thistitle
22714 @oddheading            @| @| @thispage
22715 @end iftex
22717 @bye
22719 @ignore
22720    arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
22721 @end ignore