1 \input ../man/texinfo @c -*-texinfo-*-
2 @c change above to \input texinfo if building on own.
3 @comment %**start of header
4 @setfilename ../info/eintr
5 @c setfilename emacs-lisp-intro.info
6 @c sethtmlfilename emacs-lisp-intro.html
7 @settitle Programming in Emacs Lisp
10 @setchapternewpage odd
14 @c <<<< For hard copy printing, this file is now
15 @c set for smallbook, which works for all sizes
16 @c of paper, and with Postscript figures >>>>
19 @set print-postscript-figures
21 @c clear print-postscript-figures
24 @comment %**end of header
26 @set edition-number 2.14
27 @set update-date 2004 Oct 12
30 ## Summary of shell commands to create various output formats:
32 pushd /usr/local/src/emacs/lispintro/
35 makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
38 texi2dvi emacs-lisp-intro.texi
41 makeinfo --html --no-split --verbose emacs-lisp-intro.texi
44 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
45 --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
48 makeinfo --docbook --no-split --paragraph-indent=0 \
49 --verbose emacs-lisp-intro.texi
52 makeinfo --xml --no-split --paragraph-indent=0 \
53 --verbose emacs-lisp-intro.texi
55 #### (You must be in the same directory as the viewed file.)
58 xdvi emacs-lisp-intro.dvi &
61 galeon emacs-lisp-intro.html
63 ## View Info output with standalone reader
64 info emacs-lisp-intro.info
70 @c ================ Included Figures ================
72 @c Set print-postscript-figures if you print PostScript figures.
73 @c If you clear this, the ten figures will be printed as ASCII diagrams.
74 @c (This is not relevant to Info, since Info only handles ASCII.)
75 @c Your site may require editing changes to print PostScript; in this
76 @c case, search for `print-postscript-figures' and make appropriate changes.
79 @c ================ How to Create an Info file ================
81 @c If you have `makeinfo' installed, run the following command
83 @c makeinfo emacs-lisp-intro.texi
85 @c or, if you want a single, large Info file, and no paragraph indents:
86 @c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
88 @c After creating the Info file, edit your Info `dir' file, if the
89 @c `dircategory' section below does not enable your system to
90 @c install the manual automatically.
91 @c (The `dir' file is often in the `/usr/local/info/' directory.)
93 @c ================ How to Create an HTML file ================
95 @c To convert to HTML format
96 @c makeinfo --html --no-split --verbose emacs-lisp-intro.texi
98 @c ================ How to Print a Book in Various Sizes ================
100 @c This book can be printed in any of three different sizes.
101 @c In the above header, set @-commands appropriately.
111 @c European A4 size paper:
116 @c ================ How to Typeset and Print ================
118 @c If you do not include PostScript figures, run either of the
119 @c following command sequences, or similar commands suited to your
122 @c texi2dvi emacs-lisp-intro.texi
123 @c lpr -d emacs-lisp-intro.dvi
127 @c tex emacs-lisp-intro.texi
128 @c texindex emacs-lisp-intro.??
129 @c tex emacs-lisp-intro.texi
130 @c lpr -d emacs-lisp-intro.dvi
132 @c If you include the PostScript figures, and you have old software,
133 @c you may need to convert the .dvi file to a .ps file before
134 @c printing. Run either of the following command sequences, or one
137 @c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
141 @c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
144 @c (Note: if you edit the book so as to change the length of the
145 @c table of contents, you may have to change the value of `pageno' below.)
147 @c ================ End of Formatting Sections ================
149 @c For next or subsequent edition:
150 @c create function using with-output-to-temp-buffer
151 @c create a major mode, with keymaps
152 @c run an asynchronous process, like grep or diff
154 @c For 8.5 by 11 inch format: do not use such a small amount of
155 @c whitespace between paragraphs as smallbook format
158 \global\parskip 6pt plus 1pt
162 @c For all sized formats: print within-book cross
163 @c reference with ``...'' rather than [...]
165 @c This works with the texinfo.tex file, version 2003-05-04.08,
166 @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
169 \global\def\xrefprintnodename#1{``#1''}
172 @c ----------------------------------------------------
176 * Emacs Lisp Intro: (eintr).
177 A simple introduction to Emacs Lisp programming.
181 This is an @cite{Introduction to Programming in Emacs Lisp}, for
182 people who are not programmers.
184 Edition @value{edition-number}, @value{update-date}
186 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
187 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
193 GNU Press, @hfill @uref{http://www.gnupress.org}@*
194 a division of the @hfill General: @email{press@@gnu.org}@*
195 Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@*
196 51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@*
197 Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@*
204 GNU Press, Website: http://www.gnupress.org
205 a division of the General: press@@gnu.org
206 Free Software Foundation, Inc. Orders: sales@@gnu.org
207 51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942
208 Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652
213 @c Printed copies are available for $30 each.@*
216 Permission is granted to copy, distribute and/or modify this document
217 under the terms of the GNU Free Documentation License, Version 1.2 or
218 any later version published by the Free Software Foundation; there
219 being no Invariant Section, with the Front-Cover Texts being ``A GNU
220 Manual'', and with the Back-Cover Texts as in (a) below. A copy of
221 the license is included in the section entitled ``GNU Free
222 Documentation License''.
224 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
225 modify this GNU Manual, like GNU software. Copies published by the
226 Free Software Foundation raise funds for GNU development.''
229 @c half title; two lines here, so do not use `shorttitlepage'
232 \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
234 {\begingroup\hbox{}\vskip 0.25in \chaprm%
235 \centerline{Programming in Emacs Lisp}%
236 \endgroup\page\hbox{}\page}
241 @center @titlefont{An Introduction to}
243 @center @titlefont{Programming in Emacs Lisp}
245 @center Revised Second Edition
247 @center by Robert J. Chassell
250 @vskip 0pt plus 1filll
256 @evenheading @thispage @| @| @thischapter
257 @oddheading @thissection @| @| @thispage
261 @c Keep T.O.C. short by tightening up for largebook
264 \global\parskip 2pt plus 1pt
265 \global\advance\baselineskip by -1pt
274 @node Top, Preface, (dir), (dir)
275 @top An Introduction to Programming in Emacs Lisp
279 This master menu first lists each chapter and index; then it lists
280 every node in every chapter.
284 * Preface:: What to look for.
285 * List Processing:: What is Lisp?
286 * Practicing Evaluation:: Running several programs.
287 * Writing Defuns:: How to write function definitions.
288 * Buffer Walk Through:: Exploring a few buffer-related functions.
289 * More Complex:: A few, even more complex functions.
290 * Narrowing & Widening:: Restricting your and Emacs attention to
292 * car cdr & cons:: Fundamental functions in Lisp.
293 * Cutting & Storing Text:: Removing text and saving it.
294 * List Implementation:: How lists are implemented in the computer.
295 * Yanking:: Pasting stored text.
296 * Loops & Recursion:: How to repeat a process.
297 * Regexp Search:: Regular expression searches.
298 * Counting Words:: A review of repetition and regexps.
299 * Words in a defun:: Counting words in a @code{defun}.
300 * Readying a Graph:: A prototype graph printing function.
301 * Emacs Initialization:: How to write a @file{.emacs} file.
302 * Debugging:: How to run the Emacs Lisp debuggers.
303 * Conclusion:: Now you have the basics.
304 * the-the:: An appendix: how to find reduplicated words.
305 * Kill Ring:: An appendix: how the kill ring works.
306 * Full Graph:: How to create a graph with labelled axes.
307 * Free Software and Free Manuals::
308 * GNU Free Documentation License::
313 --- The Detailed Node Listing ---
317 * Why:: Why learn Emacs Lisp?
318 * On Reading this Text:: Read, gain familiarity, pick up habits....
319 * Who You Are:: For whom this is written.
321 * Note for Novices:: You can read this as a novice.
326 * Lisp Lists:: What are lists?
327 * Run a Program:: Any list in Lisp is a program ready to run.
328 * Making Errors:: Generating an error message.
329 * Names & Definitions:: Names of symbols and function definitions.
330 * Lisp Interpreter:: What the Lisp interpreter does.
331 * Evaluation:: Running a program.
332 * Variables:: Returning a value from a variable.
333 * Arguments:: Passing information to a function.
334 * set & setq:: Setting the value of a variable.
335 * Summary:: The major points.
336 * Error Message Exercises::
340 * Numbers Lists:: List have numbers, other lists, in them.
341 * Lisp Atoms:: Elemental entities.
342 * Whitespace in Lists:: Formating lists to be readable.
343 * Typing Lists:: How GNU Emacs helps you type lists.
347 * Complications:: Variables, Special forms, Lists within.
348 * Byte Compiling:: Specially processing code for speed.
352 * Evaluating Inner Lists:: Lists within lists...
356 * fill-column Example::
357 * Void Function:: The error message for a symbol
359 * Void Variable:: The error message for a symbol without a value.
363 * Data types:: Types of data passed to a function.
364 * Args as Variable or List:: An argument can be the value
365 of a variable or list.
366 * Variable Number of Arguments:: Some functions may take a
367 variable number of arguments.
368 * Wrong Type of Argument:: Passing an argument of the wrong type
370 * message:: A useful function for sending messages.
372 Setting the Value of a Variable
374 * Using set:: Setting values.
375 * Using setq:: Setting a quoted value.
376 * Counting:: Using @code{setq} to count.
378 Practicing Evaluation
380 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
382 * Buffer Names:: Buffers and files are different.
383 * Getting Buffers:: Getting a buffer itself, not merely its name.
384 * Switching Buffers:: How to change to another buffer.
385 * Buffer Size & Locations:: Where point is located and the size of
387 * Evaluation Exercise::
389 How To Write Function Definitions
391 * Primitive Functions::
392 * defun:: The @code{defun} special form.
393 * Install:: Install a function definition.
394 * Interactive:: Making a function interactive.
395 * Interactive Options:: Different options for @code{interactive}.
396 * Permanent Installation:: Installing code permanently.
397 * let:: Creating and initializing local variables.
399 * else:: If--then--else expressions.
400 * Truth & Falsehood:: What Lisp considers false and true.
401 * save-excursion:: Keeping track of point, mark, and buffer.
405 Install a Function Definition
407 * Effect of installation::
408 * Change a defun:: How to change a function definition.
410 Make a Function Interactive
412 * Interactive multiply-by-seven:: An overview.
413 * multiply-by-seven in detail:: The interactive version.
417 * Prevent confusion::
418 * Parts of let Expression::
419 * Sample let Expression::
420 * Uninitialized let Variables::
422 The @code{if} Special Form
424 * if in more detail::
425 * type-of-animal in detail:: An example of an @code{if} expression.
427 Truth and Falsehood in Emacs Lisp
429 * nil explained:: @code{nil} has two meanings.
431 @code{save-excursion}
433 * Point and mark:: A review of various locations.
434 * Template for save-excursion::
436 A Few Buffer--Related Functions
438 * Finding More:: How to find more information.
439 * simplified-beginning-of-buffer:: Shows @code{goto-char},
440 @code{point-min}, and @code{push-mark}.
441 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
442 * append-to-buffer:: Uses @code{save-excursion} and
443 @code{insert-buffer-substring}.
444 * Buffer Related Review:: Review.
447 The Definition of @code{mark-whole-buffer}
449 * mark-whole-buffer overview::
450 * Body of mark-whole-buffer:: Only three lines of code.
452 The Definition of @code{append-to-buffer}
454 * append-to-buffer overview::
455 * append interactive:: A two part interactive expression.
456 * append-to-buffer body:: Incorporates a @code{let} expression.
457 * append save-excursion:: How the @code{save-excursion} works.
459 A Few More Complex Functions
461 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
462 * insert-buffer:: Read-only, and with @code{or}.
463 * beginning-of-buffer:: Shows @code{goto-char},
464 @code{point-min}, and @code{push-mark}.
465 * Second Buffer Related Review::
466 * optional Exercise::
468 The Definition of @code{insert-buffer}
470 * insert-buffer code::
471 * insert-buffer interactive:: When you can read, but not write.
472 * insert-buffer body:: The body has an @code{or} and a @code{let}.
473 * if & or:: Using an @code{if} instead of an @code{or}.
474 * Insert or:: How the @code{or} expression works.
475 * Insert let:: Two @code{save-excursion} expressions.
477 The Interactive Expression in @code{insert-buffer}
479 * Read-only buffer:: When a buffer cannot be modified.
480 * b for interactive:: An existing buffer or else its name.
482 Complete Definition of @code{beginning-of-buffer}
484 * Optional Arguments::
485 * beginning-of-buffer opt arg:: Example with optional argument.
486 * beginning-of-buffer complete::
488 @code{beginning-of-buffer} with an Argument
490 * Disentangle beginning-of-buffer::
491 * Large buffer case::
492 * Small buffer case::
494 Narrowing and Widening
496 * Narrowing advantages:: The advantages of narrowing
497 * save-restriction:: The @code{save-restriction} special form.
498 * what-line:: The number of the line that point is on.
501 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
503 * Strange Names:: An historical aside: why the strange names?
504 * car & cdr:: Functions for extracting part of a list.
505 * cons:: Constructing a list.
506 * nthcdr:: Calling @code{cdr} repeatedly.
508 * setcar:: Changing the first element of a list.
509 * setcdr:: Changing the rest of a list.
515 * length:: How to find the length of a list.
517 Cutting and Storing Text
519 * Storing Text:: Text is stored in a list.
520 * zap-to-char:: Cutting out text up to a character.
521 * kill-region:: Cutting text out of a region.
522 * Digression into C:: Minor note on C programming language macros.
523 * defvar:: How to give a variable an initial value.
524 * copy-region-as-kill:: A definition for copying text.
525 * cons & search-fwd Review::
530 * Complete zap-to-char:: The complete implementation.
531 * zap-to-char interactive:: A three part interactive expression.
532 * zap-to-char body:: A short overview.
533 * search-forward:: How to search for a string.
534 * progn:: The @code{progn} special form.
535 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
539 * Complete kill-region:: The function definition.
540 * condition-case:: Dealing with a problem.
541 * delete-and-extract-region:: Doing the work.
543 Initializing a Variable with @code{defvar}
545 * See variable current value::
546 * defvar and asterisk:: An old-time convention.
548 @code{copy-region-as-kill}
550 * Complete copy-region-as-kill:: The complete function definition.
551 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
553 The Body of @code{copy-region-as-kill}
555 * last-command & this-command::
556 * kill-append function::
557 * kill-new function::
559 How Lists are Implemented
562 * Symbols as Chest:: Exploring a powerful metaphor.
567 * Kill Ring Overview:: The kill ring is a list.
568 * kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable.
569 * yank nthcdr Exercises::
573 * while:: Causing a stretch of code to repeat.
575 * Recursion:: Causing a function to call itself.
580 * Looping with while:: Repeat so long as test returns true.
581 * Loop Example:: A @code{while} loop that uses a list.
582 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
583 * Incrementing Loop:: A loop with an incrementing counter.
584 * Decrementing Loop:: A loop with a decrementing counter.
586 A Loop with an Incrementing Counter
588 * Incrementing Example:: Counting pebbles in a triangle.
589 * Inc Example parts:: The parts of the function definition.
590 * Inc Example altogether:: Putting the function definition together.
592 Loop with a Decrementing Counter
594 * Decrementing Example:: More pebbles on the beach.
595 * Dec Example parts:: The parts of the function definition.
596 * Dec Example altogether:: Putting the function definition together.
598 Save your time: @code{dolist} and @code{dotimes}
605 * Building Robots:: Same model, different serial number ...
606 * Recursive Definition Parts:: Walk until you stop ...
607 * Recursion with list:: Using a list as the test whether to recurse.
608 * Recursive triangle function::
609 * Recursion with cond::
610 * Recursive Patterns:: Often used templates.
611 * No Deferment:: Don't store up work ...
612 * No deferment solution::
614 Recursion in Place of a Counter
616 * Recursive Example arg of 1 or 2::
617 * Recursive Example arg of 3 or 4::
625 Regular Expression Searches
627 * sentence-end:: The regular expression for @code{sentence-end}.
628 * re-search-forward:: Very similar to @code{search-forward}.
629 * forward-sentence:: A straightforward example of regexp search.
630 * forward-paragraph:: A somewhat complex example.
631 * etags:: How to create your own @file{TAGS} table.
633 * re-search Exercises::
635 @code{forward-sentence}
637 * Complete forward-sentence::
638 * fwd-sentence while loops:: Two @code{while} loops.
639 * fwd-sentence re-search:: A regular expression search.
641 @code{forward-paragraph}: a Goldmine of Functions
643 * forward-paragraph in brief:: Key parts of the function definition.
644 * fwd-para let:: The @code{let*} expression.
645 * fwd-para while:: The forward motion @code{while} loop.
646 * fwd-para between paragraphs:: Movement between paragraphs.
647 * fwd-para within paragraph:: Movement within paragraphs.
648 * fwd-para no fill prefix:: When there is no fill prefix.
649 * fwd-para with fill prefix:: When there is a fill prefix.
650 * fwd-para summary:: Summary of @code{forward-paragraph} code.
652 Counting: Repetition and Regexps
655 * count-words-region:: Use a regexp, but find a problem.
656 * recursive-count-words:: Start with case of no words in region.
657 * Counting Exercise::
659 The @code{count-words-region} Function
661 * Design count-words-region:: The definition using a @code{while} loop.
662 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
664 Counting Words in a @code{defun}
666 * Divide and Conquer::
667 * Words and Symbols:: What to count?
668 * Syntax:: What constitutes a word or symbol?
669 * count-words-in-defun:: Very like @code{count-words}.
670 * Several defuns:: Counting several defuns in a file.
671 * Find a File:: Do you want to look at a file?
672 * lengths-list-file:: A list of the lengths of many definitions.
673 * Several files:: Counting in definitions in different files.
674 * Several files recursively:: Recursively counting in different files.
675 * Prepare the data:: Prepare the data for display in a graph.
677 Count Words in @code{defuns} in Different Files
679 * lengths-list-many-files:: Return a list of the lengths of defuns.
680 * append:: Attach one list to another.
682 Prepare the Data for Display in a Graph
684 * Sorting:: Sorting lists.
685 * Files List:: Making a list of files.
686 * Counting function definitions::
690 * Columns of a graph::
691 * graph-body-print:: How to print the body of a graph.
692 * recursive-graph-body-print::
694 * Line Graph Exercise::
696 Your @file{.emacs} File
698 * Default Configuration::
699 * Site-wide Init:: You can write site-wide init files.
700 * defcustom:: Emacs will write code for you.
701 * Beginning a .emacs File:: How to write a @code{.emacs file}.
702 * Text and Auto-fill:: Automatically wrap lines.
703 * Mail Aliases:: Use abbreviations for email addresses.
704 * Indent Tabs Mode:: Don't use tabs with @TeX{}
705 * Keybindings:: Create some personal keybindings.
706 * Keymaps:: More about key binding.
707 * Loading Files:: Load (i.e., evaluate) files automatically.
708 * Autoload:: Make functions available.
709 * Simple Extension:: Define a function; bind it to a key.
710 * X11 Colors:: Colors in version 19 in X.
712 * Mode Line:: How to customize your mode line.
716 * debug:: How to use the built-in debugger.
717 * debug-on-entry:: Start debugging when you call a function.
718 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
719 * edebug:: How to use Edebug, a source level debugger.
720 * Debugging Exercises::
722 Handling the Kill Ring
724 * rotate-yank-pointer:: Move a pointer along a list and around.
725 * yank:: Paste a copy of a clipped element.
726 * yank-pop:: Insert first element pointed to.
729 The @code{rotate-yank-pointer} Function
731 * Understanding rotate-yk-ptr::
732 * rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
734 The Body of @code{rotate-yank-pointer}
736 * Digression concerning error:: How to mislead humans, but not computers.
737 * rotate-yk-ptr else-part:: The else-part of the @code{if} expression.
738 * Remainder Function:: The remainder, @code{%}, function.
739 * rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}.
740 * kill-rng-yk-ptr last elt:: Pointing to the last element.
744 * rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}.
745 * rotate-yk-ptr negative arg:: Pass a negative argument.
747 A Graph with Labelled Axes
750 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
751 * print-Y-axis:: Print a label for the vertical axis.
752 * print-X-axis:: Print a horizontal label.
753 * Print Whole Graph:: The function to print a complete graph.
755 The @code{print-Y-axis} Function
757 * Height of label:: What height for the Y axis?
758 * Compute a Remainder:: How to compute the remainder of a division.
759 * Y Axis Element:: Construct a line for the Y axis.
760 * Y-axis-column:: Generate a list of Y axis labels.
761 * print-Y-axis Penultimate:: A not quite final version.
763 The @code{print-X-axis} Function
765 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
766 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
768 Printing the Whole Graph
770 * The final version:: A few changes.
771 * Test print-graph:: Run a short test.
772 * Graphing words in defuns:: Executing the final code.
773 * lambda:: How to write an anonymous function.
774 * mapcar:: Apply a function to elements of a list.
775 * Another Bug:: Yet another bug @dots{} most insidious.
776 * Final printed graph:: The graph itself!
781 @c >>>> Set pageno appropriately <<<<
783 @c The first page of the Preface is a roman numeral; it is the first
784 @c right handed page after the Table of Contents; hence the following
785 @c setting must be for an odd negative number.
791 @node Preface, List Processing, Top, Top
792 @comment node-name, next, previous, up
795 Most of the GNU Emacs integrated environment is written in the programming
796 language called Emacs Lisp. The code written in this programming
797 language is the software---the sets of instructions---that tell the
798 computer what to do when you give it commands. Emacs is designed so
799 that you can write new code in Emacs Lisp and easily install it as an
800 extension to the editor.
802 (GNU Emacs is sometimes called an ``extensible editor'', but it does
803 much more than provide editing capabilities. It is better to refer to
804 Emacs as an ``extensible computing environment''. However, that
805 phrase is quite a mouthful. It is easier to refer to Emacs simply as
806 an editor. Moreover, everything you do in Emacs---find the Mayan date
807 and phases of the moon, simplify polynomials, debug code, manage
808 files, read letters, write books---all these activities are kinds of
809 editing in the most general sense of the word.)
812 * Why:: Why learn Emacs Lisp?
813 * On Reading this Text:: Read, gain familiarity, pick up habits....
814 * Who You Are:: For whom this is written.
816 * Note for Novices:: You can read this as a novice.
820 @node Why, On Reading this Text, Preface, Preface
822 @unnumberedsec Why Study Emacs Lisp?
825 Although Emacs Lisp is usually thought of in association only with Emacs,
826 it is a full computer programming language. You can use Emacs Lisp as
827 you would any other programming language.
829 Perhaps you want to understand programming; perhaps you want to extend
830 Emacs; or perhaps you want to become a programmer. This introduction to
831 Emacs Lisp is designed to get you started: to guide you in learning the
832 fundamentals of programming, and more importantly, to show you how you
833 can teach yourself to go further.
835 @node On Reading this Text, Who You Are, Why, Preface
836 @comment node-name, next, previous, up
837 @unnumberedsec On Reading this Text
839 All through this document, you will see little sample programs you can
840 run inside of Emacs. If you read this document in Info inside of GNU
841 Emacs, you can run the programs as they appear. (This is easy to do and
842 is explained when the examples are presented.) Alternatively, you can
843 read this introduction as a printed book while sitting beside a computer
844 running Emacs. (This is what I like to do; I like printed books.) If
845 you don't have a running Emacs beside you, you can still read this book,
846 but in this case, it is best to treat it as a novel or as a travel guide
847 to a country not yet visited: interesting, but not the same as being
850 Much of this introduction is dedicated to walk-throughs or guided tours
851 of code used in GNU Emacs. These tours are designed for two purposes:
852 first, to give you familiarity with real, working code (code you use
853 every day); and, second, to give you familiarity with the way Emacs
854 works. It is interesting to see how a working environment is
857 hope that you will pick up the habit of browsing through source code.
858 You can learn from it and mine it for ideas. Having GNU Emacs is like
859 having a dragon's cave of treasures.
861 In addition to learning about Emacs as an editor and Emacs Lisp as a
862 programming language, the examples and guided tours will give you an
863 opportunity to get acquainted with Emacs as a Lisp programming
864 environment. GNU Emacs supports programming and provides tools that
865 you will want to become comfortable using, such as @kbd{M-.} (the key
866 which invokes the @code{find-tag} command). You will also learn about
867 buffers and other objects that are part of the environment.
868 Learning about these features of Emacs is like learning new routes
869 around your home town.
872 In addition, I have written several programs as extended examples.
873 Although these are examples, the programs are real. I use them.
874 Other people use them. You may use them. Beyond the fragments of
875 programs used for illustrations, there is very little in here that is
876 `just for teaching purposes'; what you see is used. This is a great
877 advantage of Emacs Lisp: it is easy to learn to use it for work.
880 Finally, I hope to convey some of the skills for using Emacs to
881 learn aspects of programming that you don't know. You can often use
882 Emacs to help you understand what puzzles you or to find out how to do
883 something new. This self-reliance is not only a pleasure, but an
886 @node Who You Are, Lisp History, On Reading this Text, Preface
887 @comment node-name, next, previous, up
888 @unnumberedsec For Whom This is Written
890 This text is written as an elementary introduction for people who are
891 not programmers. If you are a programmer, you may not be satisfied with
892 this primer. The reason is that you may have become expert at reading
893 reference manuals and be put off by the way this text is organized.
895 An expert programmer who reviewed this text said to me:
898 @i{I prefer to learn from reference manuals. I ``dive into'' each
899 paragraph, and ``come up for air'' between paragraphs.}
901 @i{When I get to the end of a paragraph, I assume that that subject is
902 done, finished, that I know everything I need (with the
903 possible exception of the case when the next paragraph starts talking
904 about it in more detail). I expect that a well written reference manual
905 will not have a lot of redundancy, and that it will have excellent
906 pointers to the (one) place where the information I want is.}
909 This introduction is not written for this person!
911 Firstly, I try to say everything at least three times: first, to
912 introduce it; second, to show it in context; and third, to show it in a
913 different context, or to review it.
915 Secondly, I hardly ever put all the information about a subject in one
916 place, much less in one paragraph. To my way of thinking, that imposes
917 too heavy a burden on the reader. Instead I try to explain only what
918 you need to know at the time. (Sometimes I include a little extra
919 information so you won't be surprised later when the additional
920 information is formally introduced.)
922 When you read this text, you are not expected to learn everything the
923 first time. Frequently, you need only make, as it were, a `nodding
924 acquaintance' with some of the items mentioned. My hope is that I have
925 structured the text and given you enough hints that you will be alert to
926 what is important, and concentrate on it.
928 You will need to ``dive into'' some paragraphs; there is no other way
929 to read them. But I have tried to keep down the number of such
930 paragraphs. This book is intended as an approachable hill, rather than
931 as a daunting mountain.
933 This introduction to @cite{Programming in Emacs Lisp} has a companion
936 @cite{The GNU Emacs Lisp Reference Manual}.
939 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
940 Emacs Lisp Reference Manual}.
942 The reference manual has more detail than this introduction. In the
943 reference manual, all the information about one topic is concentrated
944 in one place. You should turn to it if you are like the programmer
945 quoted above. And, of course, after you have read this
946 @cite{Introduction}, you will find the @cite{Reference Manual} useful
947 when you are writing your own programs.
949 @node Lisp History, Note for Novices, Who You Are, Preface
950 @unnumberedsec Lisp History
953 Lisp was first developed in the late 1950s at the Massachusetts
954 Institute of Technology for research in artificial intelligence. The
955 great power of the Lisp language makes it superior for other purposes as
956 well, such as writing editor commands and integrated environments.
960 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT
961 in the 1960s. It is somewhat inspired by Common Lisp, which became a
962 standard in the 1980s. However, Emacs Lisp is much simpler than Common
963 Lisp. (The standard Emacs distribution contains an optional extensions
964 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.)
966 @node Note for Novices, Thank You, Lisp History, Preface
967 @comment node-name, next, previous, up
968 @unnumberedsec A Note for Novices
970 If you don't know GNU Emacs, you can still read this document
971 profitably. However, I recommend you learn Emacs, if only to learn to
972 move around your computer screen. You can teach yourself how to use
973 Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This
974 means you press and release the @key{CTRL} key and the @kbd{h} at the
975 same time, and then press and release @kbd{t}.)
977 Also, I often refer to one of Emacs' standard commands by listing the
978 keys which you press to invoke the command and then giving the name of
979 the command in parentheses, like this: @kbd{M-C-\}
980 (@code{indent-region}). What this means is that the
981 @code{indent-region} command is customarily invoked by typing
982 @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to
983 invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, ,
984 Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your
985 @key{META} key, @key{CTRL} key and @key{\} key all at the same time.
986 (On many modern keyboards the @key{META} key is labelled
988 Sometimes a combination like this is called a keychord, since it is
989 similar to the way you play a chord on a piano. If your keyboard does
990 not have a @key{META} key, the @key{ESC} key prefix is used in place
991 of it. In this case, @kbd{M-C-\} means that you press and release your
992 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
993 the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key
994 along with the key that is labelled @key{ALT} and, at the same time,
995 press the @key{\} key.
997 In addition to typing a lone keychord, you can prefix what you type
998 with @kbd{C-u}, which is called the `universal argument'. The
999 @kbd{C-u} keychord passes an argument to the subsequent command.
1000 Thus, to indent a region of plain text by 6 spaces, mark the region,
1001 and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number,
1002 Emacs either passes the number 4 to the command or otherwise runs the
1003 command differently than it would otherwise.) @xref{Arguments, ,
1004 Numeric Arguments, emacs, The GNU Emacs Manual}.
1006 If you are reading this in Info using GNU Emacs, you can read through
1007 this whole document just by pressing the space bar, @key{SPC}.
1008 (To learn about Info, type @kbd{C-h i} and then select Info.)
1010 A note on terminology: when I use the word Lisp alone, I often am
1011 referring to the various dialects of Lisp in general, but when I speak
1012 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
1014 @node Thank You, , Note for Novices, Preface
1015 @comment node-name, next, previous, up
1016 @unnumberedsec Thank You
1018 My thanks to all who helped me with this book. My especial thanks to
1019 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
1020 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@:
1021 Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both
1022 @w{Philip Johnson} and @w{David Stampe} for their patient
1023 encouragement. My mistakes are my own.
1029 @c ================ Beginning of main text ================
1031 @c Start main text on right-hand (verso) page
1034 \par\vfill\supereject
1037 \par\vfill\supereject
1039 \par\vfill\supereject
1041 \par\vfill\supereject
1047 @evenheading @thispage @| @| @thischapter
1048 @oddheading @thissection @| @| @thispage
1052 @node List Processing, Practicing Evaluation, Preface, Top
1053 @comment node-name, next, previous, up
1054 @chapter List Processing
1056 To the untutored eye, Lisp is a strange programming language. In Lisp
1057 code there are parentheses everywhere. Some people even claim that
1058 the name stands for `Lots of Isolated Silly Parentheses'. But the
1059 claim is unwarranted. Lisp stands for LISt Processing, and the
1060 programming language handles @emph{lists} (and lists of lists) by
1061 putting them between parentheses. The parentheses mark the boundaries
1062 of the list. Sometimes a list is preceded by a single apostrophe or
1063 quotation mark, @samp{'}@footnote{The single apostrophe or quotation
1064 mark is an abbreviation for the function @code{quote}; you need not
1065 think about functions now; functions are defined in @ref{Making
1066 Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
1069 * Lisp Lists:: What are lists?
1070 * Run a Program:: Any list in Lisp is a program ready to run.
1071 * Making Errors:: Generating an error message.
1072 * Names & Definitions:: Names of symbols and function definitions.
1073 * Lisp Interpreter:: What the Lisp interpreter does.
1074 * Evaluation:: Running a program.
1075 * Variables:: Returning a value from a variable.
1076 * Arguments:: Passing information to a function.
1077 * set & setq:: Setting the value of a variable.
1078 * Summary:: The major points.
1079 * Error Message Exercises::
1082 @node Lisp Lists, Run a Program, List Processing, List Processing
1083 @comment node-name, next, previous, up
1087 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}.
1088 This list is preceded by a single apostrophe. It could just as well be
1089 written as follows, which looks more like the kind of list you are likely
1090 to be familiar with:
1102 The elements of this list are the names of the four different flowers,
1103 separated from each other by whitespace and surrounded by parentheses,
1104 like flowers in a field with a stone wall around them.
1105 @cindex Flowers in a field
1108 * Numbers Lists:: List have numbers, other lists, in them.
1109 * Lisp Atoms:: Elemental entities.
1110 * Whitespace in Lists:: Formating lists to be readable.
1111 * Typing Lists:: How GNU Emacs helps you type lists.
1114 @node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
1116 @unnumberedsubsec Numbers, Lists inside of Lists
1119 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}.
1120 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each
1121 separated by whitespace.
1123 In Lisp, both data and programs are represented the same way; that is,
1124 they are both lists of words, numbers, or other lists, separated by
1125 whitespace and surrounded by parentheses. (Since a program looks like
1126 data, one program may easily serve as data for another; this is a very
1127 powerful feature of Lisp.) (Incidentally, these two parenthetical
1128 remarks are @emph{not} Lisp lists, because they contain @samp{;} and
1129 @samp{.} as punctuation marks.)
1132 Here is another list, this time with a list inside of it:
1135 '(this list has (a list inside of it))
1138 The components of this list are the words @samp{this}, @samp{list},
1139 @samp{has}, and the list @samp{(a list inside of it)}. The interior
1140 list is made up of the words @samp{a}, @samp{list}, @samp{inside},
1141 @samp{of}, @samp{it}.
1143 @node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists
1144 @comment node-name, next, previous, up
1145 @subsection Lisp Atoms
1148 In Lisp, what we have been calling words are called @dfn{atoms}. This
1149 term comes from the historical meaning of the word atom, which means
1150 `indivisible'. As far as Lisp is concerned, the words we have been
1151 using in the lists cannot be divided into any smaller parts and still
1152 mean the same thing as part of a program; likewise with numbers and
1153 single character symbols like @samp{+}. On the other hand, unlike an
1154 atom, a list can be split into parts. (@xref{car cdr & cons, ,
1155 @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
1157 In a list, atoms are separated from each other by whitespace. They can be
1158 right next to a parenthesis.
1160 @cindex @samp{empty list} defined
1161 Technically speaking, a list in Lisp consists of parentheses surrounding
1162 atoms separated by whitespace or surrounding other lists or surrounding
1163 both atoms and other lists. A list can have just one atom in it or
1164 have nothing in it at all. A list with nothing in it looks like this:
1165 @code{()}, and is called the @dfn{empty list}. Unlike anything else, an
1166 empty list is considered both an atom and a list at the same time.
1168 @cindex Symbolic expressions, introduced
1169 @cindex @samp{expression} defined
1170 @cindex @samp{form} defined
1171 The printed representation of both atoms and lists are called
1172 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
1173 The word @dfn{expression} by itself can refer to either the printed
1174 representation, or to the atom or list as it is held internally in the
1175 computer. Often, people use the term @dfn{expression}
1176 indiscriminately. (Also, in many texts, the word @dfn{form} is used
1177 as a synonym for expression.)
1179 Incidentally, the atoms that make up our universe were named such when
1180 they were thought to be indivisible; but it has been found that physical
1181 atoms are not indivisible. Parts can split off an atom or it can
1182 fission into two parts of roughly equal size. Physical atoms were named
1183 prematurely, before their truer nature was found. In Lisp, certain
1184 kinds of atom, such as an array, can be separated into parts; but the
1185 mechanism for doing this is different from the mechanism for splitting a
1186 list. As far as list operations are concerned, the atoms of a list are
1189 As in English, the meanings of the component letters of a Lisp atom
1190 are different from the meaning the letters make as a word. For
1191 example, the word for the South American sloth, the @samp{ai}, is
1192 completely different from the two words, @samp{a}, and @samp{i}.
1194 There are many kinds of atom in nature but only a few in Lisp: for
1195 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such
1196 as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have
1197 listed in the examples above are all symbols. In everyday Lisp
1198 conversation, the word ``atom'' is not often used, because programmers
1199 usually try to be more specific about what kind of atom they are dealing
1200 with. Lisp programming is mostly about symbols (and sometimes numbers)
1201 within lists. (Incidentally, the preceding three word parenthetical
1202 remark is a proper list in Lisp, since it consists of atoms, which in
1203 this case are symbols, separated by whitespace and enclosed by
1204 parentheses, without any non-Lisp punctuation.)
1207 In addition, text between double quotation marks---even sentences or
1208 paragraphs---is an atom. Here is an example:
1209 @cindex Text between double quotation marks
1212 '(this list includes "text between quotation marks.")
1215 @cindex @samp{string} defined
1217 In Lisp, all of the quoted text including the punctuation mark and the
1218 blank spaces is a single atom. This kind of atom is called a
1219 @dfn{string} (for `string of characters') and is the sort of thing that
1220 is used for messages that a computer can print for a human to read.
1221 Strings are a different kind of atom than numbers or symbols and are
1224 @node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists
1225 @comment node-name, next, previous, up
1226 @subsection Whitespace in Lists
1227 @cindex Whitespace in lists
1230 The amount of whitespace in a list does not matter. From the point of view
1231 of the Lisp language,
1242 is exactly the same as this:
1245 '(this list looks like this)
1248 Both examples show what to Lisp is the same list, the list made up of
1249 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and
1250 @samp{this} in that order.
1252 Extra whitespace and newlines are designed to make a list more readable
1253 by humans. When Lisp reads the expression, it gets rid of all the extra
1254 whitespace (but it needs to have at least one space between atoms in
1255 order to tell them apart.)
1257 Odd as it seems, the examples we have seen cover almost all of what Lisp
1258 lists look like! Every other list in Lisp looks more or less like one
1259 of these examples, except that the list may be longer and more complex.
1260 In brief, a list is between parentheses, a string is between quotation
1261 marks, a symbol looks like a word, and a number looks like a number.
1262 (For certain situations, square brackets, dots and a few other special
1263 characters may be used; however, we will go quite far without them.)
1265 @node Typing Lists, , Whitespace in Lists, Lisp Lists
1266 @comment node-name, next, previous, up
1267 @subsection GNU Emacs Helps You Type Lists
1268 @cindex Help typing lists
1269 @cindex Formatting help
1271 When you type a Lisp expression in GNU Emacs using either Lisp
1272 Interaction mode or Emacs Lisp mode, you have available to you several
1273 commands to format the Lisp expression so it is easy to read. For
1274 example, pressing the @key{TAB} key automatically indents the line the
1275 cursor is on by the right amount. A command to properly indent the
1276 code in a region is customarily bound to @kbd{M-C-\}. Indentation is
1277 designed so that you can see which elements of a list belong to which
1278 list---elements of a sub-list are indented more than the elements of
1281 In addition, when you type a closing parenthesis, Emacs momentarily
1282 jumps the cursor back to the matching opening parenthesis, so you can
1283 see which one it is. This is very useful, since every list you type
1284 in Lisp must have its closing parenthesis match its opening
1285 parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs
1286 Manual}, for more information about Emacs' modes.)
1288 @node Run a Program, Making Errors, Lisp Lists, List Processing
1289 @comment node-name, next, previous, up
1290 @section Run a Program
1291 @cindex Run a program
1292 @cindex Program, running one
1294 @cindex @samp{evaluate} defined
1295 A list in Lisp---any list---is a program ready to run. If you run it
1296 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one
1297 of three things: do nothing except return to you the list itself; send
1298 you an error message; or, treat the first symbol in the list as a
1299 command to do something. (Usually, of course, it is the last of these
1300 three things that you really want!)
1302 @c use code for the single apostrophe, not samp.
1303 The single apostrophe, @code{'}, that I put in front of some of the
1304 example lists in preceding sections is called a @dfn{quote}; when it
1305 precedes a list, it tells Lisp to do nothing with the list, other than
1306 take it as it is written. But if there is no quote preceding a list,
1307 the first item of the list is special: it is a command for the computer
1308 to obey. (In Lisp, these commands are called @emph{functions}.) The list
1309 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp
1310 understands that the @code{+} is an instruction to do something with the
1311 rest of the list: add the numbers that follow.
1314 If you are reading this inside of GNU Emacs in Info, here is how you can
1315 evaluate such a list: place your cursor immediately after the right
1316 hand parenthesis of the following list and then type @kbd{C-x C-e}:
1322 @c use code for the number four, not samp.
1324 You will see the number @code{4} appear in the echo area. (In the
1325 jargon, what you have just done is ``evaluate the list.'' The echo area
1326 is the line at the bottom of the screen that displays or ``echoes''
1327 text.) Now try the same thing with a quoted list: place the cursor
1328 right after the following list and type @kbd{C-x C-e}:
1331 '(this is a quoted list)
1335 You will see @code{(this is a quoted list)} appear in the echo area.
1337 @cindex Lisp interpreter, explained
1338 @cindex Interpreter, Lisp, explained
1339 In both cases, what you are doing is giving a command to the program
1340 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
1341 interpreter a command to evaluate the expression. The name of the Lisp
1342 interpreter comes from the word for the task done by a human who comes
1343 up with the meaning of an expression---who ``interprets'' it.
1345 You can also evaluate an atom that is not part of a list---one that is
1346 not surrounded by parentheses; again, the Lisp interpreter translates
1347 from the humanly readable expression to the language of the computer.
1348 But before discussing this (@pxref{Variables}), we will discuss what the
1349 Lisp interpreter does when you make an error.
1351 @node Making Errors, Names & Definitions, Run a Program, List Processing
1352 @comment node-name, next, previous, up
1353 @section Generate an Error Message
1354 @cindex Generate an error message
1355 @cindex Error message generation
1357 Partly so you won't worry if you do it accidentally, we will now give
1358 a command to the Lisp interpreter that generates an error message.
1359 This is a harmless activity; and indeed, we will often try to generate
1360 error messages intentionally. Once you understand the jargon, error
1361 messages can be informative. Instead of being called ``error''
1362 messages, they should be called ``help'' messages. They are like
1363 signposts to a traveller in a strange country; deciphering them can be
1364 hard, but once understood, they can point the way.
1366 The error message is generated by a built-in GNU Emacs debugger. We
1367 will `enter the debugger'. You get out of the debugger by typing @code{q}.
1369 What we will do is evaluate a list that is not quoted and does not
1370 have a meaningful command as its first element. Here is a list almost
1371 exactly the same as the one we just used, but without the single-quote
1372 in front of it. Position the cursor right after it and type @kbd{C-x
1376 (this is an unquoted list)
1380 What you see depends on which version of Emacs you are running. GNU
1381 Emacs version 21 provides more information than version 20 and before.
1382 First, the more recent result of generating an error; then the
1383 earlier, version 20 result.
1387 In GNU Emacs version 21, a @file{*Backtrace*} window will open up and
1388 you will see the following in it:
1392 ---------- Buffer: *Backtrace* ----------
1393 Debugger entered--Lisp error: (void-function this)
1394 (this is an unquoted list)
1395 eval((this is an unquoted list))
1396 eval-last-sexp-1(nil)
1398 call-interactively(eval-last-sexp)
1399 ---------- Buffer: *Backtrace* ----------
1405 Your cursor will be in this window (you may have to wait a few seconds
1406 before it becomes visible). To quit the debugger and make the
1407 debugger window go away, type:
1414 Please type @kbd{q} right now, so you become confident that you can
1415 get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter
1418 @cindex @samp{function} defined
1419 Based on what we already know, we can almost read this error message.
1421 You read the @file{*Backtrace*} buffer from the bottom up; it tells
1422 you what Emacs did. When you typed @kbd{C-x C-e}, you made an
1423 interactive call to the command @code{eval-last-sexp}. @code{eval} is
1424 an abbreviation for `evaluate' and @code{sexp} is an abbreviation for
1425 `symbolic expression'. The command means `evaluate last symbolic
1426 expression', which is the expression just before your cursor.
1428 Each line above tells you what the Lisp interpreter evaluated next.
1429 The most recent action is at the top. The buffer is called the
1430 @file{*Backtrace*} buffer because it enables you to track Emacs
1434 At the top of the @file{*Backtrace*} buffer, you see the line:
1437 Debugger entered--Lisp error: (void-function this)
1441 The Lisp interpreter tried to evaluate the first atom of the list, the
1442 word @samp{this}. It is this action that generated the error message
1443 @samp{void-function this}.
1445 The message contains the words @samp{void-function} and @samp{this}.
1447 @cindex @samp{function} defined
1448 The word @samp{function} was mentioned once before. It is a very
1449 important word. For our purposes, we can define it by saying that a
1450 @dfn{function} is a set of instructions to the computer that tell the
1451 computer to do something.
1453 Now we can begin to understand the error message: @samp{void-function
1454 this}. The function (that is, the word @samp{this}) does not have a
1455 definition of any set of instructions for the computer to carry out.
1457 The slightly odd word, @samp{void-function}, is designed to cover the
1458 way Emacs Lisp is implemented, which is that when a symbol does not
1459 have a function definition attached to it, the place that should
1460 contain the instructions is `void'.
1462 On the other hand, since we were able to add 2 plus 2 successfully, by
1463 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
1464 have a set of instructions for the computer to obey and those
1465 instructions must be to add the numbers that follow the @code{+}.
1468 In GNU Emacs version 20, and in earlier versions, you will see only
1469 one line of error message; it will appear in the echo area and look
1473 Symbol's function definition is void:@: this
1477 (Also, your terminal may beep at you---some do, some don't; and others
1478 blink. This is just a device to get your attention.) The message goes
1479 away as soon as you type another key, even just to move the cursor.
1481 We know the meaning of the word @samp{Symbol}. It refers to the first
1482 atom of the list, the word @samp{this}. The word @samp{function}
1483 refers to the instructions that tell the computer what to do.
1484 (Technically, the symbol tells the computer where to find the
1485 instructions, but this is a complication we can ignore for the
1488 The error message can be understood: @samp{Symbol's function
1489 definition is void:@: this}. The symbol (that is, the word
1490 @samp{this}) lacks instructions for the computer to carry out.
1492 @node Names & Definitions, Lisp Interpreter, Making Errors, List Processing
1493 @comment node-name, next, previous, up
1494 @section Symbol Names and Function Definitions
1495 @cindex Symbol names
1497 We can articulate another characteristic of Lisp based on what we have
1498 discussed so far---an important characteristic: a symbol, like
1499 @code{+}, is not itself the set of instructions for the computer to
1500 carry out. Instead, the symbol is used, perhaps temporarily, as a way
1501 of locating the definition or set of instructions. What we see is the
1502 name through which the instructions can be found. Names of people
1503 work the same way. I can be referred to as @samp{Bob}; however, I am
1504 not the letters @samp{B}, @samp{o}, @samp{b} but am, or were, the
1505 consciousness consistently associated with a particular life-form.
1506 The name is not me, but it can be used to refer to me.
1508 In Lisp, one set of instructions can be attached to several names.
1509 For example, the computer instructions for adding numbers can be
1510 linked to the symbol @code{plus} as well as to the symbol @code{+}
1511 (and are in some dialects of Lisp). Among humans, I can be referred
1512 to as @samp{Robert} as well as @samp{Bob} and by other words as well.
1514 On the other hand, a symbol can have only one function definition
1515 attached to it at a time. Otherwise, the computer would be confused as
1516 to which definition to use. If this were the case among people, only
1517 one person in the world could be named @samp{Bob}. However, the function
1518 definition to which the name refers can be changed readily.
1519 (@xref{Install, , Install a Function Definition}.)
1521 Since Emacs Lisp is large, it is customary to name symbols in a way
1522 that identifies the part of Emacs to which the function belongs.
1523 Thus, all the names for functions that deal with Texinfo start with
1524 @samp{texinfo-} and those for functions that deal with reading mail
1525 start with @samp{rmail-}.
1527 @node Lisp Interpreter, Evaluation, Names & Definitions, List Processing
1528 @comment node-name, next, previous, up
1529 @section The Lisp Interpreter
1530 @cindex Lisp interpreter, what it does
1531 @cindex Interpreter, what it does
1533 Based on what we have seen, we can now start to figure out what the
1534 Lisp interpreter does when we command it to evaluate a list.
1535 First, it looks to see whether there is a quote before the list; if
1536 there is, the interpreter just gives us the list. On the other
1537 hand, if there is no quote, the interpreter looks at the first element
1538 in the list and sees whether it has a function definition. If it does,
1539 the interpreter carries out the instructions in the function definition.
1540 Otherwise, the interpreter prints an error message.
1542 This is how Lisp works. Simple. There are added complications which we
1543 will get to in a minute, but these are the fundamentals. Of course, to
1544 write Lisp programs, you need to know how to write function definitions
1545 and attach them to names, and how to do this without confusing either
1546 yourself or the computer.
1549 * Complications:: Variables, Special forms, Lists within.
1550 * Byte Compiling:: Specially processing code for speed.
1553 @node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
1555 @unnumberedsubsec Complications
1558 Now, for the first complication. In addition to lists, the Lisp
1559 interpreter can evaluate a symbol that is not quoted and does not have
1560 parentheses around it. The Lisp interpreter will attempt to determine
1561 the symbol's value as a @dfn{variable}. This situation is described
1562 in the section on variables. (@xref{Variables}.)
1564 @cindex Special form
1565 The second complication occurs because some functions are unusual and do
1566 not work in the usual manner. Those that don't are called @dfn{special
1567 forms}. They are used for special jobs, like defining a function, and
1568 there are not many of them. In the next few chapters, you will be
1569 introduced to several of the more important special forms.
1571 The third and final complication is this: if the function that the
1572 Lisp interpreter is looking at is not a special form, and if it is part
1573 of a list, the Lisp interpreter looks to see whether the list has a list
1574 inside of it. If there is an inner list, the Lisp interpreter first
1575 figures out what it should do with the inside list, and then it works on
1576 the outside list. If there is yet another list embedded inside the
1577 inner list, it works on that one first, and so on. It always works on
1578 the innermost list first. The interpreter works on the innermost list
1579 first, to evaluate the result of that list. The result may be
1580 used by the enclosing expression.
1582 Otherwise, the interpreter works left to right, from one expression to
1585 @node Byte Compiling, , Complications, Lisp Interpreter
1586 @subsection Byte Compiling
1587 @cindex Byte compiling
1589 One other aspect of interpreting: the Lisp interpreter is able to
1590 interpret two kinds of entity: humanly readable code, on which we will
1591 focus exclusively, and specially processed code, called @dfn{byte
1592 compiled} code, which is not humanly readable. Byte compiled code
1593 runs faster than humanly readable code.
1595 You can transform humanly readable code into byte compiled code by
1596 running one of the compile commands such as @code{byte-compile-file}.
1597 Byte compiled code is usually stored in a file that ends with a
1598 @file{.elc} extension rather than a @file{.el} extension. You will
1599 see both kinds of file in the @file{emacs/lisp} directory; the files
1600 to read are those with @file{.el} extensions.
1602 As a practical matter, for most things you might do to customize or
1603 extend Emacs, you do not need to byte compile; and I will not discuss
1604 the topic here. @xref{Byte Compilation, , Byte Compilation, elisp,
1605 The GNU Emacs Lisp Reference Manual}, for a full description of byte
1608 @node Evaluation, Variables, Lisp Interpreter, List Processing
1609 @comment node-name, next, previous, up
1613 When the Lisp interpreter works on an expression, the term for the
1614 activity is called @dfn{evaluation}. We say that the interpreter
1615 `evaluates the expression'. I've used this term several times before.
1616 The word comes from its use in everyday language, `to ascertain the
1617 value or amount of; to appraise', according to @cite{Webster's New
1618 Collegiate Dictionary}.
1620 After evaluating an expression, the Lisp interpreter will most likely
1621 @dfn{return} the value that the computer produces by carrying out the
1622 instructions it found in the function definition, or perhaps it will
1623 give up on that function and produce an error message. (The interpreter
1624 may also find itself tossed, so to speak, to a different function or it
1625 may attempt to repeat continually what it is doing for ever and ever in
1626 what is called an `infinite loop'. These actions are less common; and
1627 we can ignore them.) Most frequently, the interpreter returns a value.
1629 @cindex @samp{side effect} defined
1630 At the same time the interpreter returns a value, it may do something
1631 else as well, such as move a cursor or copy a file; this other kind of
1632 action is called a @dfn{side effect}. Actions that we humans think are
1633 important, such as printing results, are often ``side effects'' to the
1634 Lisp interpreter. The jargon can sound peculiar, but it turns out that
1635 it is fairly easy to learn to use side effects.
1637 In summary, evaluating a symbolic expression most commonly causes the
1638 Lisp interpreter to return a value and perhaps carry out a side effect;
1639 or else produce an error.
1642 * Evaluating Inner Lists:: Lists within lists...
1645 @node Evaluating Inner Lists, , Evaluation, Evaluation
1646 @comment node-name, next, previous, up
1647 @subsection Evaluating Inner Lists
1648 @cindex Inner list evaluation
1649 @cindex Evaluating inner lists
1651 If evaluation applies to a list that is inside another list, the outer
1652 list may use the value returned by the first evaluation as information
1653 when the outer list is evaluated. This explains why inner expressions
1654 are evaluated first: the values they return are used by the outer
1658 We can investigate this process by evaluating another addition example.
1659 Place your cursor after the following expression and type @kbd{C-x C-e}:
1666 The number 8 will appear in the echo area.
1668 What happens is that the Lisp interpreter first evaluates the inner
1669 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it
1670 evaluates the outer expression as if it were written @code{(+ 2 6)}, which
1671 returns the value 8. Since there are no more enclosing expressions to
1672 evaluate, the interpreter prints that value in the echo area.
1674 Now it is easy to understand the name of the command invoked by the
1675 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The
1676 letters @code{sexp} are an abbreviation for `symbolic expression', and
1677 @code{eval} is an abbreviation for `evaluate'. The command means
1678 `evaluate last symbolic expression'.
1680 As an experiment, you can try evaluating the expression by putting the
1681 cursor at the beginning of the next line immediately following the
1682 expression, or inside the expression.
1685 Here is another copy of the expression:
1692 If you place the cursor at the beginning of the blank line that
1693 immediately follows the expression and type @kbd{C-x C-e}, you will
1694 still get the value 8 printed in the echo area. Now try putting the
1695 cursor inside the expression. If you put it right after the next to
1696 last parenthesis (so it appears to sit on top of the last parenthesis),
1697 you will get a 6 printed in the echo area! This is because the command
1698 evaluates the expression @code{(+ 3 3)}.
1700 Now put the cursor immediately after a number. Type @kbd{C-x C-e} and
1701 you will get the number itself. In Lisp, if you evaluate a number, you
1702 get the number itself---this is how numbers differ from symbols. If you
1703 evaluate a list starting with a symbol like @code{+}, you will get a
1704 value returned that is the result of the computer carrying out the
1705 instructions in the function definition attached to that name. If a
1706 symbol by itself is evaluated, something different happens, as we will
1707 see in the next section.
1709 @node Variables, Arguments, Evaluation, List Processing
1710 @comment node-name, next, previous, up
1714 In Emacs Lisp, a symbol can have a value attached to it just as it can
1715 have a function definition attached to it. The two are different.
1716 The function definition is a set of instructions that a computer will
1717 obey. A value, on the other hand, is something, such as number or a
1718 name, that can vary (which is why such a symbol is called a variable).
1719 The value of a symbol can be any expression in Lisp, such as a symbol,
1720 number, list, or string. A symbol that has a value is often called a
1723 A symbol can have both a function definition and a value attached to
1724 it at the same time. Or it can have just one or the other.
1725 The two are separate. This is somewhat similar
1726 to the way the name Cambridge can refer to the city in Massachusetts
1727 and have some information attached to the name as well, such as
1728 ``great programming center''.
1731 (Incidentally, in Emacs Lisp, a symbol can have two
1732 other things attached to it, too: a property list and a documentation
1733 string; these are discussed later.)
1736 Another way to think about this is to imagine a symbol as being a chest
1737 of drawers. The function definition is put in one drawer, the value in
1738 another, and so on. What is put in the drawer holding the value can be
1739 changed without affecting the contents of the drawer holding the
1740 function definition, and vice-versa.
1743 * fill-column Example::
1744 * Void Function:: The error message for a symbol
1746 * Void Variable:: The error message for a symbol without a value.
1749 @node fill-column Example, Void Function, Variables, Variables
1751 @unnumberedsubsec @code{fill-column}, an Example Variable
1754 @findex fill-column, @r{an example variable}
1755 @cindex Example variable, @code{fill-column}
1756 @cindex Variable, example of, @code{fill-column}
1757 The variable @code{fill-column} illustrates a symbol with a value
1758 attached to it: in every GNU Emacs buffer, this symbol is set to some
1759 value, usually 72 or 70, but sometimes to some other value. To find the
1760 value of this symbol, evaluate it by itself. If you are reading this in
1761 Info inside of GNU Emacs, you can do this by putting the cursor after
1762 the symbol and typing @kbd{C-x C-e}:
1769 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo
1770 area. This is the value for which @code{fill-column} is set for me as I
1771 write this. It may be different for you in your Info buffer. Notice
1772 that the value returned as a variable is printed in exactly the same way
1773 as the value returned by a function carrying out its instructions. From
1774 the point of view of the Lisp interpreter, a value returned is a value
1775 returned. What kind of expression it came from ceases to matter once
1778 A symbol can have any value attached to it or, to use the jargon, we can
1779 @dfn{bind} the variable to a value: to a number, such as 72; to a
1780 string, @code{"such as this"}; to a list, such as @code{(spruce pine
1781 oak)}; we can even bind a variable to a function definition.
1783 A symbol can be bound to a value in several ways. @xref{set & setq, ,
1784 Setting the Value of a Variable}, for information about one way to do
1787 @node Void Function, Void Variable, fill-column Example, Variables
1788 @comment node-name, next, previous, up
1789 @subsection Error Message for a Symbol Without a Function
1790 @cindex Symbol without function error
1791 @cindex Error for symbol without function
1793 When we evaluated @code{fill-column} to find its value as a variable,
1794 we did not place parentheses around the word. This is because we did
1795 not intend to use it as a function name.
1797 If @code{fill-column} were the first or only element of a list, the
1798 Lisp interpreter would attempt to find the function definition
1799 attached to it. But @code{fill-column} has no function definition.
1800 Try evaluating this:
1808 In GNU Emacs version 21, you will create a @file{*Backtrace*} buffer
1813 ---------- Buffer: *Backtrace* ----------
1814 Debugger entered--Lisp error: (void-function fill-column)
1817 eval-last-sexp-1(nil)
1819 call-interactively(eval-last-sexp)
1820 ---------- Buffer: *Backtrace* ----------
1825 (Remember, to quit the debugger and make the debugger window go away,
1826 type @kbd{q} in the @file{*Backtrace*} buffer.)
1829 In GNU Emacs 20 and before, you will produce an error message that says:
1832 Symbol's function definition is void:@: fill-column
1836 (The message will go away away as soon as you move the cursor or type
1839 @node Void Variable, , Void Function, Variables
1840 @comment node-name, next, previous, up
1841 @subsection Error Message for a Symbol Without a Value
1842 @cindex Symbol without value error
1843 @cindex Error for symbol without value
1845 If you attempt to evaluate a symbol that does not have a value bound to
1846 it, you will receive an error message. You can see this by
1847 experimenting with our 2 plus 2 addition. In the following expression,
1848 put your cursor right after the @code{+}, before the first number 2,
1857 In GNU Emacs 21, you will create a @file{*Backtrace*} buffer that
1862 ---------- Buffer: *Backtrace* ----------
1863 Debugger entered--Lisp error: (void-variable +)
1865 eval-last-sexp-1(nil)
1867 call-interactively(eval-last-sexp)
1868 ---------- Buffer: *Backtrace* ----------
1873 (As with the other times we entered the debugger, you can quit by
1874 typing @kbd{q} in the @file{*Backtrace*} buffer.)
1876 This backtrace is different from the very first error message we saw,
1877 which said, @samp{Debugger entered--Lisp error: (void-function this)}.
1878 In this case, the function does not have a value as a variable; while
1879 in the other error message, the function (the word `this') did not
1882 In this experiment with the @code{+}, what we did was cause the Lisp
1883 interpreter to evaluate the @code{+} and look for the value of the
1884 variable instead of the function definition. We did this by placing the
1885 cursor right after the symbol rather than after the parenthesis of the
1886 enclosing list as we did before. As a consequence, the Lisp interpreter
1887 evaluated the preceding s-expression, which in this case was the
1890 Since @code{+} does not have a value bound to it, just the function
1891 definition, the error message reported that the symbol's value as a
1895 In GNU Emacs version 20 and before, your error message will say:
1898 Symbol's value as variable is void:@: +
1902 The meaning is the same as in GNU Emacs 21.
1904 @node Arguments, set & setq, Variables, List Processing
1905 @comment node-name, next, previous, up
1908 @cindex Passing information to functions
1910 To see how information is passed to functions, let's look again at
1911 our old standby, the addition of two plus two. In Lisp, this is written
1918 If you evaluate this expression, the number 4 will appear in your echo
1919 area. What the Lisp interpreter does is add the numbers that follow
1922 @cindex @samp{argument} defined
1923 The numbers added by @code{+} are called the @dfn{arguments} of the
1924 function @code{+}. These numbers are the information that is given to
1925 or @dfn{passed} to the function.
1927 The word `argument' comes from the way it is used in mathematics and
1928 does not refer to a disputation between two people; instead it refers to
1929 the information presented to the function, in this case, to the
1930 @code{+}. In Lisp, the arguments to a function are the atoms or lists
1931 that follow the function. The values returned by the evaluation of
1932 these atoms or lists are passed to the function. Different functions
1933 require different numbers of arguments; some functions require none at
1934 all.@footnote{It is curious to track the path by which the word `argument'
1935 came to have two different meanings, one in mathematics and the other in
1936 everyday English. According to the @cite{Oxford English Dictionary},
1937 the word derives from the Latin for @samp{to make clear, prove}; thus it
1938 came to mean, by one thread of derivation, `the evidence offered as
1939 proof', which is to say, `the information offered', which led to its
1940 meaning in Lisp. But in the other thread of derivation, it came to mean
1941 `to assert in a manner against which others may make counter
1942 assertions', which led to the meaning of the word as a disputation.
1943 (Note here that the English word has two different definitions attached
1944 to it at the same time. By contrast, in Emacs Lisp, a symbol cannot
1945 have two different function definitions at the same time.)}
1948 * Data types:: Types of data passed to a function.
1949 * Args as Variable or List:: An argument can be the value
1950 of a variable or list.
1951 * Variable Number of Arguments:: Some functions may take a
1952 variable number of arguments.
1953 * Wrong Type of Argument:: Passing an argument of the wrong type
1955 * message:: A useful function for sending messages.
1958 @node Data types, Args as Variable or List, Arguments, Arguments
1959 @comment node-name, next, previous, up
1960 @subsection Arguments' Data Types
1962 @cindex Types of data
1963 @cindex Arguments' data types
1965 The type of data that should be passed to a function depends on what
1966 kind of information it uses. The arguments to a function such as
1967 @code{+} must have values that are numbers, since @code{+} adds numbers.
1968 Other functions use different kinds of data for their arguments.
1972 For example, the @code{concat} function links together or unites two or
1973 more strings of text to produce a string. The arguments are strings.
1974 Concatenating the two character strings @code{abc}, @code{def} produces
1975 the single string @code{abcdef}. This can be seen by evaluating the
1979 (concat "abc" "def")
1983 The value produced by evaluating this expression is @code{"abcdef"}.
1985 A function such as @code{substring} uses both a string and numbers as
1986 arguments. The function returns a part of the string, a substring of
1987 the first argument. This function takes three arguments. Its first
1988 argument is the string of characters, the second and third arguments are
1989 numbers that indicate the beginning and end of the substring. The
1990 numbers are a count of the number of characters (including spaces and
1991 punctuations) from the beginning of the string.
1994 For example, if you evaluate the following:
1997 (substring "The quick brown fox jumped." 16 19)
2001 you will see @code{"fox"} appear in the echo area. The arguments are the
2002 string and the two numbers.
2004 Note that the string passed to @code{substring} is a single atom even
2005 though it is made up of several words separated by spaces. Lisp counts
2006 everything between the two quotation marks as part of the string,
2007 including the spaces. You can think of the @code{substring} function as
2008 a kind of `atom smasher' since it takes an otherwise indivisible atom
2009 and extracts a part. However, @code{substring} is only able to extract
2010 a substring from an argument that is a string, not from another type of
2011 atom such as a number or symbol.
2013 @node Args as Variable or List, Variable Number of Arguments, Data types, Arguments
2014 @comment node-name, next, previous, up
2015 @subsection An Argument as the Value of a Variable or List
2017 An argument can be a symbol that returns a value when it is evaluated.
2018 For example, when the symbol @code{fill-column} by itself is evaluated,
2019 it returns a number. This number can be used in an addition.
2022 Position the cursor after the following expression and type @kbd{C-x
2030 The value will be a number two more than what you get by evaluating
2031 @code{fill-column} alone. For me, this is 74, because the value of
2032 @code{fill-column} is 72.
2034 As we have just seen, an argument can be a symbol that returns a value
2035 when evaluated. In addition, an argument can be a list that returns a
2036 value when it is evaluated. For example, in the following expression,
2037 the arguments to the function @code{concat} are the strings
2038 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list
2039 @code{(number-to-string (+ 2 fill-column))}.
2041 @c For Emacs 21, need number-to-string
2043 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
2047 If you evaluate this expression---and if, as with my Emacs,
2048 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will
2049 appear in the echo area. (Note that you must put spaces after the
2050 word @samp{The} and before the word @samp{red} so they will appear in
2051 the final string. The function @code{number-to-string} converts the
2052 integer that the addition function returns to a string.
2053 @code{number-to-string} is also known as @code{int-to-string}.)
2055 @node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments
2056 @comment node-name, next, previous, up
2057 @subsection Variable Number of Arguments
2058 @cindex Variable number of arguments
2059 @cindex Arguments, variable number of
2061 Some functions, such as @code{concat}, @code{+} or @code{*}, take any
2062 number of arguments. (The @code{*} is the symbol for multiplication.)
2063 This can be seen by evaluating each of the following expressions in
2064 the usual way. What you will see in the echo area is printed in this
2065 text after @samp{@result{}}, which you may read as `evaluates to'.
2068 In the first set, the functions have no arguments:
2079 In this set, the functions have one argument each:
2090 In this set, the functions have three arguments each:
2094 (+ 3 4 5) @result{} 12
2096 (* 3 4 5) @result{} 60
2100 @node Wrong Type of Argument, message, Variable Number of Arguments, Arguments
2101 @comment node-name, next, previous, up
2102 @subsection Using the Wrong Type Object as an Argument
2103 @cindex Wrong type of argument
2104 @cindex Argument, wrong type of
2106 When a function is passed an argument of the wrong type, the Lisp
2107 interpreter produces an error message. For example, the @code{+}
2108 function expects the values of its arguments to be numbers. As an
2109 experiment we can pass it the quoted symbol @code{hello} instead of a
2110 number. Position the cursor after the following expression and type
2118 When you do this you will generate an error message. What has happened
2119 is that @code{+} has tried to add the 2 to the value returned by
2120 @code{'hello}, but the value returned by @code{'hello} is the symbol
2121 @code{hello}, not a number. Only numbers can be added. So @code{+}
2122 could not carry out its addition.
2125 In GNU Emacs version 21, you will create and enter a
2126 @file{*Backtrace*} buffer that says:
2131 ---------- Buffer: *Backtrace* ----------
2132 Debugger entered--Lisp error:
2133 (wrong-type-argument number-or-marker-p hello)
2135 eval((+ 2 (quote hello)))
2136 eval-last-sexp-1(nil)
2138 call-interactively(eval-last-sexp)
2139 ---------- Buffer: *Backtrace* ----------
2144 As usual, the error message tries to be helpful and makes sense after you
2145 learn how to read it.@footnote{@code{(quote hello)} is an expansion of
2146 the abbreviation @code{'hello}.}
2148 The first part of the error message is straightforward; it says
2149 @samp{wrong type argument}. Next comes the mysterious jargon word
2150 @w{@samp{number-or-marker-p}}. This word is trying to tell you what
2151 kind of argument the @code{+} expected.
2153 The symbol @code{number-or-marker-p} says that the Lisp interpreter is
2154 trying to determine whether the information presented it (the value of
2155 the argument) is a number or a marker (a special object representing a
2156 buffer position). What it does is test to see whether the @code{+} is
2157 being given numbers to add. It also tests to see whether the
2158 argument is something called a marker, which is a specific feature of
2159 Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers.
2160 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
2161 its position is kept as a marker. The mark can be considered a
2162 number---the number of characters the location is from the beginning
2163 of the buffer.) In Emacs Lisp, @code{+} can be used to add the
2164 numeric value of marker positions as numbers.
2166 The @samp{p} of @code{number-or-marker-p} is the embodiment of a
2167 practice started in the early days of Lisp programming. The @samp{p}
2168 stands for `predicate'. In the jargon used by the early Lisp
2169 researchers, a predicate refers to a function to determine whether some
2170 property is true or false. So the @samp{p} tells us that
2171 @code{number-or-marker-p} is the name of a function that determines
2172 whether it is true or false that the argument supplied is a number or
2173 a marker. Other Lisp symbols that end in @samp{p} include @code{zerop},
2174 a function that tests whether its argument has the value of zero, and
2175 @code{listp}, a function that tests whether its argument is a list.
2177 Finally, the last part of the error message is the symbol @code{hello}.
2178 This is the value of the argument that was passed to @code{+}. If the
2179 addition had been passed the correct type of object, the value passed
2180 would have been a number, such as 37, rather than a symbol like
2181 @code{hello}. But then you would not have got the error message.
2184 In GNU Emacs version 20 and before, the echo area displays an error
2188 Wrong type argument:@: number-or-marker-p, hello
2191 This says, in different words, the same as the top line of the
2192 @file{*Backtrace*} buffer.
2194 @node message, , Wrong Type of Argument, Arguments
2195 @comment node-name, next, previous, up
2196 @subsection The @code{message} Function
2199 Like @code{+}, the @code{message} function takes a variable number of
2200 arguments. It is used to send messages to the user and is so useful
2201 that we will describe it here.
2204 A message is printed in the echo area. For example, you can print a
2205 message in your echo area by evaluating the following list:
2208 (message "This message appears in the echo area!")
2211 The whole string between double quotation marks is a single argument
2212 and is printed @i{in toto}. (Note that in this example, the message
2213 itself will appear in the echo area within double quotes; that is
2214 because you see the value returned by the @code{message} function. In
2215 most uses of @code{message} in programs that you write, the text will
2216 be printed in the echo area as a side-effect, without the quotes.
2217 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in
2218 detail}, for an example of this.)
2220 However, if there is a @samp{%s} in the quoted string of characters, the
2221 @code{message} function does not print the @samp{%s} as such, but looks
2222 to the argument that follows the string. It evaluates the second
2223 argument and prints the value at the location in the string where the
2227 You can see this by positioning the cursor after the following
2228 expression and typing @kbd{C-x C-e}:
2231 (message "The name of this buffer is: %s." (buffer-name))
2235 In Info, @code{"The name of this buffer is: *info*."} will appear in the
2236 echo area. The function @code{buffer-name} returns the name of the
2237 buffer as a string, which the @code{message} function inserts in place
2240 To print a value as an integer, use @samp{%d} in the same way as
2241 @samp{%s}. For example, to print a message in the echo area that
2242 states the value of the @code{fill-column}, evaluate the following:
2245 (message "The value of fill-column is %d." fill-column)
2249 On my system, when I evaluate this list, @code{"The value of
2250 fill-column is 72."} appears in my echo area@footnote{Actually, you
2251 can use @code{%s} to print a number. It is non-specific. @code{%d}
2252 prints only the part of a number left of a decimal point, and not
2253 anything that is not a number.}.
2255 If there is more than one @samp{%s} in the quoted string, the value of
2256 the first argument following the quoted string is printed at the
2257 location of the first @samp{%s} and the value of the second argument is
2258 printed at the location of the second @samp{%s}, and so on.
2261 For example, if you evaluate the following,
2265 (message "There are %d %s in the office!"
2266 (- fill-column 14) "pink elephants")
2271 a rather whimsical message will appear in your echo area. On my system
2272 it says, @code{"There are 58 pink elephants in the office!"}.
2274 The expression @code{(- fill-column 14)} is evaluated and the resulting
2275 number is inserted in place of the @samp{%d}; and the string in double
2276 quotes, @code{"pink elephants"}, is treated as a single argument and
2277 inserted in place of the @samp{%s}. (That is to say, a string between
2278 double quotes evaluates to itself, like a number.)
2280 Finally, here is a somewhat complex example that not only illustrates
2281 the computation of a number, but also shows how you can use an
2282 expression within an expression to generate the text that is substituted
2287 (message "He saw %d %s"
2291 "The quick brown foxes jumped." 16 21)
2296 In this example, @code{message} has three arguments: the string,
2297 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and
2298 the expression beginning with the function @code{concat}. The value
2299 resulting from the evaluation of @code{(- fill-column 32)} is inserted
2300 in place of the @samp{%d}; and the value returned by the expression
2301 beginning with @code{concat} is inserted in place of the @samp{%s}.
2303 When I evaluate the expression, the message @code{"He saw 38 red
2304 foxes leaping."} appears in my echo area.
2306 @node set & setq, Summary, Arguments, List Processing
2307 @comment node-name, next, previous, up
2308 @section Setting the Value of a Variable
2309 @cindex Variable, setting value
2310 @cindex Setting value of variable
2312 @cindex @samp{bind} defined
2313 There are several ways by which a variable can be given a value. One of
2314 the ways is to use either the function @code{set} or the function
2315 @code{setq}. Another way is to use @code{let} (@pxref{let}). (The
2316 jargon for this process is to @dfn{bind} a variable to a value.)
2318 The following sections not only describe how @code{set} and @code{setq}
2319 work but also illustrate how arguments are passed.
2322 * Using set:: Setting values.
2323 * Using setq:: Setting a quoted value.
2324 * Counting:: Using @code{setq} to count.
2327 @node Using set, Using setq, set & setq, set & setq
2328 @comment node-name, next, previous, up
2329 @subsection Using @code{set}
2332 To set the value of the symbol @code{flowers} to the list @code{'(rose
2333 violet daisy buttercup)}, evaluate the following expression by
2334 positioning the cursor after the expression and typing @kbd{C-x C-e}.
2337 (set 'flowers '(rose violet daisy buttercup))
2341 The list @code{(rose violet daisy buttercup)} will appear in the echo
2342 area. This is what is @emph{returned} by the @code{set} function. As a
2343 side effect, the symbol @code{flowers} is bound to the list ; that is,
2344 the symbol @code{flowers}, which can be viewed as a variable, is given
2345 the list as its value. (This process, by the way, illustrates how a
2346 side effect to the Lisp interpreter, setting the value, can be the
2347 primary effect that we humans are interested in. This is because every
2348 Lisp function must return a value if it does not get an error, but it
2349 will only have a side effect if it is designed to have one.)
2351 After evaluating the @code{set} expression, you can evaluate the symbol
2352 @code{flowers} and it will return the value you just set. Here is the
2353 symbol. Place your cursor after it and type @kbd{C-x C-e}.
2360 When you evaluate @code{flowers}, the list
2361 @code{(rose violet daisy buttercup)} appears in the echo area.
2363 Incidentally, if you evaluate @code{'flowers}, the variable with a quote
2364 in front of it, what you will see in the echo area is the symbol itself,
2365 @code{flowers}. Here is the quoted symbol, so you can try this:
2371 Note also, that when you use @code{set}, you need to quote both
2372 arguments to @code{set}, unless you want them evaluated. Since we do
2373 not want either argument evaluated, neither the variable
2374 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
2375 are quoted. (When you use @code{set} without quoting its first
2376 argument, the first argument is evaluated before anything else is
2377 done. If you did this and @code{flowers} did not have a value
2378 already, you would get an error message that the @samp{Symbol's value
2379 as variable is void}; on the other hand, if @code{flowers} did return
2380 a value after it was evaluated, the @code{set} would attempt to set
2381 the value that was returned. There are situations where this is the
2382 right thing for the function to do; but such situations are rare.)
2384 @node Using setq, Counting, Using set, set & setq
2385 @comment node-name, next, previous, up
2386 @subsection Using @code{setq}
2389 As a practical matter, you almost always quote the first argument to
2390 @code{set}. The combination of @code{set} and a quoted first argument
2391 is so common that it has its own name: the special form @code{setq}.
2392 This special form is just like @code{set} except that the first argument
2393 is quoted automatically, so you don't need to type the quote mark
2394 yourself. Also, as an added convenience, @code{setq} permits you to set
2395 several different variables to different values, all in one expression.
2397 To set the value of the variable @code{carnivores} to the list
2398 @code{'(lion tiger leopard)} using @code{setq}, the following expression
2402 (setq carnivores '(lion tiger leopard))
2406 This is exactly the same as using @code{set} except the first argument
2407 is automatically quoted by @code{setq}. (The @samp{q} in @code{setq}
2408 means @code{quote}.)
2411 With @code{set}, the expression would look like this:
2414 (set 'carnivores '(lion tiger leopard))
2417 Also, @code{setq} can be used to assign different values to
2418 different variables. The first argument is bound to the value
2419 of the second argument, the third argument is bound to the value of the
2420 fourth argument, and so on. For example, you could use the following to
2421 assign a list of trees to the symbol @code{trees} and a list of herbivores
2422 to the symbol @code{herbivores}:
2426 (setq trees '(pine fir oak maple)
2427 herbivores '(gazelle antelope zebra))
2432 (The expression could just as well have been on one line, but it might
2433 not have fit on a page; and humans find it easier to read nicely
2436 Although I have been using the term `assign', there is another way of
2437 thinking about the workings of @code{set} and @code{setq}; and that is to
2438 say that @code{set} and @code{setq} make the symbol @emph{point} to the
2439 list. This latter way of thinking is very common and in forthcoming
2440 chapters we shall come upon at least one symbol that has `pointer' as
2441 part of its name. The name is chosen because the symbol has a value,
2442 specifically a list, attached to it; or, expressed another way,
2443 the symbol is set to ``point'' to the list.
2445 @node Counting, , Using setq, set & setq
2446 @comment node-name, next, previous, up
2447 @subsection Counting
2450 Here is an example that shows how to use @code{setq} in a counter. You
2451 might use this to count how many times a part of your program repeats
2452 itself. First set a variable to zero; then add one to the number each
2453 time the program repeats itself. To do this, you need a variable that
2454 serves as a counter, and two expressions: an initial @code{setq}
2455 expression that sets the counter variable to zero; and a second
2456 @code{setq} expression that increments the counter each time it is
2461 (setq counter 0) ; @r{Let's call this the initializer.}
2463 (setq counter (+ counter 1)) ; @r{This is the incrementer.}
2465 counter ; @r{This is the counter.}
2470 (The text following the @samp{;} are comments. @xref{Change a
2471 defun, , Change a Function Definition}.)
2473 If you evaluate the first of these expressions, the initializer,
2474 @code{(setq counter 0)}, and then evaluate the third expression,
2475 @code{counter}, the number @code{0} will appear in the echo area. If
2476 you then evaluate the second expression, the incrementer, @code{(setq
2477 counter (+ counter 1))}, the counter will get the value 1. So if you
2478 again evaluate @code{counter}, the number @code{1} will appear in the
2479 echo area. Each time you evaluate the second expression, the value of
2480 the counter will be incremented.
2482 When you evaluate the incrementer, @code{(setq counter (+ counter 1))},
2483 the Lisp interpreter first evaluates the innermost list; this is the
2484 addition. In order to evaluate this list, it must evaluate the variable
2485 @code{counter} and the number @code{1}. When it evaluates the variable
2486 @code{counter}, it receives its current value. It passes this value and
2487 the number @code{1} to the @code{+} which adds them together. The sum
2488 is then returned as the value of the inner list and passed to the
2489 @code{setq} which sets the variable @code{counter} to this new value.
2490 Thus, the value of the variable, @code{counter}, is changed.
2492 @node Summary, Error Message Exercises, set & setq, List Processing
2493 @comment node-name, next, previous, up
2496 Learning Lisp is like climbing a hill in which the first part is the
2497 steepest. You have now climbed the most difficult part; what remains
2498 becomes easier as you progress onwards.
2506 Lisp programs are made up of expressions, which are lists or single atoms.
2509 Lists are made up of zero or more atoms or inner lists, separated by whitespace and
2510 surrounded by parentheses. A list can be empty.
2513 Atoms are multi-character symbols, like @code{forward-paragraph}, single
2514 character symbols like @code{+}, strings of characters between double
2515 quotation marks, or numbers.
2518 A number evaluates to itself.
2521 A string between double quotes also evaluates to itself.
2524 When you evaluate a symbol by itself, its value is returned.
2527 When you evaluate a list, the Lisp interpreter looks at the first symbol
2528 in the list and then at the function definition bound to that symbol.
2529 Then the instructions in the function definition are carried out.
2532 A single-quote, @code{'}, tells the Lisp interpreter that it should
2533 return the following expression as written, and not evaluate it as it
2534 would if the quote were not there.
2537 Arguments are the information passed to a function. The arguments to a
2538 function are computed by evaluating the rest of the elements of the list
2539 of which the function is the first element.
2542 A function always returns a value when it is evaluated (unless it gets
2543 an error); in addition, it may also carry out some action called a
2544 ``side effect''. In many cases, a function's primary purpose is to
2545 create a side effect.
2548 @node Error Message Exercises, , Summary, List Processing
2549 @comment node-name, next, previous, up
2552 A few simple exercises:
2556 Generate an error message by evaluating an appropriate symbol that is
2557 not within parentheses.
2560 Generate an error message by evaluating an appropriate symbol that is
2561 between parentheses.
2564 Create a counter that increments by two rather than one.
2567 Write an expression that prints a message in the echo area when
2571 @node Practicing Evaluation, Writing Defuns, List Processing, Top
2572 @comment node-name, next, previous, up
2573 @chapter Practicing Evaluation
2574 @cindex Practicing evaluation
2575 @cindex Evaluation practice
2577 Before learning how to write a function definition in Emacs Lisp, it is
2578 useful to spend a little time evaluating various expressions that have
2579 already been written. These expressions will be lists with the
2580 functions as their first (and often only) element. Since some of the
2581 functions associated with buffers are both simple and interesting, we
2582 will start with those. In this section, we will evaluate a few of
2583 these. In another section, we will study the code of several other
2584 buffer-related functions, to see how they were written.
2587 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
2589 * Buffer Names:: Buffers and files are different.
2590 * Getting Buffers:: Getting a buffer itself, not merely its name.
2591 * Switching Buffers:: How to change to another buffer.
2592 * Buffer Size & Locations:: Where point is located and the size of
2594 * Evaluation Exercise::
2597 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
2599 @unnumberedsec How to Evaluate
2602 @i{Whenever you give an editing command} to Emacs Lisp, such as the
2603 command to move the cursor or to scroll the screen, @i{you are evaluating
2604 an expression,} the first element of which is a function. @i{This is
2607 @cindex @samp{interactive function} defined
2608 @cindex @samp{command} defined
2609 When you type keys, you cause the Lisp interpreter to evaluate an
2610 expression and that is how you get your results. Even typing plain text
2611 involves evaluating an Emacs Lisp function, in this case, one that uses
2612 @code{self-insert-command}, which simply inserts the character you
2613 typed. The functions you evaluate by typing keystrokes are called
2614 @dfn{interactive} functions, or @dfn{commands}; how you make a function
2615 interactive will be illustrated in the chapter on how to write function
2616 definitions. @xref{Interactive, , Making a Function Interactive}.
2618 In addition to typing keyboard commands, we have seen a second way to
2619 evaluate an expression: by positioning the cursor after a list and
2620 typing @kbd{C-x C-e}. This is what we will do in the rest of this
2621 section. There are other ways to evaluate an expression as well; these
2622 will be described as we come to them.
2624 Besides being used for practicing evaluation, the functions shown in the
2625 next few sections are important in their own right. A study of these
2626 functions makes clear the distinction between buffers and files, how to
2627 switch to a buffer, and how to determine a location within it.
2629 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation
2630 @comment node-name, next, previous, up
2631 @section Buffer Names
2633 @findex buffer-file-name
2635 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
2636 the difference between a file and a buffer. When you evaluate the
2637 following expression, @code{(buffer-name)}, the name of the buffer
2638 appears in the echo area. When you evaluate @code{(buffer-file-name)},
2639 the name of the file to which the buffer refers appears in the echo
2640 area. Usually, the name returned by @code{(buffer-name)} is the same as
2641 the name of the file to which it refers, and the name returned by
2642 @code{(buffer-file-name)} is the full path-name of the file.
2644 A file and a buffer are two different entities. A file is information
2645 recorded permanently in the computer (unless you delete it). A buffer,
2646 on the other hand, is information inside of Emacs that will vanish at
2647 the end of the editing session (or when you kill the buffer). Usually,
2648 a buffer contains information that you have copied from a file; we say
2649 the buffer is @dfn{visiting} that file. This copy is what you work on
2650 and modify. Changes to the buffer do not change the file, until you
2651 save the buffer. When you save the buffer, the buffer is copied to the file
2652 and is thus saved permanently.
2655 If you are reading this in Info inside of GNU Emacs, you can evaluate
2656 each of the following expressions by positioning the cursor after it and
2657 typing @kbd{C-x C-e}.
2668 When I do this, @file{"introduction.texinfo"} is the value returned by
2669 evaluating @code{(buffer-name)}, and
2670 @file{"/gnu/work/intro/introduction.texinfo"} is the value returned by
2671 evaluating @code{(buffer-file-name)}. The former is the name of the
2672 buffer and the latter is the name of the file. (In the expressions, the
2673 parentheses tell the Lisp interpreter to treat @code{buffer-name} and
2674 @code{buffer-file-name} as functions; without the parentheses, the
2675 interpreter would attempt to evaluate the symbols as variables.
2678 In spite of the distinction between files and buffers, you will often
2679 find that people refer to a file when they mean a buffer and vice-versa.
2680 Indeed, most people say, ``I am editing a file,'' rather than saying,
2681 ``I am editing a buffer which I will soon save to a file.'' It is
2682 almost always clear from context what people mean. When dealing with
2683 computer programs, however, it is important to keep the distinction in mind,
2684 since the computer is not as smart as a person.
2686 @cindex Buffer, history of word
2687 The word `buffer', by the way, comes from the meaning of the word as a
2688 cushion that deadens the force of a collision. In early computers, a
2689 buffer cushioned the interaction between files and the computer's
2690 central processing unit. The drums or tapes that held a file and the
2691 central processing unit were pieces of equipment that were very
2692 different from each other, working at their own speeds, in spurts. The
2693 buffer made it possible for them to work together effectively.
2694 Eventually, the buffer grew from being an intermediary, a temporary
2695 holding place, to being the place where work is done. This
2696 transformation is rather like that of a small seaport that grew into a
2697 great city: once it was merely the place where cargo was warehoused
2698 temporarily before being loaded onto ships; then it became a business
2699 and cultural center in its own right.
2701 Not all buffers are associated with files. For example, when you start
2702 an Emacs session by typing the command @code{emacs} alone, without
2703 naming any files, Emacs will start with the @file{*scratch*} buffer on
2704 the screen. This buffer is not visiting any file. Similarly, a
2705 @file{*Help*} buffer is not associated with any file.
2707 @cindex @code{nil}, history of word
2708 If you switch to the @file{*scratch*} buffer, type @code{(buffer-name)},
2709 position the cursor after it, and type @kbd{C-x C-e} to evaluate the
2710 expression, the name @code{"*scratch*"} is returned and will appear in
2711 the echo area. @code{"*scratch*"} is the name of the buffer. However,
2712 if you type @code{(buffer-file-name)} in the @file{*scratch*} buffer and
2713 evaluate that, @code{nil} will appear in the echo area. @code{nil} is
2714 from the Latin word for `nothing'; in this case, it means that the
2715 @file{*scratch*} buffer is not associated with any file. (In Lisp,
2716 @code{nil} is also used to mean `false' and is a synonym for the empty
2719 Incidentally, if you are in the @file{*scratch*} buffer and want the
2720 value returned by an expression to appear in the @file{*scratch*}
2721 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
2722 instead of @kbd{C-x C-e}. This causes the value returned to appear
2723 after the expression. The buffer will look like this:
2726 (buffer-name)"*scratch*"
2730 You cannot do this in Info since Info is read-only and it will not allow
2731 you to change the contents of the buffer. But you can do this in any
2732 buffer you can edit; and when you write code or documentation (such as
2733 this book), this feature is very useful.
2735 @node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation
2736 @comment node-name, next, previous, up
2737 @section Getting Buffers
2738 @findex current-buffer
2739 @findex other-buffer
2740 @cindex Getting a buffer
2742 The @code{buffer-name} function returns the @emph{name} of the buffer;
2743 to get the buffer @emph{itself}, a different function is needed: the
2744 @code{current-buffer} function. If you use this function in code, what
2745 you get is the buffer itself.
2747 A name and the object or entity to which the name refers are different
2748 from each other. You are not your name. You are a person to whom
2749 others refer by name. If you ask to speak to George and someone hands you
2750 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
2751 @samp{g}, and @samp{e} written on it, you might be amused, but you would
2752 not be satisfied. You do not want to speak to the name, but to the
2753 person to whom the name refers. A buffer is similar: the name of the
2754 scratch buffer is @file{*scratch*}, but the name is not the buffer. To
2755 get a buffer itself, you need to use a function such as
2756 @code{current-buffer}.
2758 However, there is a slight complication: if you evaluate
2759 @code{current-buffer} in an expression on its own, as we will do here,
2760 what you see is a printed representation of the name of the buffer
2761 without the contents of the buffer. Emacs works this way for two
2762 reasons: the buffer may be thousands of lines long---too long to be
2763 conveniently displayed; and, another buffer may have the same contents
2764 but a different name, and it is important to distinguish between them.
2767 Here is an expression containing the function:
2774 If you evaluate the expression in the usual way, @file{#<buffer *info*>}
2775 appears in the echo area. The special format indicates that the
2776 buffer itself is being returned, rather than just its name.
2778 Incidentally, while you can type a number or symbol into a program, you
2779 cannot do that with the printed representation of a buffer: the only way
2780 to get a buffer itself is with a function such as @code{current-buffer}.
2782 A related function is @code{other-buffer}. This returns the most
2783 recently selected buffer other than the one you are in currently. If
2784 you have recently switched back and forth from the @file{*scratch*}
2785 buffer, @code{other-buffer} will return that buffer.
2788 You can see this by evaluating the expression:
2795 You should see @file{#<buffer *scratch*>} appear in the echo area, or
2796 the name of whatever other buffer you switched back from most
2797 recently@footnote{Actually, by default, if the buffer from which you
2798 just switched is visible to you in another window, @code{other-buffer}
2799 will choose the most recent buffer that you cannot see; this is a
2800 subtlety that I often forget.}.
2802 @node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation
2803 @comment node-name, next, previous, up
2804 @section Switching Buffers
2805 @findex switch-to-buffer
2807 @cindex Switching to a buffer
2809 The @code{other-buffer} function actually provides a buffer when it is
2810 used as an argument to a function that requires one. We can see this
2811 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
2814 But first, a brief introduction to the @code{switch-to-buffer}
2815 function. When you switched back and forth from Info to the
2816 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
2817 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
2818 rather, to save typing, you probably typed just part of the name, such
2819 as @code{*sc}, and then pressed your @kbd{TAB} key to cause it to
2820 expand to the full name; and then typed your @kbd{RET} key.} when
2821 prompted in the minibuffer for the name of the buffer to which you
2822 wanted to switch. The keystrokes, @kbd{C-x b}, cause the Lisp
2823 interpreter to evaluate the interactive function
2824 @code{switch-to-buffer}. As we said before, this is how Emacs works:
2825 different keystrokes call or run different functions. For example,
2826 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
2827 @code{forward-sentence}, and so on.
2829 By writing @code{switch-to-buffer} in an expression, and giving it a
2830 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
2834 Here is the Lisp expression:
2837 (switch-to-buffer (other-buffer))
2841 The symbol @code{switch-to-buffer} is the first element of the list,
2842 so the Lisp interpreter will treat it as a function and carry out the
2843 instructions that are attached to it. But before doing that, the
2844 interpreter will note that @code{other-buffer} is inside parentheses
2845 and work on that symbol first. @code{other-buffer} is the first (and
2846 in this case, the only) element of this list, so the Lisp interpreter
2847 calls or runs the function. It returns another buffer. Next, the
2848 interpreter runs @code{switch-to-buffer}, passing to it, as an
2849 argument, the other buffer, which is what Emacs will switch to. If
2850 you are reading this in Info, try this now. Evaluate the expression.
2851 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
2852 expression will move you to your most recent other buffer that you
2853 cannot see. If you really want to go to your most recently selected
2854 buffer, even if you can still see it, you need to evaluate the
2855 following more complex expression:
2858 (switch-to-buffer (other-buffer (current-buffer) t))
2862 In this case, the first argument to @code{other-buffer} tells it which
2863 buffer to skip---the current one---and the second argument tells
2864 @code{other-buffer} it is OK to switch to a visible buffer.
2865 In regular use, @code{switch-to-buffer} takes you to an invisible
2866 window since you would most likely use @kbd{C-x o} (@code{other-window})
2867 to go to another visible buffer.}
2869 In the programming examples in later sections of this document, you will
2870 see the function @code{set-buffer} more often than
2871 @code{switch-to-buffer}. This is because of a difference between
2872 computer programs and humans: humans have eyes and expect to see the
2873 buffer on which they are working on their computer terminals. This is
2874 so obvious, it almost goes without saying. However, programs do not
2875 have eyes. When a computer program works on a buffer, that buffer does
2876 not need to be visible on the screen.
2878 @code{switch-to-buffer} is designed for humans and does two different
2879 things: it switches the buffer to which Emacs' attention is directed; and
2880 it switches the buffer displayed in the window to the new buffer.
2881 @code{set-buffer}, on the other hand, does only one thing: it switches
2882 the attention of the computer program to a different buffer. The buffer
2883 on the screen remains unchanged (of course, normally nothing happens
2884 there until the command finishes running).
2886 @cindex @samp{call} defined
2887 Also, we have just introduced another jargon term, the word @dfn{call}.
2888 When you evaluate a list in which the first symbol is a function, you
2889 are calling that function. The use of the term comes from the notion of
2890 the function as an entity that can do something for you if you `call'
2891 it---just as a plumber is an entity who can fix a leak if you call him
2894 @node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation
2895 @comment node-name, next, previous, up
2896 @section Buffer Size and the Location of Point
2897 @cindex Size of buffer
2899 @cindex Point location
2900 @cindex Location of point
2902 Finally, let's look at several rather simple functions,
2903 @code{buffer-size}, @code{point}, @code{point-min}, and
2904 @code{point-max}. These give information about the size of a buffer and
2905 the location of point within it.
2907 The function @code{buffer-size} tells you the size of the current
2908 buffer; that is, the function returns a count of the number of
2909 characters in the buffer.
2916 You can evaluate this in the usual way, by positioning the
2917 cursor after the expression and typing @kbd{C-x C-e}.
2919 @cindex @samp{point} defined
2920 In Emacs, the current position of the cursor is called @dfn{point}.
2921 The expression @code{(point)} returns a number that tells you where the
2922 cursor is located as a count of the number of characters from the
2923 beginning of the buffer up to point.
2926 You can see the character count for point in this buffer by evaluating
2927 the following expression in the usual way:
2934 As I write this, the value of @code{point} is 65724. The @code{point}
2935 function is frequently used in some of the examples later in this
2939 The value of point depends, of course, on its location within the
2940 buffer. If you evaluate point in this spot, the number will be larger:
2947 For me, the value of point in this location is 66043, which means that
2948 there are 319 characters (including spaces) between the two expressions.
2950 @cindex @samp{narrowing} defined
2951 The function @code{point-min} is somewhat similar to @code{point}, but
2952 it returns the value of the minimum permissible value of point in the
2953 current buffer. This is the number 1 unless @dfn{narrowing} is in
2954 effect. (Narrowing is a mechanism whereby you can restrict yourself,
2955 or a program, to operations on just a part of a buffer.
2956 @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the
2957 function @code{point-max} returns the value of the maximum permissible
2958 value of point in the current buffer.
2960 @node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation
2963 Find a file with which you are working and move towards its middle.
2964 Find its buffer name, file name, length, and your position in the file.
2966 @node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top
2967 @comment node-name, next, previous, up
2968 @chapter How To Write Function Definitions
2969 @cindex Definition writing
2970 @cindex Function definition writing
2971 @cindex Writing a function definition
2973 When the Lisp interpreter evaluates a list, it looks to see whether the
2974 first symbol on the list has a function definition attached to it; or,
2975 put another way, whether the symbol points to a function definition. If
2976 it does, the computer carries out the instructions in the definition. A
2977 symbol that has a function definition is called, simply, a function
2978 (although, properly speaking, the definition is the function and the
2979 symbol refers to it.)
2982 * Primitive Functions::
2983 * defun:: The @code{defun} special form.
2984 * Install:: Install a function definition.
2985 * Interactive:: Making a function interactive.
2986 * Interactive Options:: Different options for @code{interactive}.
2987 * Permanent Installation:: Installing code permanently.
2988 * let:: Creating and initializing local variables.
2990 * else:: If--then--else expressions.
2991 * Truth & Falsehood:: What Lisp considers false and true.
2992 * save-excursion:: Keeping track of point, mark, and buffer.
2997 @node Primitive Functions, defun, Writing Defuns, Writing Defuns
2999 @unnumberedsec An Aside about Primitive Functions
3001 @cindex Primitive functions
3002 @cindex Functions, primitive
3004 @cindex C language primitives
3005 @cindex Primitives written in C
3006 All functions are defined in terms of other functions, except for a few
3007 @dfn{primitive} functions that are written in the C programming
3008 language. When you write functions' definitions, you will write them in
3009 Emacs Lisp and use other functions as your building blocks. Some of the
3010 functions you will use will themselves be written in Emacs Lisp (perhaps
3011 by you) and some will be primitives written in C. The primitive
3012 functions are used exactly like those written in Emacs Lisp and behave
3013 like them. They are written in C so we can easily run GNU Emacs on any
3014 computer that has sufficient power and can run C.
3016 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
3017 distinguish between the use of functions written in C and the use of
3018 functions written in Emacs Lisp. The difference is irrelevant. I
3019 mention the distinction only because it is interesting to know. Indeed,
3020 unless you investigate, you won't know whether an already-written
3021 function is written in Emacs Lisp or C.
3023 @node defun, Install, Primitive Functions, Writing Defuns
3024 @comment node-name, next, previous, up
3025 @section The @code{defun} Special Form
3027 @cindex Special form of @code{defun}
3029 @cindex @samp{function definition} defined
3030 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
3031 it that tells the computer what to do when the function is called.
3032 This code is called the @dfn{function definition} and is created by
3033 evaluating a Lisp expression that starts with the symbol @code{defun}
3034 (which is an abbreviation for @emph{define function}). Because
3035 @code{defun} does not evaluate its arguments in the usual way, it is
3036 called a @dfn{special form}.
3038 In subsequent sections, we will look at function definitions from the
3039 Emacs source code, such as @code{mark-whole-buffer}. In this section,
3040 we will describe a simple function definition so you can see how it
3041 looks. This function definition uses arithmetic because it makes for a
3042 simple example. Some people dislike examples using arithmetic; however,
3043 if you are such a person, do not despair. Hardly any of the code we
3044 will study in the remainder of this introduction involves arithmetic or
3045 mathematics. The examples mostly involve text in one way or another.
3047 A function definition has up to five parts following the word
3052 The name of the symbol to which the function definition should be
3056 A list of the arguments that will be passed to the function. If no
3057 arguments will be passed to the function, this is an empty list,
3061 Documentation describing the function. (Technically optional, but
3062 strongly recommended.)
3065 Optionally, an expression to make the function interactive so you can
3066 use it by typing @kbd{M-x} and then the name of the function; or by
3067 typing an appropriate key or keychord.
3069 @cindex @samp{body} defined
3071 The code that instructs the computer what to do: the @dfn{body} of the
3072 function definition.
3075 It is helpful to think of the five parts of a function definition as
3076 being organized in a template, with slots for each part:
3080 (defun @var{function-name} (@var{arguments}@dots{})
3081 "@var{optional-documentation}@dots{}"
3082 (interactive @var{argument-passing-info}) ; @r{optional}
3087 As an example, here is the code for a function that multiplies its
3088 argument by 7. (This example is not interactive. @xref{Interactive,
3089 , Making a Function Interactive}, for that information.)
3093 (defun multiply-by-seven (number)
3094 "Multiply NUMBER by seven."
3099 This definition begins with a parenthesis and the symbol @code{defun},
3100 followed by the name of the function.
3102 @cindex @samp{argument list} defined
3103 The name of the function is followed by a list that contains the
3104 arguments that will be passed to the function. This list is called
3105 the @dfn{argument list}. In this example, the list has only one
3106 element, the symbol, @code{number}. When the function is used, the
3107 symbol will be bound to the value that is used as the argument to the
3110 Instead of choosing the word @code{number} for the name of the argument,
3111 I could have picked any other name. For example, I could have chosen
3112 the word @code{multiplicand}. I picked the word `number' because it
3113 tells what kind of value is intended for this slot; but I could just as
3114 well have chosen the word `multiplicand' to indicate the role that the
3115 value placed in this slot will play in the workings of the function. I
3116 could have called it @code{foogle}, but that would have been a bad
3117 choice because it would not tell humans what it means. The choice of
3118 name is up to the programmer and should be chosen to make the meaning of
3121 Indeed, you can choose any name you wish for a symbol in an argument
3122 list, even the name of a symbol used in some other function: the name
3123 you use in an argument list is private to that particular definition.
3124 In that definition, the name refers to a different entity than any use
3125 of the same name outside the function definition. Suppose you have a
3126 nick-name `Shorty' in your family; when your family members refer to
3127 `Shorty', they mean you. But outside your family, in a movie, for
3128 example, the name `Shorty' refers to someone else. Because a name in an
3129 argument list is private to the function definition, you can change the
3130 value of such a symbol inside the body of a function without changing
3131 its value outside the function. The effect is similar to that produced
3132 by a @code{let} expression. (@xref{let, , @code{let}}.)
3135 Note also that we discuss the word `number' in two different ways: as a
3136 symbol that appears in the code, and as the name of something that will
3137 be replaced by a something else during the evaluation of the function.
3138 In the first case, @code{number} is a symbol, not a number; it happens
3139 that within the function, it is a variable who value is the number in
3140 question, but our primary interest in it is as a symbol. On the other
3141 hand, when we are talking about the function, our interest is that we
3142 will substitute a number for the word @var{number}. To keep this
3143 distinction clear, we use different typography for the two
3144 circumstances. When we talk about this function, or about how it works,
3145 we refer to this number by writing @var{number}. In the function
3146 itself, we refer to it by writing @code{number}.
3149 The argument list is followed by the documentation string that
3150 describes the function. This is what you see when you type
3151 @w{@kbd{C-h f}} and the name of a function. Incidentally, when you
3152 write a documentation string like this, you should make the first line
3153 a complete sentence since some commands, such as @code{apropos}, print
3154 only the first line of a multi-line documentation string. Also, you
3155 should not indent the second line of a documentation string, if you
3156 have one, because that looks odd when you use @kbd{C-h f}
3157 (@code{describe-function}). The documentation string is optional, but
3158 it is so useful, it should be included in almost every function you
3161 @findex * @r{(multiplication)}
3162 The third line of the example consists of the body of the function
3163 definition. (Most functions' definitions, of course, are longer than
3164 this.) In this function, the body is the list, @code{(* 7 number)}, which
3165 says to multiply the value of @var{number} by 7. (In Emacs Lisp,
3166 @code{*} is the function for multiplication, just as @code{+} is the
3167 function for addition.)
3169 When you use the @code{multiply-by-seven} function, the argument
3170 @code{number} evaluates to the actual number you want used. Here is an
3171 example that shows how @code{multiply-by-seven} is used; but don't try
3172 to evaluate this yet!
3175 (multiply-by-seven 3)
3179 The symbol @code{number}, specified in the function definition in the
3180 next section, is given or ``bound to'' the value 3 in the actual use of
3181 the function. Note that although @code{number} was inside parentheses
3182 in the function definition, the argument passed to the
3183 @code{multiply-by-seven} function is not in parentheses. The
3184 parentheses are written in the function definition so the computer can
3185 figure out where the argument list ends and the rest of the function
3188 If you evaluate this example, you are likely to get an error message.
3189 (Go ahead, try it!) This is because we have written the function
3190 definition, but not yet told the computer about the definition---we have
3191 not yet installed (or `loaded') the function definition in Emacs.
3192 Installing a function is the process that tells the Lisp interpreter the
3193 definition of the function. Installation is described in the next
3196 @node Install, Interactive, defun, Writing Defuns
3197 @comment node-name, next, previous, up
3198 @section Install a Function Definition
3199 @cindex Install a Function Definition
3200 @cindex Definition installation
3201 @cindex Function definition installation
3203 If you are reading this inside of Info in Emacs, you can try out the
3204 @code{multiply-by-seven} function by first evaluating the function
3205 definition and then evaluating @code{(multiply-by-seven 3)}. A copy of
3206 the function definition follows. Place the cursor after the last
3207 parenthesis of the function definition and type @kbd{C-x C-e}. When you
3208 do this, @code{multiply-by-seven} will appear in the echo area. (What
3209 this means is that when a function definition is evaluated, the value it
3210 returns is the name of the defined function.) At the same time, this
3211 action installs the function definition.
3215 (defun multiply-by-seven (number)
3216 "Multiply NUMBER by seven."
3222 By evaluating this @code{defun}, you have just installed
3223 @code{multiply-by-seven} in Emacs. The function is now just as much a
3224 part of Emacs as @code{forward-word} or any other editing function you
3225 use. (@code{multiply-by-seven} will stay installed until you quit
3226 Emacs. To reload code automatically whenever you start Emacs, see
3227 @ref{Permanent Installation, , Installing Code Permanently}.)
3231 * Effect of installation::
3232 * Change a defun:: How to change a function definition.
3235 @node Effect of installation, Change a defun, Install, Install
3237 @unnumberedsubsec The effect of installation
3241 You can see the effect of installing @code{multiply-by-seven} by
3242 evaluating the following sample. Place the cursor after the following
3243 expression and type @kbd{C-x C-e}. The number 21 will appear in the
3247 (multiply-by-seven 3)
3250 If you wish, you can read the documentation for the function by typing
3251 @kbd{C-h f} (@code{describe-function}) and then the name of the
3252 function, @code{multiply-by-seven}. When you do this, a
3253 @file{*Help*} window will appear on your screen that says:
3258 Multiply NUMBER by seven.
3263 (To return to a single window on your screen, type @kbd{C-x 1}.)
3265 @node Change a defun, , Effect of installation, Install
3266 @comment node-name, next, previous, up
3267 @subsection Change a Function Definition
3268 @cindex Changing a function definition
3269 @cindex Function definition, how to change
3270 @cindex Definition, how to change
3272 If you want to change the code in @code{multiply-by-seven}, just rewrite
3273 it. To install the new version in place of the old one, evaluate the
3274 function definition again. This is how you modify code in Emacs. It is
3277 As an example, you can change the @code{multiply-by-seven} function to
3278 add the number to itself seven times instead of multiplying the number
3279 by seven. It produces the same answer, but by a different path. At
3280 the same time, we will add a comment to the code; a comment is text
3281 that the Lisp interpreter ignores, but that a human reader may find
3282 useful or enlightening. The comment is that this is the ``second
3287 (defun multiply-by-seven (number) ; @r{Second version.}
3288 "Multiply NUMBER by seven."
3289 (+ number number number number number number number))
3293 @cindex Comments in Lisp code
3294 The comment follows a semicolon, @samp{;}. In Lisp, everything on a
3295 line that follows a semicolon is a comment. The end of the line is the
3296 end of the comment. To stretch a comment over two or more lines, begin
3297 each line with a semicolon.
3299 @xref{Beginning a .emacs File, , Beginning a @file{.emacs}
3300 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
3301 Reference Manual}, for more about comments.
3303 You can install this version of the @code{multiply-by-seven} function by
3304 evaluating it in the same way you evaluated the first function: place
3305 the cursor after the last parenthesis and type @kbd{C-x C-e}.
3307 In summary, this is how you write code in Emacs Lisp: you write a
3308 function; install it; test it; and then make fixes or enhancements and
3311 @node Interactive, Interactive Options, Install, Writing Defuns
3312 @comment node-name, next, previous, up
3313 @section Make a Function Interactive
3314 @cindex Interactive functions
3317 You make a function interactive by placing a list that begins with
3318 the special form @code{interactive} immediately after the
3319 documentation. A user can invoke an interactive function by typing
3320 @kbd{M-x} and then the name of the function; or by typing the keys to
3321 which it is bound, for example, by typing @kbd{C-n} for
3322 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
3324 Interestingly, when you call an interactive function interactively,
3325 the value returned is not automatically displayed in the echo area.
3326 This is because you often call an interactive function for its side
3327 effects, such as moving forward by a word or line, and not for the
3328 value returned. If the returned value were displayed in the echo area
3329 each time you typed a key, it would be very distracting.
3332 * Interactive multiply-by-seven:: An overview.
3333 * multiply-by-seven in detail:: The interactive version.
3336 @node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
3338 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
3341 Both the use of the special form @code{interactive} and one way to
3342 display a value in the echo area can be illustrated by creating an
3343 interactive version of @code{multiply-by-seven}.
3350 (defun multiply-by-seven (number) ; @r{Interactive version.}
3351 "Multiply NUMBER by seven."
3353 (message "The result is %d" (* 7 number)))
3358 You can install this code by placing your cursor after it and typing
3359 @kbd{C-x C-e}. The name of the function will appear in your echo area.
3360 Then, you can use this code by typing @kbd{C-u} and a number and then
3361 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase
3362 @samp{The result is @dots{}} followed by the product will appear in the
3365 Speaking more generally, you invoke a function like this in either of two
3370 By typing a prefix argument that contains the number to be passed, and
3371 then typing @kbd{M-x} and the name of the function, as with
3372 @kbd{C-u 3 M-x forward-sentence}; or,
3375 By typing whatever key or keychord the function is bound to, as with
3380 Both the examples just mentioned work identically to move point forward
3381 three sentences. (Since @code{multiply-by-seven} is not bound to a key,
3382 it could not be used as an example of key binding.)
3384 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
3387 A prefix argument is passed to an interactive function by typing the
3388 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
3389 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
3390 type @kbd{C-u} without a number, it defaults to 4).
3392 @node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive
3393 @comment node-name, next, previous, up
3394 @subsection An Interactive @code{multiply-by-seven}
3396 Let's look at the use of the special form @code{interactive} and then at
3397 the function @code{message} in the interactive version of
3398 @code{multiply-by-seven}. You will recall that the function definition
3403 (defun multiply-by-seven (number) ; @r{Interactive version.}
3404 "Multiply NUMBER by seven."
3406 (message "The result is %d" (* 7 number)))
3410 In this function, the expression, @code{(interactive "p")}, is a list of
3411 two elements. The @code{"p"} tells Emacs to pass the prefix argument to
3412 the function and use its value for the argument of the function.
3415 The argument will be a number. This means that the symbol
3416 @code{number} will be bound to a number in the line:
3419 (message "The result is %d" (* 7 number))
3424 For example, if your prefix argument is 5, the Lisp interpreter will
3425 evaluate the line as if it were:
3428 (message "The result is %d" (* 7 5))
3432 (If you are reading this in GNU Emacs, you can evaluate this expression
3433 yourself.) First, the interpreter will evaluate the inner list, which
3434 is @code{(* 7 5)}. This returns a value of 35. Next, it
3435 will evaluate the outer list, passing the values of the second and
3436 subsequent elements of the list to the function @code{message}.
3438 As we have seen, @code{message} is an Emacs Lisp function especially
3439 designed for sending a one line message to a user. (@xref{message, , The
3440 @code{message} function}.)
3441 In summary, the @code{message} function prints its first argument in the
3442 echo area as is, except for occurrences of @samp{%d}, @samp{%s}, or
3443 @samp{%c}. When it sees one of these control sequences, the function
3444 looks to the second and subsequent arguments and prints the value of the
3445 argument in the location in the string where the control sequence is
3448 In the interactive @code{multiply-by-seven} function, the control string
3449 is @samp{%d}, which requires a number, and the value returned by
3450 evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35
3451 is printed in place of the @samp{%d} and the message is @samp{The result
3454 (Note that when you call the function @code{multiply-by-seven}, the
3455 message is printed without quotes, but when you call @code{message}, the
3456 text is printed in double quotes. This is because the value returned by
3457 @code{message} is what appears in the echo area when you evaluate an
3458 expression whose first element is @code{message}; but when embedded in a
3459 function, @code{message} prints the text as a side effect without
3462 @node Interactive Options, Permanent Installation, Interactive, Writing Defuns
3463 @comment node-name, next, previous, up
3464 @section Different Options for @code{interactive}
3465 @cindex Options for @code{interactive}
3466 @cindex Interactive options
3468 In the example, @code{multiply-by-seven} used @code{"p"} as the
3469 argument to @code{interactive}. This argument told Emacs to interpret
3470 your typing either @kbd{C-u} followed by a number or @key{META}
3471 followed by a number as a command to pass that number to the function
3472 as its argument. Emacs has more than twenty characters predefined for
3473 use with @code{interactive}. In almost every case, one of these
3474 options will enable you to pass the right information interactively to
3475 a function. (@xref{Interactive Codes, , Code Characters for
3476 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
3479 For example, the character @samp{r} causes Emacs to pass the beginning
3480 and end of the region (the current values of point and mark) to the
3481 function as two separate arguments. It is used as follows:
3487 On the other hand, a @samp{B} tells Emacs to ask for the name of a
3488 buffer that will be passed to the function. When it sees a @samp{B},
3489 Emacs will ask for the name by prompting the user in the minibuffer,
3490 using a string that follows the @samp{B}, as in @code{"BAppend to
3491 buffer:@: "}. Not only will Emacs prompt for the name, but Emacs will
3492 complete the name if you type enough of it and press @key{TAB}.
3494 A function with two or more arguments can have information passed to
3495 each argument by adding parts to the string that follows
3496 @code{interactive}. When you do this, the information is passed to
3497 each argument in the same order it is specified in the
3498 @code{interactive} list. In the string, each part is separated from
3499 the next part by a @samp{\n}, which is a newline. For example, you
3500 could follow @code{"BAppend to buffer:@: "} with a @samp{\n} and an
3501 @samp{r}. This would cause Emacs to pass the values of point and mark
3502 to the function as well as prompt you for the buffer---three arguments
3505 In this case, the function definition would look like the following,
3506 where @code{buffer}, @code{start}, and @code{end} are the symbols to
3507 which @code{interactive} binds the buffer and the current values of the
3508 beginning and ending of the region:
3512 (defun @var{name-of-function} (buffer start end)
3513 "@var{documentation}@dots{}"
3514 (interactive "BAppend to buffer:@: \nr")
3515 @var{body-of-function}@dots{})
3520 (The space after the colon in the prompt makes it look better when you
3521 are prompted. The @code{append-to-buffer} function looks exactly like
3522 this. @xref{append-to-buffer, , The Definition of
3523 @code{append-to-buffer}}.)
3525 If a function does not have arguments, then @code{interactive} does not
3526 require any. Such a function contains the simple expression
3527 @code{(interactive)}. The @code{mark-whole-buffer} function is like
3530 Alternatively, if the special letter-codes are not right for your
3531 application, you can pass your own arguments to @code{interactive} as
3532 a list. @xref{Using Interactive, , Using @code{Interactive}, elisp, The
3533 GNU Emacs Lisp Reference Manual}, for more information about this advanced
3536 @node Permanent Installation, let, Interactive Options, Writing Defuns
3537 @comment node-name, next, previous, up
3538 @section Install Code Permanently
3539 @cindex Install code permanently
3540 @cindex Permanent code installation
3541 @cindex Code installation
3543 When you install a function definition by evaluating it, it will stay
3544 installed until you quit Emacs. The next time you start a new session
3545 of Emacs, the function will not be installed unless you evaluate the
3546 function definition again.
3548 At some point, you may want to have code installed automatically
3549 whenever you start a new session of Emacs. There are several ways of
3554 If you have code that is just for yourself, you can put the code for the
3555 function definition in your @file{.emacs} initialization file. When you
3556 start Emacs, your @file{.emacs} file is automatically evaluated and all
3557 the function definitions within it are installed.
3558 @xref{Emacs Initialization, , Your @file{.emacs} File}.
3561 Alternatively, you can put the function definitions that you want
3562 installed in one or more files of their own and use the @code{load}
3563 function to cause Emacs to evaluate and thereby install each of the
3564 functions in the files.
3565 @xref{Loading Files, , Loading Files}.
3568 On the other hand, if you have code that your whole site will use, it
3569 is usual to put it in a file called @file{site-init.el} that is loaded
3570 when Emacs is built. This makes the code available to everyone who
3571 uses your machine. (See the @file{INSTALL} file that is part of the
3572 Emacs distribution.)
3575 Finally, if you have code that everyone who uses Emacs may want, you
3576 can post it on a computer network or send a copy to the Free Software
3577 Foundation. (When you do this, please license the code and its
3578 documentation under a license that permits other people to run, copy,
3579 study, modify, and redistribute the code and which protects you from
3580 having your work taken from you.) If you send a copy of your code to
3581 the Free Software Foundation, and properly protect yourself and
3582 others, it may be included in the next release of Emacs. In large
3583 part, this is how Emacs has grown over the past years, by donations.
3585 @node let, if, Permanent Installation, Writing Defuns
3586 @comment node-name, next, previous, up
3590 The @code{let} expression is a special form in Lisp that you will need
3591 to use in most function definitions.
3593 @code{let} is used to attach or bind a symbol to a value in such a way
3594 that the Lisp interpreter will not confuse the variable with a
3595 variable of the same name that is not part of the function.
3597 To understand why the @code{let} special form is necessary, consider
3598 the situation in which you own a home that you generally refer to as
3599 `the house', as in the sentence, ``The house needs painting.'' If you
3600 are visiting a friend and your host refers to `the house', he is
3601 likely to be referring to @emph{his} house, not yours, that is, to a
3604 If your friend is referring to his house and you think he is referring
3605 to your house, you may be in for some confusion. The same thing could
3606 happen in Lisp if a variable that is used inside of one function has
3607 the same name as a variable that is used inside of another function,
3608 and the two are not intended to refer to the same value. The
3609 @code{let} special form prevents this kind of confusion.
3612 * Prevent confusion::
3613 * Parts of let Expression::
3614 * Sample let Expression::
3615 * Uninitialized let Variables::
3618 @node Prevent confusion, Parts of let Expression, let, let
3620 @unnumberedsubsec @code{let} Prevents Confusion
3623 @cindex @samp{local variable} defined
3624 The @code{let} special form prevents confusion. @code{let} creates a
3625 name for a @dfn{local variable} that overshadows any use of the same
3626 name outside the @code{let} expression. This is like understanding
3627 that whenever your host refers to `the house', he means his house, not
3628 yours. (Symbols used in argument lists work the same way.
3629 @xref{defun, , The @code{defun} Special Form}.)
3631 Local variables created by a @code{let} expression retain their value
3632 @emph{only} within the @code{let} expression itself (and within
3633 expressions called within the @code{let} expression); the local
3634 variables have no effect outside the @code{let} expression.
3636 Another way to think about @code{let} is that it is like a @code{setq}
3637 that is temporary and local. The values set by @code{let} are
3638 automatically undone when the @code{let} is finished. The setting
3639 only affects expressions that are inside the bounds of the @code{let}
3640 expression. In computer science jargon, we would say ``the binding of
3641 a symbol is visible only in functions called in the @code{let} form;
3642 in Emacs Lisp, scoping is dynamic, not lexical.''
3644 @code{let} can create more than one variable at once. Also,
3645 @code{let} gives each variable it creates an initial value, either a
3646 value specified by you, or @code{nil}. (In the jargon, this is called
3647 `binding the variable to the value'.) After @code{let} has created
3648 and bound the variables, it executes the code in the body of the
3649 @code{let}, and returns the value of the last expression in the body,
3650 as the value of the whole @code{let} expression. (`Execute' is a jargon
3651 term that means to evaluate a list; it comes from the use of the word
3652 meaning `to give practical effect to' (@cite{Oxford English
3653 Dictionary}). Since you evaluate an expression to perform an action,
3654 `execute' has evolved as a synonym to `evaluate'.)
3656 @node Parts of let Expression, Sample let Expression, Prevent confusion, let
3657 @comment node-name, next, previous, up
3658 @subsection The Parts of a @code{let} Expression
3659 @cindex @code{let} expression, parts of
3660 @cindex Parts of @code{let} expression
3662 @cindex @samp{varlist} defined
3663 A @code{let} expression is a list of three parts. The first part is
3664 the symbol @code{let}. The second part is a list, called a
3665 @dfn{varlist}, each element of which is either a symbol by itself or a
3666 two-element list, the first element of which is a symbol. The third
3667 part of the @code{let} expression is the body of the @code{let}. The
3668 body usually consists of one or more lists.
3671 A template for a @code{let} expression looks like this:
3674 (let @var{varlist} @var{body}@dots{})
3678 The symbols in the varlist are the variables that are given initial
3679 values by the @code{let} special form. Symbols by themselves are given
3680 the initial value of @code{nil}; and each symbol that is the first
3681 element of a two-element list is bound to the value that is returned
3682 when the Lisp interpreter evaluates the second element.
3684 Thus, a varlist might look like this: @code{(thread (needles 3))}. In
3685 this case, in a @code{let} expression, Emacs binds the symbol
3686 @code{thread} to an initial value of @code{nil}, and binds the symbol
3687 @code{needles} to an initial value of 3.
3689 When you write a @code{let} expression, what you do is put the
3690 appropriate expressions in the slots of the @code{let} expression
3693 If the varlist is composed of two-element lists, as is often the case,
3694 the template for the @code{let} expression looks like this:
3698 (let ((@var{variable} @var{value})
3699 (@var{variable} @var{value})
3705 @node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let
3706 @comment node-name, next, previous, up
3707 @subsection Sample @code{let} Expression
3708 @cindex Sample @code{let} expression
3709 @cindex @code{let} expression sample
3711 The following expression creates and gives initial values
3712 to the two variables @code{zebra} and @code{tiger}. The body of the
3713 @code{let} expression is a list which calls the @code{message} function.
3717 (let ((zebra 'stripes)
3719 (message "One kind of animal has %s and another is %s."
3724 Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}.
3726 The two variables are @code{zebra} and @code{tiger}. Each variable is
3727 the first element of a two-element list and each value is the second
3728 element of its two-element list. In the varlist, Emacs binds the
3729 variable @code{zebra} to the value @code{stripes}, and binds the
3730 variable @code{tiger} to the value @code{fierce}. In this example,
3731 both values are symbols preceded by a quote. The values could just as
3732 well have been another list or a string. The body of the @code{let}
3733 follows after the list holding the variables. In this example, the body
3734 is a list that uses the @code{message} function to print a string in
3738 You may evaluate the example in the usual fashion, by placing the
3739 cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do
3740 this, the following will appear in the echo area:
3743 "One kind of animal has stripes and another is fierce."
3746 As we have seen before, the @code{message} function prints its first
3747 argument, except for @samp{%s}. In this example, the value of the variable
3748 @code{zebra} is printed at the location of the first @samp{%s} and the
3749 value of the variable @code{tiger} is printed at the location of the
3752 @node Uninitialized let Variables, , Sample let Expression, let
3753 @comment node-name, next, previous, up
3754 @subsection Uninitialized Variables in a @code{let} Statement
3755 @cindex Uninitialized @code{let} variables
3756 @cindex @code{let} variables uninitialized
3758 If you do not bind the variables in a @code{let} statement to specific
3759 initial values, they will automatically be bound to an initial value of
3760 @code{nil}, as in the following expression:
3769 "Here are %d variables with %s, %s, and %s value."
3770 birch pine fir oak))
3775 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
3778 If you evaluate this expression in the usual way, the following will
3779 appear in your echo area:
3782 "Here are 3 variables with nil, nil, and some value."
3786 In this example, Emacs binds the symbol @code{birch} to the number 3,
3787 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
3788 the symbol @code{oak} to the value @code{some}.
3790 Note that in the first part of the @code{let}, the variables @code{pine}
3791 and @code{fir} stand alone as atoms that are not surrounded by
3792 parentheses; this is because they are being bound to @code{nil}, the
3793 empty list. But @code{oak} is bound to @code{some} and so is a part of
3794 the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the
3795 number 3 and so is in a list with that number. (Since a number
3796 evaluates to itself, the number does not need to be quoted. Also, the
3797 number is printed in the message using a @samp{%d} rather than a
3798 @samp{%s}.) The four variables as a group are put into a list to
3799 delimit them from the body of the @code{let}.
3801 @node if, else, let, Writing Defuns
3802 @comment node-name, next, previous, up
3803 @section The @code{if} Special Form
3805 @cindex Conditional with @code{if}
3807 A third special form, in addition to @code{defun} and @code{let}, is the
3808 conditional @code{if}. This form is used to instruct the computer to
3809 make decisions. You can write function definitions without using
3810 @code{if}, but it is used often enough, and is important enough, to be
3811 included here. It is used, for example, in the code for the
3812 function @code{beginning-of-buffer}.
3814 The basic idea behind an @code{if}, is that ``@emph{if} a test is true,
3815 @emph{then} an expression is evaluated.'' If the test is not true, the
3816 expression is not evaluated. For example, you might make a decision
3817 such as, ``if it is warm and sunny, then go to the beach!''
3820 * if in more detail::
3821 * type-of-animal in detail:: An example of an @code{if} expression.
3824 @node if in more detail, type-of-animal in detail, if, if
3826 @unnumberedsubsec @code{if} in more detail
3829 @cindex @samp{if-part} defined
3830 @cindex @samp{then-part} defined
3831 An @code{if} expression written in Lisp does not use the word `then';
3832 the test and the action are the second and third elements of the list
3833 whose first element is @code{if}. Nonetheless, the test part of an
3834 @code{if} expression is often called the @dfn{if-part} and the second
3835 argument is often called the @dfn{then-part}.
3837 Also, when an @code{if} expression is written, the true-or-false-test
3838 is usually written on the same line as the symbol @code{if}, but the
3839 action to carry out if the test is true, the ``then-part'', is written
3840 on the second and subsequent lines. This makes the @code{if}
3841 expression easier to read.
3845 (if @var{true-or-false-test}
3846 @var{action-to-carry-out-if-test-is-true})
3851 The true-or-false-test will be an expression that
3852 is evaluated by the Lisp interpreter.
3854 Here is an example that you can evaluate in the usual manner. The test
3855 is whether the number 5 is greater than the number 4. Since it is, the
3856 message @samp{5 is greater than 4!} will be printed.
3860 (if (> 5 4) ; @r{if-part}
3861 (message "5 is greater than 4!")) ; @r{then-part}
3866 (The function @code{>} tests whether its first argument is greater than
3867 its second argument and returns true if it is.)
3868 @findex > (greater than)
3870 Of course, in actual use, the test in an @code{if} expression will not
3871 be fixed for all time as it is by the expression @code{(> 5 4)}.
3872 Instead, at least one of the variables used in the test will be bound to
3873 a value that is not known ahead of time. (If the value were known ahead
3874 of time, we would not need to run the test!)
3876 For example, the value may be bound to an argument of a function
3877 definition. In the following function definition, the character of the
3878 animal is a value that is passed to the function. If the value bound to
3879 @code{characteristic} is @code{fierce}, then the message, @samp{It's a
3880 tiger!} will be printed; otherwise, @code{nil} will be returned.
3884 (defun type-of-animal (characteristic)
3885 "Print message in echo area depending on CHARACTERISTIC.
3886 If the CHARACTERISTIC is the symbol `fierce',
3887 then warn of a tiger."
3888 (if (equal characteristic 'fierce)
3889 (message "It's a tiger!")))
3895 If you are reading this inside of GNU Emacs, you can evaluate the
3896 function definition in the usual way to install it in Emacs, and then you
3897 can evaluate the following two expressions to see the results:
3901 (type-of-animal 'fierce)
3903 (type-of-animal 'zebra)
3908 @c Following sentences rewritten to prevent overfull hbox.
3910 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
3911 following message printed in the echo area: @code{"It's a tiger!"}; and
3912 when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil}
3913 printed in the echo area.
3915 @node type-of-animal in detail, , if in more detail, if
3916 @comment node-name, next, previous, up
3917 @subsection The @code{type-of-animal} Function in Detail
3919 Let's look at the @code{type-of-animal} function in detail.
3921 The function definition for @code{type-of-animal} was written by filling
3922 the slots of two templates, one for a function definition as a whole, and
3923 a second for an @code{if} expression.
3926 The template for every function that is not interactive is:
3930 (defun @var{name-of-function} (@var{argument-list})
3931 "@var{documentation}@dots{}"
3937 The parts of the function that match this template look like this:
3941 (defun type-of-animal (characteristic)
3942 "Print message in echo area depending on CHARACTERISTIC.
3943 If the CHARACTERISTIC is the symbol `fierce',
3944 then warn of a tiger."
3945 @var{body: the} @code{if} @var{expression})
3949 The name of function is @code{type-of-animal}; it is passed the value
3950 of one argument. The argument list is followed by a multi-line
3951 documentation string. The documentation string is included in the
3952 example because it is a good habit to write documentation string for
3953 every function definition. The body of the function definition
3954 consists of the @code{if} expression.
3957 The template for an @code{if} expression looks like this:
3961 (if @var{true-or-false-test}
3962 @var{action-to-carry-out-if-the-test-returns-true})
3967 In the @code{type-of-animal} function, the code for the @code{if}
3972 (if (equal characteristic 'fierce)
3973 (message "It's a tiger!")))
3978 Here, the true-or-false-test is the expression:
3981 (equal characteristic 'fierce)
3985 In Lisp, @code{equal} is a function that determines whether its first
3986 argument is equal to its second argument. The second argument is the
3987 quoted symbol @code{'fierce} and the first argument is the value of the
3988 symbol @code{characteristic}---in other words, the argument passed to
3991 In the first exercise of @code{type-of-animal}, the argument
3992 @code{fierce} is passed to @code{type-of-animal}. Since @code{fierce}
3993 is equal to @code{fierce}, the expression, @code{(equal characteristic
3994 'fierce)}, returns a value of true. When this happens, the @code{if}
3995 evaluates the second argument or then-part of the @code{if}:
3996 @code{(message "It's tiger!")}.
3998 On the other hand, in the second exercise of @code{type-of-animal}, the
3999 argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra}
4000 is not equal to @code{fierce}, so the then-part is not evaluated and
4001 @code{nil} is returned by the @code{if} expression.
4003 @node else, Truth & Falsehood, if, Writing Defuns
4004 @comment node-name, next, previous, up
4005 @section If--then--else Expressions
4008 An @code{if} expression may have an optional third argument, called
4009 the @dfn{else-part}, for the case when the true-or-false-test returns
4010 false. When this happens, the second argument or then-part of the
4011 overall @code{if} expression is @emph{not} evaluated, but the third or
4012 else-part @emph{is} evaluated. You might think of this as the cloudy
4013 day alternative for the decision ``if it is warm and sunny, then go to
4014 the beach, else read a book!''.
4016 The word ``else'' is not written in the Lisp code; the else-part of an
4017 @code{if} expression comes after the then-part. In the written Lisp, the
4018 else-part is usually written to start on a line of its own and is
4019 indented less than the then-part:
4023 (if @var{true-or-false-test}
4024 @var{action-to-carry-out-if-the-test-returns-true}
4025 @var{action-to-carry-out-if-the-test-returns-false})
4029 For example, the following @code{if} expression prints the message @samp{4
4030 is not greater than 5!} when you evaluate it in the usual way:
4034 (if (> 4 5) ; @r{if-part}
4035 (message "5 is greater than 4!") ; @r{then-part}
4036 (message "4 is not greater than 5!")) ; @r{else-part}
4041 Note that the different levels of indentation make it easy to
4042 distinguish the then-part from the else-part. (GNU Emacs has several
4043 commands that automatically indent @code{if} expressions correctly.
4044 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
4046 We can extend the @code{type-of-animal} function to include an
4047 else-part by simply incorporating an additional part to the @code{if}
4051 You can see the consequences of doing this if you evaluate the following
4052 version of the @code{type-of-animal} function definition to install it
4053 and then evaluate the two subsequent expressions to pass different
4054 arguments to the function.
4058 (defun type-of-animal (characteristic) ; @r{Second version.}
4059 "Print message in echo area depending on CHARACTERISTIC.
4060 If the CHARACTERISTIC is the symbol `fierce',
4061 then warn of a tiger;
4062 else say it's not fierce."
4063 (if (equal characteristic 'fierce)
4064 (message "It's a tiger!")
4065 (message "It's not fierce!")))
4072 (type-of-animal 'fierce)
4074 (type-of-animal 'zebra)
4079 @c Following sentence rewritten to prevent overfull hbox.
4081 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
4082 following message printed in the echo area: @code{"It's a tiger!"}; but
4083 when you evaluate @code{(type-of-animal 'zebra)}, you will see
4084 @code{"It's not fierce!"}.
4086 (Of course, if the @var{characteristic} were @code{ferocious}, the
4087 message @code{"It's not fierce!"} would be printed; and it would be
4088 misleading! When you write code, you need to take into account the
4089 possibility that some such argument will be tested by the @code{if} and
4090 write your program accordingly.)
4092 @node Truth & Falsehood, save-excursion, else, Writing Defuns
4093 @comment node-name, next, previous, up
4094 @section Truth and Falsehood in Emacs Lisp
4095 @cindex Truth and falsehood in Emacs Lisp
4096 @cindex Falsehood and truth in Emacs Lisp
4099 There is an important aspect to the truth test in an @code{if}
4100 expression. So far, we have spoken of `true' and `false' as values of
4101 predicates as if they were new kinds of Emacs Lisp objects. In fact,
4102 `false' is just our old friend @code{nil}. Anything else---anything
4105 The expression that tests for truth is interpreted as @dfn{true}
4106 if the result of evaluating it is a value that is not @code{nil}. In
4107 other words, the result of the test is considered true if the value
4108 returned is a number such as 47, a string such as @code{"hello"}, or a
4109 symbol (other than @code{nil}) such as @code{flowers}, or a list, or
4113 * nil explained:: @code{nil} has two meanings.
4116 @node nil explained, , Truth & Falsehood, Truth & Falsehood
4118 @unnumberedsubsec An explanation of @code{nil}
4121 Before illustrating a test for truth, we need an explanation of @code{nil}.
4123 In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the
4124 empty list. Second, it means false and is the value returned when a
4125 true-or-false-test tests false. @code{nil} can be written as an empty
4126 list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is
4127 concerned, @code{()} and @code{nil} are the same. Humans, however, tend
4128 to use @code{nil} for false and @code{()} for the empty list.
4130 In Emacs Lisp, any value that is not @code{nil}---is not the empty
4131 list---is considered true. This means that if an evaluation returns
4132 something that is not an empty list, an @code{if} expression will test
4133 true. For example, if a number is put in the slot for the test, it
4134 will be evaluated and will return itself, since that is what numbers
4135 do when evaluated. In this conditional, the @code{if} expression will
4136 test true. The expression tests false only when @code{nil}, an empty
4137 list, is returned by evaluating the expression.
4139 You can see this by evaluating the two expressions in the following examples.
4141 In the first example, the number 4 is evaluated as the test in the
4142 @code{if} expression and returns itself; consequently, the then-part
4143 of the expression is evaluated and returned: @samp{true} appears in
4144 the echo area. In the second example, the @code{nil} indicates false;
4145 consequently, the else-part of the expression is evaluated and
4146 returned: @samp{false} appears in the echo area.
4163 Incidentally, if some other useful value is not available for a test that
4164 returns true, then the Lisp interpreter will return the symbol @code{t}
4165 for true. For example, the expression @code{(> 5 4)} returns @code{t}
4166 when evaluated, as you can see by evaluating it in the usual way:
4174 On the other hand, this function returns @code{nil} if the test is false.
4180 @node save-excursion, Review, Truth & Falsehood, Writing Defuns
4181 @comment node-name, next, previous, up
4182 @section @code{save-excursion}
4183 @findex save-excursion
4184 @cindex Region, what it is
4185 @cindex Preserving point, mark, and buffer
4186 @cindex Point, mark, buffer preservation
4190 The @code{save-excursion} function is the fourth and final special form
4191 that we will discuss in this chapter.
4193 In Emacs Lisp programs used for editing, the @code{save-excursion}
4194 function is very common. It saves the location of point and mark,
4195 executes the body of the function, and then restores point and mark to
4196 their previous positions if their locations were changed. Its primary
4197 purpose is to keep the user from being surprised and disturbed by
4198 unexpected movement of point or mark.
4201 * Point and mark:: A review of various locations.
4202 * Template for save-excursion::
4205 @node Point and mark, Template for save-excursion, save-excursion, save-excursion
4207 @unnumberedsubsec Point and Mark
4210 Before discussing @code{save-excursion}, however, it may be useful
4211 first to review what point and mark are in GNU Emacs. @dfn{Point} is
4212 the current location of the cursor. Wherever the cursor
4213 is, that is point. More precisely, on terminals where the cursor
4214 appears to be on top of a character, point is immediately before the
4215 character. In Emacs Lisp, point is an integer. The first character in
4216 a buffer is number one, the second is number two, and so on. The
4217 function @code{point} returns the current position of the cursor as a
4218 number. Each buffer has its own value for point.
4220 The @dfn{mark} is another position in the buffer; its value can be set
4221 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If
4222 a mark has been set, you can use the command @kbd{C-x C-x}
4223 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
4224 and set the mark to be the previous position of point. In addition, if
4225 you set another mark, the position of the previous mark is saved in the
4226 mark ring. Many mark positions can be saved this way. You can jump the
4227 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
4230 The part of the buffer between point and mark is called @dfn{the
4231 region}. Numerous commands work on the region, including
4232 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
4233 @code{print-region}.
4235 The @code{save-excursion} special form saves the locations of point and
4236 mark and restores those positions after the code within the body of the
4237 special form is evaluated by the Lisp interpreter. Thus, if point were
4238 in the beginning of a piece of text and some code moved point to the end
4239 of the buffer, the @code{save-excursion} would put point back to where
4240 it was before, after the expressions in the body of the function were
4243 In Emacs, a function frequently moves point as part of its internal
4244 workings even though a user would not expect this. For example,
4245 @code{count-lines-region} moves point. To prevent the user from being
4246 bothered by jumps that are both unexpected and (from the user's point of
4247 view) unnecessary, @code{save-excursion} is often used to keep point and
4248 mark in the location expected by the user. The use of
4249 @code{save-excursion} is good housekeeping.
4251 To make sure the house stays clean, @code{save-excursion} restores the
4252 values of point and mark even if something goes wrong in the code inside
4253 of it (or, to be more precise and to use the proper jargon, ``in case of
4254 abnormal exit''). This feature is very helpful.
4256 In addition to recording the values of point and mark,
4257 @code{save-excursion} keeps track of the current buffer, and restores
4258 it, too. This means you can write code that will change the buffer and
4259 have @code{save-excursion} switch you back to the original buffer. This
4260 is how @code{save-excursion} is used in @code{append-to-buffer}.
4261 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
4263 @node Template for save-excursion, , Point and mark, save-excursion
4264 @comment node-name, next, previous, up
4265 @subsection Template for a @code{save-excursion} Expression
4268 The template for code using @code{save-excursion} is simple:
4278 The body of the function is one or more expressions that will be
4279 evaluated in sequence by the Lisp interpreter. If there is more than
4280 one expression in the body, the value of the last one will be returned
4281 as the value of the @code{save-excursion} function. The other
4282 expressions in the body are evaluated only for their side effects; and
4283 @code{save-excursion} itself is used only for its side effect (which
4284 is restoring the positions of point and mark).
4287 In more detail, the template for a @code{save-excursion} expression
4293 @var{first-expression-in-body}
4294 @var{second-expression-in-body}
4295 @var{third-expression-in-body}
4297 @var{last-expression-in-body})
4302 An expression, of course, may be a symbol on its own or a list.
4304 In Emacs Lisp code, a @code{save-excursion} expression often occurs
4305 within the body of a @code{let} expression. It looks like this:
4315 @node Review, defun Exercises, save-excursion, Writing Defuns
4316 @comment node-name, next, previous, up
4319 In the last few chapters we have introduced a fair number of functions
4320 and special forms. Here they are described in brief, along with a few
4321 similar functions that have not been mentioned yet.
4324 @item eval-last-sexp
4325 Evaluate the last symbolic expression before the current location of
4326 point. The value is printed in the echo area unless the function is
4327 invoked with an argument; in that case, the output is printed in the
4328 current buffer. This command is normally bound to @kbd{C-x C-e}.
4331 Define function. This special form has up to five parts: the name,
4332 a template for the arguments that will be passed to the function,
4333 documentation, an optional interactive declaration, and the body of the
4341 (defun back-to-indentation ()
4342 "Move point to first visible character on line."
4344 (beginning-of-line 1)
4345 (skip-chars-forward " \t"))
4350 Declare to the interpreter that the function can be used
4351 interactively. This special form may be followed by a string with one
4352 or more parts that pass the information to the arguments of the
4353 function, in sequence. These parts may also tell the interpreter to
4354 prompt for information. Parts of the string are separated by
4355 newlines, @samp{\n}.
4358 Common code characters are:
4362 The name of an existing buffer.
4365 The name of an existing file.
4368 The numeric prefix argument. (Note that this `p' is lower case.)
4371 Point and the mark, as two numeric arguments, smallest first. This
4372 is the only code letter that specifies two successive arguments
4376 @xref{Interactive Codes, , Code Characters for @samp{interactive},
4377 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
4381 Declare that a list of variables is for use within the body of the
4382 @code{let} and give them an initial value, either @code{nil} or a
4383 specified value; then evaluate the rest of the expressions in the body
4384 of the @code{let} and return the value of the last one. Inside the
4385 body of the @code{let}, the Lisp interpreter does not see the values of
4386 the variables of the same names that are bound outside of the
4394 (let ((foo (buffer-name))
4395 (bar (buffer-size)))
4397 "This buffer is %s and has %d characters."
4402 @item save-excursion
4403 Record the values of point and mark and the current buffer before
4404 evaluating the body of this special form. Restore the values of point
4405 and mark and buffer afterward.
4412 (message "We are %d characters into this buffer."
4415 (goto-char (point-min)) (point))))
4420 Evaluate the first argument to the function; if it is true, evaluate
4421 the second argument; else evaluate the third argument, if there is one.
4423 The @code{if} special form is called a @dfn{conditional}. There are
4424 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
4433 (number-to-string 21)
4434 (substring (emacs-version) 10 12))
4435 (message "This is version 21 Emacs")
4436 (message "This is not version 21 Emacs"))
4442 Test whether two objects are the same. @code{equal} uses one meaning
4443 of the word `same' and @code{eq} uses another: @code{equal} returns
4444 true if the two objects have a similar structure and contents, such as
4445 two copies of the same book. On the other hand, @code{eq}, returns
4446 true if both arguments are actually the same object.
4455 The @code{<} function tests whether its first argument is smaller than
4456 its second argument. A corresponding function, @code{>}, tests whether
4457 the first argument is greater than the second. Likewise, @code{<=}
4458 tests whether the first argument is less than or equal to the second and
4459 @code{>=} tests whether the first argument is greater than or equal to
4460 the second. In all cases, both arguments must be numbers or markers
4461 (markers indicate positions in buffers).
4467 The @code{string-lessp} function tests whether its first argument is
4468 smaller than the second argument. A shorter, alternative name for the
4469 same function (a @code{defalias}) is @code{string<}.
4471 The arguments to @code{string-lessp} must be strings or symbols; the
4472 ordering is lexicographic, so case is significant. The print names of
4473 symbols are used instead of the symbols themselves.
4475 @cindex @samp{empty string} defined
4476 An empty string, @samp{""}, a string with no characters in it, is
4477 smaller than any string of characters.
4479 @code{string-equal} provides the corresponding test for equality. Its
4480 shorter, alternative name is @code{string=}. There are no string test
4481 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
4484 Print a message in the echo area. The first argument is a string that
4485 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
4486 arguments that follow the string. The argument used by @samp{%s} must
4487 be a string or a symbol; the argument used by @samp{%d} must be a
4488 number. The argument used by @samp{%c} must be an @sc{ascii} code
4489 number; it will be printed as the character with that @sc{ascii} code.
4493 The @code{setq} function sets the value of its first argument to the
4494 value of the second argument. The first argument is automatically
4495 quoted by @code{setq}. It does the same for succeeding pairs of
4496 arguments. Another function, @code{set}, takes only two arguments and
4497 evaluates both of them before setting the value returned by its first
4498 argument to the value returned by its second argument.
4501 Without an argument, return the name of the buffer, as a string.
4503 @itemx buffer-file-name
4504 Without an argument, return the name of the file the buffer is
4507 @item current-buffer
4508 Return the buffer in which Emacs is active; it may not be
4509 the buffer that is visible on the screen.
4512 Return the most recently selected buffer (other than the buffer passed
4513 to @code{other-buffer} as an argument and other than the current
4516 @item switch-to-buffer
4517 Select a buffer for Emacs to be active in and display it in the current
4518 window so users can look at it. Usually bound to @kbd{C-x b}.
4521 Switch Emacs' attention to a buffer on which programs will run. Don't
4522 alter what the window is showing.
4525 Return the number of characters in the current buffer.
4528 Return the value of the current position of the cursor, as an
4529 integer counting the number of characters from the beginning of the
4533 Return the minimum permissible value of point in
4534 the current buffer. This is 1, unless narrowing is in effect.
4537 Return the value of the maximum permissible value of point in the
4538 current buffer. This is the end of the buffer, unless narrowing is in
4543 @node defun Exercises, , Review, Writing Defuns
4548 Write a non-interactive function that doubles the value of its
4549 argument, a number. Make that function interactive.
4552 Write a function that tests whether the current value of
4553 @code{fill-column} is greater than the argument passed to the function,
4554 and if so, prints an appropriate message.
4557 @node Buffer Walk Through, More Complex, Writing Defuns, Top
4558 @comment node-name, next, previous, up
4559 @chapter A Few Buffer--Related Functions
4561 In this chapter we study in detail several of the functions used in GNU
4562 Emacs. This is called a ``walk-through''. These functions are used as
4563 examples of Lisp code, but are not imaginary examples; with the
4564 exception of the first, simplified function definition, these functions
4565 show the actual code used in GNU Emacs. You can learn a great deal from
4566 these definitions. The functions described here are all related to
4567 buffers. Later, we will study other functions.
4570 * Finding More:: How to find more information.
4571 * simplified-beginning-of-buffer:: Shows @code{goto-char},
4572 @code{point-min}, and @code{push-mark}.
4573 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
4574 * append-to-buffer:: Uses @code{save-excursion} and
4575 @code{insert-buffer-substring}.
4576 * Buffer Related Review:: Review.
4577 * Buffer Exercises::
4580 @node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
4581 @section Finding More Information
4583 @findex describe-function, @r{introduced}
4584 @cindex Find function documentation
4585 In this walk-through, I will describe each new function as we come to
4586 it, sometimes in detail and sometimes briefly. If you are interested,
4587 you can get the full documentation of any Emacs Lisp function at any
4588 time by typing @kbd{C-h f} and then the name of the function (and then
4589 @key{RET}). Similarly, you can get the full documentation for a
4590 variable by typing @kbd{C-h v} and then the name of the variable (and
4593 @cindex Find source of function
4594 In versions 20 and higher, when a function is written in Emacs Lisp,
4595 @code{describe-function} will also tell you the location of the
4596 function definition. If you move point over the file name and press
4597 the @key{RET} key, which in this case means @code{help-follow} rather
4598 than `return' or `enter', Emacs will take you directly to the function
4601 More generally, if you want to see a function in its original source
4602 file, you can use the @code{find-tags} function to jump to it.
4603 @code{find-tags} works with a wide variety of languages, not just
4604 Lisp, and C, and it works with non-programming text as well. For
4605 example, @code{find-tags} will jump to the various nodes in the
4606 Texinfo source file of this document.
4608 The @code{find-tags} function depends on `tags tables' that record
4609 the locations of the functions, variables, and other items to which
4610 @code{find-tags} jumps.
4612 To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the
4613 period key while holding down the @key{META} key, or else type the
4614 @key{ESC} key and then type the period key), and then, at the prompt,
4615 type in the name of the function whose source code you want to see,
4616 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will
4617 switch buffers and display the source code for the function on your
4618 screen. To switch back to your current buffer, type @kbd{C-x b
4619 @key{RET}}. (On some keyboards, the @key{META} key is labelled
4622 @c !!! 21.0.100 tags table location in this paragraph
4623 @cindex TAGS table, specifying
4625 Depending on how the initial default values of your copy of Emacs are
4626 set, you may also need to specify the location of your `tags table',
4627 which is a file called @file{TAGS}. For example, if you are
4628 interested in Emacs sources, the tags table you will most likely want,
4629 if it has already been created for you, will be in a subdirectory of
4630 the @file{/usr/local/share/emacs/} directory; thus you would use the
4631 @code{M-x visit-tags-table} command and specify a pathname such as
4632 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or
4633 @file{/usr/local/src/emacs/src/TAGS}. If the tags table has
4634 not already been created, you will have to create it yourself.
4637 To create a @file{TAGS} file in a specific directory, switch to that
4638 directory in Emacs using @kbd{M-x cd} command, or list the directory
4639 with @kbd{C-x d} (@code{dired}). Then run the compile command, with
4640 @w{@code{etags *.el}} as the command to execute
4643 M-x compile RET etags *.el RET
4646 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
4648 After you become more familiar with Emacs Lisp, you will find that you will
4649 frequently use @code{find-tags} to navigate your way around source code;
4650 and you will create your own @file{TAGS} tables.
4652 @cindex Library, as term for `file'
4653 Incidentally, the files that contain Lisp code are conventionally
4654 called @dfn{libraries}. The metaphor is derived from that of a
4655 specialized library, such as a law library or an engineering library,
4656 rather than a general library. Each library, or file, contains
4657 functions that relate to a particular topic or activity, such as
4658 @file{abbrev.el} for handling abbreviations and other typing
4659 shortcuts, and @file{help.el} for on-line help. (Sometimes several
4660 libraries provide code for a single activity, as the various
4661 @file{rmail@dots{}} files provide code for reading electronic mail.)
4662 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
4663 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
4664 by topic keywords.''
4666 @node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through
4667 @comment node-name, next, previous, up
4668 @section A Simplified @code{beginning-of-buffer} Definition
4669 @findex simplified-beginning-of-buffer
4671 The @code{beginning-of-buffer} command is a good function to start with
4672 since you are likely to be familiar with it and it is easy to
4673 understand. Used as an interactive command, @code{beginning-of-buffer}
4674 moves the cursor to the beginning of the buffer, leaving the mark at the
4675 previous position. It is generally bound to @kbd{M-<}.
4677 In this section, we will discuss a shortened version of the function
4678 that shows how it is most frequently used. This shortened function
4679 works as written, but it does not contain the code for a complex option.
4680 In another section, we will describe the entire function.
4681 (@xref{beginning-of-buffer, , Complete Definition of
4682 @code{beginning-of-buffer}}.)
4684 Before looking at the code, let's consider what the function
4685 definition has to contain: it must include an expression that makes
4686 the function interactive so it can be called by typing @kbd{M-x
4687 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
4688 must include code to leave a mark at the original position in the
4689 buffer; and it must include code to move the cursor to the beginning
4693 Here is the complete text of the shortened version of the function:
4697 (defun simplified-beginning-of-buffer ()
4698 "Move point to the beginning of the buffer;
4699 leave mark at previous position."
4702 (goto-char (point-min)))
4706 Like all function definitions, this definition has five parts following
4707 the special form @code{defun}:
4711 The name: in this example, @code{simplified-beginning-of-buffer}.
4714 A list of the arguments: in this example, an empty list, @code{()},
4717 The documentation string.
4720 The interactive expression.
4727 In this function definition, the argument list is empty; this means that
4728 this function does not require any arguments. (When we look at the
4729 definition for the complete function, we will see that it may be passed
4730 an optional argument.)
4732 The interactive expression tells Emacs that the function is intended to
4733 be used interactively. In this example, @code{interactive} does not have
4734 an argument because @code{simplified-beginning-of-buffer} does not
4738 The body of the function consists of the two lines:
4743 (goto-char (point-min))
4747 The first of these lines is the expression, @code{(push-mark)}. When
4748 this expression is evaluated by the Lisp interpreter, it sets a mark at
4749 the current position of the cursor, wherever that may be. The position
4750 of this mark is saved in the mark ring.
4752 The next line is @code{(goto-char (point-min))}. This expression
4753 jumps the cursor to the minimum point in the buffer, that is, to the
4754 beginning of the buffer (or to the beginning of the accessible portion
4755 of the buffer if it is narrowed. @xref{Narrowing & Widening, ,
4756 Narrowing and Widening}.)
4758 The @code{push-mark} command sets a mark at the place where the cursor
4759 was located before it was moved to the beginning of the buffer by the
4760 @code{(goto-char (point-min))} expression. Consequently, you can, if
4761 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
4763 That is all there is to the function definition!
4765 @findex describe-function
4766 When you are reading code such as this and come upon an unfamiliar
4767 function, such as @code{goto-char}, you can find out what it does by
4768 using the @code{describe-function} command. To use this command, type
4769 @kbd{C-h f} and then type in the name of the function and press
4770 @key{RET}. The @code{describe-function} command will print the
4771 function's documentation string in a @file{*Help*} window. For
4772 example, the documentation for @code{goto-char} is:
4776 One arg, a number. Set point to that number.
4777 Beginning of buffer is position (point-min),
4783 (The prompt for @code{describe-function} will offer you the symbol
4784 under or preceding the cursor, so you can save typing by positioning
4785 the cursor right over or after the function and then typing @kbd{C-h f
4788 The @code{end-of-buffer} function definition is written in the same way as
4789 the @code{beginning-of-buffer} definition except that the body of the
4790 function contains the expression @code{(goto-char (point-max))} in place
4791 of @code{(goto-char (point-min))}.
4793 @node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through
4794 @comment node-name, next, previous, up
4795 @section The Definition of @code{mark-whole-buffer}
4796 @findex mark-whole-buffer
4798 The @code{mark-whole-buffer} function is no harder to understand than the
4799 @code{simplified-beginning-of-buffer} function. In this case, however,
4800 we will look at the complete function, not a shortened version.
4802 The @code{mark-whole-buffer} function is not as commonly used as the
4803 @code{beginning-of-buffer} function, but is useful nonetheless: it
4804 marks a whole buffer as a region by putting point at the beginning and
4805 a mark at the end of the buffer. It is generally bound to @kbd{C-x
4810 * mark-whole-buffer overview::
4811 * Body of mark-whole-buffer:: Only three lines of code.
4815 @node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
4817 @unnumberedsubsec An overview of @code{mark-whole-buffer}
4821 In GNU Emacs 20, the code for the complete function looks like this:
4825 (defun mark-whole-buffer ()
4826 "Put point at beginning and mark at end of buffer."
4829 (push-mark (point-max))
4830 (goto-char (point-min)))
4835 Like all other functions, the @code{mark-whole-buffer} function fits
4836 into the template for a function definition. The template looks like
4841 (defun @var{name-of-function} (@var{argument-list})
4842 "@var{documentation}@dots{}"
4843 (@var{interactive-expression}@dots{})
4848 Here is how the function works: the name of the function is
4849 @code{mark-whole-buffer}; it is followed by an empty argument list,
4850 @samp{()}, which means that the function does not require arguments.
4851 The documentation comes next.
4853 The next line is an @code{(interactive)} expression that tells Emacs
4854 that the function will be used interactively. These details are similar
4855 to the @code{simplified-beginning-of-buffer} function described in the
4859 @node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer
4860 @comment node-name, next, previous, up
4861 @subsection Body of @code{mark-whole-buffer}
4863 The body of the @code{mark-whole-buffer} function consists of three
4869 (push-mark (point-max))
4870 (goto-char (point-min))
4874 The first of these lines is the expression, @code{(push-mark (point))}.
4876 This line does exactly the same job as the first line of the body of
4877 the @code{simplified-beginning-of-buffer} function, which is written
4878 @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark
4879 at the current position of the cursor.
4881 I don't know why the expression in @code{mark-whole-buffer} is written
4882 @code{(push-mark (point))} and the expression in
4883 @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps
4884 whoever wrote the code did not know that the arguments for
4885 @code{push-mark} are optional and that if @code{push-mark} is not
4886 passed an argument, the function automatically sets mark at the
4887 location of point by default. Or perhaps the expression was written
4888 so as to parallel the structure of the next line. In any case, the
4889 line causes Emacs to determine the position of point and set a mark
4892 The next line of @code{mark-whole-buffer} is @code{(push-mark (point-max)}.
4893 This expression sets a mark at the point in the buffer
4894 that has the highest number. This will be the end of the buffer (or,
4895 if the buffer is narrowed, the end of the accessible portion of the
4896 buffer. @xref{Narrowing & Widening, , Narrowing and Widening}, for
4897 more about narrowing.) After this mark has been set, the previous
4898 mark, the one set at point, is no longer set, but Emacs remembers its
4899 position, just as all other recent marks are always remembered. This
4900 means that you can, if you wish, go back to that position by typing
4901 @kbd{C-u C-@key{SPC}} twice.
4903 (In GNU Emacs 21, the @code{(push-mark (point-max)} is slightly more
4904 complicated than shown here. The line reads
4907 (push-mark (point-max) nil t)
4911 (The expression works nearly the same as before. It sets a mark at
4912 the highest numbered place in the buffer that it can. However, in
4913 this version, @code{push-mark} has two additional arguments. The
4914 second argument to @code{push-mark} is @code{nil}. This tells the
4915 function it @emph{should} display a message that says `Mark set' when
4916 it pushes the mark. The third argument is @code{t}. This tells
4917 @code{push-mark} to activate the mark when Transient Mark mode is
4918 turned on. Transient Mark mode highlights the currently active
4919 region. It is usually turned off.)
4921 Finally, the last line of the function is @code{(goto-char
4922 (point-min)))}. This is written exactly the same way as it is written
4923 in @code{beginning-of-buffer}. The expression moves the cursor to
4924 the minimum point in the buffer, that is, to the beginning of the buffer
4925 (or to the beginning of the accessible portion of the buffer). As a
4926 result of this, point is placed at the beginning of the buffer and mark
4927 is set at the end of the buffer. The whole buffer is, therefore, the
4930 @node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through
4931 @comment node-name, next, previous, up
4932 @section The Definition of @code{append-to-buffer}
4933 @findex append-to-buffer
4935 The @code{append-to-buffer} command is very nearly as simple as the
4936 @code{mark-whole-buffer} command. What it does is copy the region (that
4937 is, the part of the buffer between point and mark) from the current
4938 buffer to a specified buffer.
4941 * append-to-buffer overview::
4942 * append interactive:: A two part interactive expression.
4943 * append-to-buffer body:: Incorporates a @code{let} expression.
4944 * append save-excursion:: How the @code{save-excursion} works.
4947 @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
4949 @unnumberedsubsec An Overview of @code{append-to-buffer}
4952 @findex insert-buffer-substring
4953 The @code{append-to-buffer} command uses the
4954 @code{insert-buffer-substring} function to copy the region.
4955 @code{insert-buffer-substring} is described by its name: it takes a
4956 string of characters from part of a buffer, a ``substring'', and
4957 inserts them into another buffer. Most of @code{append-to-buffer} is
4958 concerned with setting up the conditions for
4959 @code{insert-buffer-substring} to work: the code must specify both the
4960 buffer to which the text will go and the region that will be copied.
4961 Here is the complete text of the function:
4965 (defun append-to-buffer (buffer start end)
4966 "Append to specified buffer the text of the region.
4967 It is inserted into that buffer before its point.
4971 When calling from a program, give three arguments:
4972 a buffer or the name of one, and two character numbers
4973 specifying the portion of the current buffer to be copied."
4974 (interactive "BAppend to buffer:@: \nr")
4975 (let ((oldbuf (current-buffer)))
4977 (set-buffer (get-buffer-create buffer))
4978 (insert-buffer-substring oldbuf start end))))
4982 The function can be understood by looking at it as a series of
4983 filled-in templates.
4985 The outermost template is for the function definition. In this
4986 function, it looks like this (with several slots filled in):
4990 (defun append-to-buffer (buffer start end)
4991 "@var{documentation}@dots{}"
4992 (interactive "BAppend to buffer:@: \nr")
4997 The first line of the function includes its name and three arguments.
4998 The arguments are the @code{buffer} to which the text will be copied, and
4999 the @code{start} and @code{end} of the region in the current buffer that
5002 The next part of the function is the documentation, which is clear and
5005 @node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
5006 @comment node-name, next, previous, up
5007 @subsection The @code{append-to-buffer} Interactive Expression
5009 Since the @code{append-to-buffer} function will be used interactively,
5010 the function must have an @code{interactive} expression. (For a
5011 review of @code{interactive}, see @ref{Interactive, , Making a
5012 Function Interactive}.) The expression reads as follows:
5015 (interactive "BAppend to buffer:@: \nr")
5019 This expression has an argument inside of quotation marks and that
5020 argument has two parts, separated by @samp{\n}.
5022 The first part is @samp{BAppend to buffer:@: }. Here, the @samp{B}
5023 tells Emacs to ask for the name of the buffer that will be passed to the
5024 function. Emacs will ask for the name by prompting the user in the
5025 minibuffer, using the string following the @samp{B}, which is the string
5026 @samp{Append to buffer:@: }. Emacs then binds the variable @code{buffer}
5027 in the function's argument list to the specified buffer.
5029 The newline, @samp{\n}, separates the first part of the argument from
5030 the second part. It is followed by an @samp{r} that tells Emacs to bind
5031 the two arguments that follow the symbol @code{buffer} in the function's
5032 argument list (that is, @code{start} and @code{end}) to the values of
5035 @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
5036 @comment node-name, next, previous, up
5037 @subsection The Body of @code{append-to-buffer}
5039 The body of the @code{append-to-buffer} function begins with @code{let}.
5041 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
5042 @code{let} expression is to create and give initial values to one or
5043 more variables that will only be used within the body of the
5044 @code{let}. This means that such a variable will not be confused with
5045 any variable of the same name outside the @code{let} expression.
5047 We can see how the @code{let} expression fits into the function as a
5048 whole by showing a template for @code{append-to-buffer} with the
5049 @code{let} expression in outline:
5053 (defun append-to-buffer (buffer start end)
5054 "@var{documentation}@dots{}"
5055 (interactive "BAppend to buffer:@: \nr")
5056 (let ((@var{variable} @var{value}))
5061 The @code{let} expression has three elements:
5065 The symbol @code{let};
5068 A varlist containing, in this case, a single two-element list,
5069 @code{(@var{variable} @var{value})};
5072 The body of the @code{let} expression.
5076 In the @code{append-to-buffer} function, the varlist looks like this:
5079 (oldbuf (current-buffer))
5083 In this part of the @code{let} expression, the one variable,
5084 @code{oldbuf}, is bound to the value returned by the
5085 @code{(current-buffer)} expression. The variable, @code{oldbuf}, is
5086 used to keep track of the buffer in which you are working and from
5087 which you will copy.
5089 The element or elements of a varlist are surrounded by a set of
5090 parentheses so the Lisp interpreter can distinguish the varlist from
5091 the body of the @code{let}. As a consequence, the two-element list
5092 within the varlist is surrounded by a circumscribing set of parentheses.
5093 The line looks like this:
5097 (let ((oldbuf (current-buffer)))
5103 The two parentheses before @code{oldbuf} might surprise you if you did
5104 not realize that the first parenthesis before @code{oldbuf} marks the
5105 boundary of the varlist and the second parenthesis marks the beginning
5106 of the two-element list, @code{(oldbuf (current-buffer))}.
5108 @node append save-excursion, , append-to-buffer body, append-to-buffer
5109 @comment node-name, next, previous, up
5110 @subsection @code{save-excursion} in @code{append-to-buffer}
5112 The body of the @code{let} expression in @code{append-to-buffer}
5113 consists of a @code{save-excursion} expression.
5115 The @code{save-excursion} function saves the locations of point and
5116 mark, and restores them to those positions after the expressions in the
5117 body of the @code{save-excursion} complete execution. In addition,
5118 @code{save-excursion} keeps track of the original buffer, and
5119 restores it. This is how @code{save-excursion} is used in
5120 @code{append-to-buffer}.
5123 @cindex Indentation for formatting
5124 @cindex Formatting convention
5125 Incidentally, it is worth noting here that a Lisp function is normally
5126 formatted so that everything that is enclosed in a multi-line spread is
5127 indented more to the right than the first symbol. In this function
5128 definition, the @code{let} is indented more than the @code{defun}, and
5129 the @code{save-excursion} is indented more than the @code{let}, like
5145 This formatting convention makes it easy to see that the two lines in
5146 the body of the @code{save-excursion} are enclosed by the parentheses
5147 associated with @code{save-excursion}, just as the
5148 @code{save-excursion} itself is enclosed by the parentheses associated
5149 with the @code{let}:
5153 (let ((oldbuf (current-buffer)))
5155 (set-buffer (get-buffer-create buffer))
5156 (insert-buffer-substring oldbuf start end))))
5161 The use of the @code{save-excursion} function can be viewed as a process
5162 of filling in the slots of a template:
5167 @var{first-expression-in-body}
5168 @var{second-expression-in-body}
5170 @var{last-expression-in-body})
5176 In this function, the body of the @code{save-excursion} contains only
5177 two expressions. The body looks like this:
5181 (set-buffer (get-buffer-create buffer))
5182 (insert-buffer-substring oldbuf start end)
5186 When the @code{append-to-buffer} function is evaluated, the two
5187 expressions in the body of the @code{save-excursion} are evaluated in
5188 sequence. The value of the last expression is returned as the value of
5189 the @code{save-excursion} function; the other expression is evaluated
5190 only for its side effects.
5192 The first line in the body of the @code{save-excursion} uses the
5193 @code{set-buffer} function to change the current buffer to the one
5194 specified in the first argument to @code{append-to-buffer}. (Changing
5195 the buffer is the side effect; as we have said before, in Lisp, a side
5196 effect is often the primary thing we want.) The second line does the
5197 primary work of the function.
5199 The @code{set-buffer} function changes Emacs' attention to the buffer to
5200 which the text will be copied and from which @code{save-excursion} will
5204 The line looks like this:
5207 (set-buffer (get-buffer-create buffer))
5210 The innermost expression of this list is @code{(get-buffer-create
5211 buffer)}. This expression uses the @code{get-buffer-create} function,
5212 which either gets the named buffer, or if it does not exist, creates one
5213 with the given name. This means you can use @code{append-to-buffer} to
5214 put text into a buffer that did not previously exist.
5216 @code{get-buffer-create} also keeps @code{set-buffer} from getting an
5217 unnecessary error: @code{set-buffer} needs a buffer to go to; if you
5218 were to specify a buffer that does not exist, Emacs would baulk.
5219 Since @code{get-buffer-create} will create a buffer if none exists,
5220 @code{set-buffer} is always provided with a buffer.
5223 The last line of @code{append-to-buffer} does the work of appending
5227 (insert-buffer-substring oldbuf start end)
5231 The @code{insert-buffer-substring} function copies a string @emph{from}
5232 the buffer specified as its first argument and inserts the string into
5233 the present buffer. In this case, the argument to
5234 @code{insert-buffer-substring} is the value of the variable created and
5235 bound by the @code{let}, namely the value of @code{oldbuf}, which was
5236 the current buffer when you gave the @code{append-to-buffer} command.
5238 After @code{insert-buffer-substring} has done its work,
5239 @code{save-excursion} will restore the action to the original buffer and
5240 @code{append-to-buffer} will have done its job.
5243 Written in skeletal form, the workings of the body look like this:
5247 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5248 (save-excursion ; @r{Keep track of buffer.}
5250 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
5252 @var{change-back-to-original-buffer-when-finished}
5253 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
5258 In summary, @code{append-to-buffer} works as follows: it saves the value
5259 of the current buffer in the variable called @code{oldbuf}. It gets the
5260 new buffer, creating one if need be, and switches Emacs to it. Using
5261 the value of @code{oldbuf}, it inserts the region of text from the old
5262 buffer into the new buffer; and then using @code{save-excursion}, it
5263 brings you back to your original buffer.
5265 In looking at @code{append-to-buffer}, you have explored a fairly
5266 complex function. It shows how to use @code{let} and
5267 @code{save-excursion}, and how to change to and come back from another
5268 buffer. Many function definitions use @code{let},
5269 @code{save-excursion}, and @code{set-buffer} this way.
5271 @node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through
5272 @comment node-name, next, previous, up
5275 Here is a brief summary of the various functions discussed in this chapter.
5278 @item describe-function
5279 @itemx describe-variable
5280 Print the documentation for a function or variable.
5281 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
5284 Find the file containing the source for a function or variable and
5285 switch buffers to it, positioning point at the beginning of the item.
5286 Conventionally bound to @kbd{M-.} (that's a period following the
5289 @item save-excursion
5290 Save the location of point and mark and restore their values after the
5291 arguments to @code{save-excursion} have been evaluated. Also, remember
5292 the current buffer and return to it.
5295 Set mark at a location and record the value of the previous mark on the
5296 mark ring. The mark is a location in the buffer that will keep its
5297 relative position even if text is added to or removed from the buffer.
5300 Set point to the location specified by the value of the argument, which
5301 can be a number, a marker, or an expression that returns the number of
5302 a position, such as @code{(point-min)}.
5304 @item insert-buffer-substring
5305 Copy a region of text from a buffer that is passed to the function as
5306 an argument and insert the region into the current buffer.
5308 @item mark-whole-buffer
5309 Mark the whole buffer as a region. Normally bound to @kbd{C-x h}.
5312 Switch the attention of Emacs to another buffer, but do not change the
5313 window being displayed. Used when the program rather than a human is
5314 to work on a different buffer.
5316 @item get-buffer-create
5318 Find a named buffer or create one if a buffer of that name does not
5319 exist. The @code{get-buffer} function returns @code{nil} if the named
5320 buffer does not exist.
5324 @node Buffer Exercises, , Buffer Related Review, Buffer Walk Through
5329 Write your own @code{simplified-end-of-buffer} function definition;
5330 then test it to see whether it works.
5333 Use @code{if} and @code{get-buffer} to write a function that prints a
5334 message telling you whether a buffer exists.
5337 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
5341 @node More Complex, Narrowing & Widening, Buffer Walk Through, Top
5342 @comment node-name, next, previous, up
5343 @chapter A Few More Complex Functions
5345 In this chapter, we build on what we have learned in previous chapters
5346 by looking at more complex functions. The @code{copy-to-buffer}
5347 function illustrates use of two @code{save-excursion} expressions in
5348 one definition, while the @code{insert-buffer} function illustrates
5349 use of an asterisk in an @code{interactive} expression, use of
5350 @code{or}, and the important distinction between a name and the object
5351 to which the name refers.
5354 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
5355 * insert-buffer:: Read-only, and with @code{or}.
5356 * beginning-of-buffer:: Shows @code{goto-char},
5357 @code{point-min}, and @code{push-mark}.
5358 * Second Buffer Related Review::
5359 * optional Exercise::
5362 @node copy-to-buffer, insert-buffer, More Complex, More Complex
5363 @comment node-name, next, previous, up
5364 @section The Definition of @code{copy-to-buffer}
5365 @findex copy-to-buffer
5367 After understanding how @code{append-to-buffer} works, it is easy to
5368 understand @code{copy-to-buffer}. This function copies text into a
5369 buffer, but instead of adding to the second buffer, it replaces the
5370 previous text in the second buffer. The code for the
5371 @code{copy-to-buffer} function is almost the same as the code for
5372 @code{append-to-buffer}, except that @code{erase-buffer} and a second
5373 @code{save-excursion} are used. (@xref{append-to-buffer, , The
5374 Definition of @code{append-to-buffer}}, for the description of
5375 @code{append-to-buffer}.)
5378 The body of @code{copy-to-buffer} looks like this
5383 (interactive "BCopy to buffer:@: \nr")
5384 (let ((oldbuf (current-buffer)))
5386 (set-buffer (get-buffer-create buffer))
5389 (insert-buffer-substring oldbuf start end)))))
5393 This code is similar to the code in @code{append-to-buffer}: it is
5394 only after changing to the buffer to which the text will be copied
5395 that the definition for this function diverges from the definition for
5396 @code{append-to-buffer}: the @code{copy-to-buffer} function erases the
5397 buffer's former contents. (This is what is meant by `replacement'; to
5398 replace text, Emacs erases the previous text and then inserts new
5399 text.) After erasing the previous contents of the buffer,
5400 @code{save-excursion} is used for a second time and the new text is
5403 Why is @code{save-excursion} used twice? Consider again what the
5407 In outline, the body of @code{copy-to-buffer} looks like this:
5411 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
5412 (save-excursion ; @r{First use of @code{save-excursion}.}
5415 (save-excursion ; @r{Second use of @code{save-excursion}.}
5416 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
5420 The first use of @code{save-excursion} returns Emacs to the buffer from
5421 which the text is being copied. That is clear, and is just like its use
5422 in @code{append-to-buffer}. Why the second use? The reason is that
5423 @code{insert-buffer-substring} always leaves point at the @emph{end} of
5424 the region being inserted. The second @code{save-excursion} causes
5425 Emacs to leave point at the beginning of the text being inserted. In
5426 most circumstances, users prefer to find point at the beginning of
5427 inserted text. (Of course, the @code{copy-to-buffer} function returns
5428 the user to the original buffer when done---but if the user @emph{then}
5429 switches to the copied-to buffer, point will go to the beginning of the
5430 text. Thus, this use of a second @code{save-excursion} is a little
5433 @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
5434 @comment node-name, next, previous, up
5435 @section The Definition of @code{insert-buffer}
5436 @findex insert-buffer
5438 @code{insert-buffer} is yet another buffer-related function. This
5439 command copies another buffer @emph{into} the current buffer. It is the
5440 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
5441 copy a region of text @emph{from} the current buffer to another buffer.
5443 Here is a discussion based on the original code. The code was
5444 simplified in 2003 and is harder to understand.
5446 In addition, this code illustrates the use of @code{interactive} with a
5447 buffer that might be @dfn{read-only} and the important distinction
5448 between the name of an object and the object actually referred to.
5451 * insert-buffer code::
5452 * insert-buffer interactive:: When you can read, but not write.
5453 * insert-buffer body:: The body has an @code{or} and a @code{let}.
5454 * if & or:: Using an @code{if} instead of an @code{or}.
5455 * Insert or:: How the @code{or} expression works.
5456 * Insert let:: Two @code{save-excursion} expressions.
5459 @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
5461 @unnumberedsubsec The Code for @code{insert-buffer}
5469 (defun insert-buffer (buffer)
5470 "Insert after point the contents of BUFFER.
5471 Puts mark after the inserted text.
5472 BUFFER may be a buffer or a buffer name."
5473 (interactive "*bInsert buffer:@: ")
5476 (or (bufferp buffer)
5477 (setq buffer (get-buffer buffer)))
5478 (let (start end newmark)
5482 (setq start (point-min) end (point-max)))
5485 (insert-buffer-substring buffer start end)
5486 (setq newmark (point)))
5487 (push-mark newmark)))
5492 As with other function definitions, you can use a template to see an
5493 outline of the function:
5497 (defun insert-buffer (buffer)
5498 "@var{documentation}@dots{}"
5499 (interactive "*bInsert buffer:@: ")
5504 @node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer
5505 @comment node-name, next, previous, up
5506 @subsection The Interactive Expression in @code{insert-buffer}
5507 @findex interactive, @r{example use of}
5509 In @code{insert-buffer}, the argument to the @code{interactive}
5510 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
5514 * Read-only buffer:: When a buffer cannot be modified.
5515 * b for interactive:: An existing buffer or else its name.
5518 @node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
5519 @comment node-name, next, previous, up
5520 @unnumberedsubsubsec A Read-only Buffer
5521 @cindex Read-only buffer
5522 @cindex Asterisk for read-only buffer
5523 @findex * @r{for read-only buffer}
5525 The asterisk is for the situation when the current buffer is a
5526 read-only buffer---a buffer that cannot be modified. If
5527 @code{insert-buffer} is called when the current buffer is read-only, a
5528 message to this effect is printed in the echo area and the terminal
5529 may beep or blink at you; you will not be permitted to insert anything
5530 into current buffer. The asterisk does not need to be followed by a
5531 newline to separate it from the next argument.
5533 @node b for interactive, , Read-only buffer, insert-buffer interactive
5534 @comment node-name, next, previous, up
5535 @unnumberedsubsubsec @samp{b} in an Interactive Expression
5537 The next argument in the interactive expression starts with a lower
5538 case @samp{b}. (This is different from the code for
5539 @code{append-to-buffer}, which uses an upper-case @samp{B}.
5540 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
5541 The lower-case @samp{b} tells the Lisp interpreter that the argument
5542 for @code{insert-buffer} should be an existing buffer or else its
5543 name. (The upper-case @samp{B} option provides for the possibility
5544 that the buffer does not exist.) Emacs will prompt you for the name
5545 of the buffer, offering you a default buffer, with name completion
5546 enabled. If the buffer does not exist, you receive a message that
5547 says ``No match''; your terminal may beep at you as well.
5549 @node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
5550 @comment node-name, next, previous, up
5551 @subsection The Body of the @code{insert-buffer} Function
5553 The body of the @code{insert-buffer} function has two major parts: an
5554 @code{or} expression and a @code{let} expression. The purpose of the
5555 @code{or} expression is to ensure that the argument @code{buffer} is
5556 bound to a buffer and not just the name of a buffer. The body of the
5557 @code{let} expression contains the code which copies the other buffer
5558 into the current buffer.
5561 In outline, the two expressions fit into the @code{insert-buffer}
5566 (defun insert-buffer (buffer)
5567 "@var{documentation}@dots{}"
5568 (interactive "*bInsert buffer:@: ")
5573 (let (@var{varlist})
5574 @var{body-of-}@code{let}@dots{} )
5578 To understand how the @code{or} expression ensures that the argument
5579 @code{buffer} is bound to a buffer and not to the name of a buffer, it
5580 is first necessary to understand the @code{or} function.
5582 Before doing this, let me rewrite this part of the function using
5583 @code{if} so that you can see what is done in a manner that will be familiar.
5585 @node if & or, Insert or, insert-buffer body, insert-buffer
5586 @comment node-name, next, previous, up
5587 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
5589 The job to be done is to make sure the value of @code{buffer} is a
5590 buffer itself and not the name of a buffer. If the value is the name,
5591 then the buffer itself must be got.
5593 You can imagine yourself at a conference where an usher is wandering
5594 around holding a list with your name on it and looking for you: the
5595 usher is ``bound'' to your name, not to you; but when the usher finds
5596 you and takes your arm, the usher becomes ``bound'' to you.
5599 In Lisp, you might describe this situation like this:
5603 (if (not (holding-on-to-guest))
5604 (find-and-take-arm-of-guest))
5608 We want to do the same thing with a buffer---if we do not have the
5609 buffer itself, we want to get it.
5612 Using a predicate called @code{bufferp} that tells us whether we have a
5613 buffer (rather than its name), we can write the code like this:
5617 (if (not (bufferp buffer)) ; @r{if-part}
5618 (setq buffer (get-buffer buffer))) ; @r{then-part}
5623 Here, the true-or-false-test of the @code{if} expression is
5624 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
5625 @w{@code{(setq buffer (get-buffer buffer))}}.
5627 In the test, the function @code{bufferp} returns true if its argument is
5628 a buffer---but false if its argument is the name of the buffer. (The
5629 last character of the function name @code{bufferp} is the character
5630 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
5631 indicates that the function is a predicate, which is a term that means
5632 that the function will determine whether some property is true or false.
5633 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
5637 The function @code{not} precedes the expression @code{(bufferp buffer)},
5638 so the true-or-false-test looks like this:
5641 (not (bufferp buffer))
5645 @code{not} is a function that returns true if its argument is false
5646 and false if its argument is true. So if @code{(bufferp buffer)}
5647 returns true, the @code{not} expression returns false and vice-versa:
5648 what is ``not true'' is false and what is ``not false'' is true.
5650 Using this test, the @code{if} expression works as follows: when the
5651 value of the variable @code{buffer} is actually a buffer rather than
5652 its name, the true-or-false-test returns false and the @code{if}
5653 expression does not evaluate the then-part. This is fine, since we do
5654 not need to do anything to the variable @code{buffer} if it really is
5657 On the other hand, when the value of @code{buffer} is not a buffer
5658 itself, but the name of a buffer, the true-or-false-test returns true
5659 and the then-part of the expression is evaluated. In this case, the
5660 then-part is @code{(setq buffer (get-buffer buffer))}. This
5661 expression uses the @code{get-buffer} function to return an actual
5662 buffer itself, given its name. The @code{setq} then sets the variable
5663 @code{buffer} to the value of the buffer itself, replacing its previous
5664 value (which was the name of the buffer).
5666 @node Insert or, Insert let, if & or, insert-buffer
5667 @comment node-name, next, previous, up
5668 @subsection The @code{or} in the Body
5670 The purpose of the @code{or} expression in the @code{insert-buffer}
5671 function is to ensure that the argument @code{buffer} is bound to a
5672 buffer and not just to the name of a buffer. The previous section shows
5673 how the job could have been done using an @code{if} expression.
5674 However, the @code{insert-buffer} function actually uses @code{or}.
5675 To understand this, it is necessary to understand how @code{or} works.
5678 An @code{or} function can have any number of arguments. It evaluates
5679 each argument in turn and returns the value of the first of its
5680 arguments that is not @code{nil}. Also, and this is a crucial feature
5681 of @code{or}, it does not evaluate any subsequent arguments after
5682 returning the first non-@code{nil} value.
5685 The @code{or} expression looks like this:
5689 (or (bufferp buffer)
5690 (setq buffer (get-buffer buffer)))
5695 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
5696 This expression returns true (a non-@code{nil} value) if the buffer is
5697 actually a buffer, and not just the name of a buffer. In the @code{or}
5698 expression, if this is the case, the @code{or} expression returns this
5699 true value and does not evaluate the next expression---and this is fine
5700 with us, since we do not want to do anything to the value of
5701 @code{buffer} if it really is a buffer.
5703 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
5704 which it will be if the value of @code{buffer} is the name of a buffer,
5705 the Lisp interpreter evaluates the next element of the @code{or}
5706 expression. This is the expression @code{(setq buffer (get-buffer
5707 buffer))}. This expression returns a non-@code{nil} value, which
5708 is the value to which it sets the variable @code{buffer}---and this
5709 value is a buffer itself, not the name of a buffer.
5711 The result of all this is that the symbol @code{buffer} is always
5712 bound to a buffer itself rather than to the name of a buffer. All
5713 this is necessary because the @code{set-buffer} function in a
5714 following line only works with a buffer itself, not with the name to a
5718 Incidentally, using @code{or}, the situation with the usher would be
5722 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
5725 @node Insert let, , Insert or, insert-buffer
5726 @comment node-name, next, previous, up
5727 @subsection The @code{let} Expression in @code{insert-buffer}
5729 After ensuring that the variable @code{buffer} refers to a buffer itself
5730 and not just to the name of a buffer, the @code{insert-buffer function}
5731 continues with a @code{let} expression. This specifies three local
5732 variables, @code{start}, @code{end}, and @code{newmark} and binds them
5733 to the initial value @code{nil}. These variables are used inside the
5734 remainder of the @code{let} and temporarily hide any other occurrence of
5735 variables of the same name in Emacs until the end of the @code{let}.
5738 The body of the @code{let} contains two @code{save-excursion}
5739 expressions. First, we will look at the inner @code{save-excursion}
5740 expression in detail. The expression looks like this:
5746 (setq start (point-min) end (point-max)))
5751 The expression @code{(set-buffer buffer)} changes Emacs' attention
5752 from the current buffer to the one from which the text will copied.
5753 In that buffer, the variables @code{start} and @code{end} are set to
5754 the beginning and end of the buffer, using the commands
5755 @code{point-min} and @code{point-max}. Note that we have here an
5756 illustration of how @code{setq} is able to set two variables in the
5757 same expression. The first argument of @code{setq} is set to the
5758 value of its second, and its third argument is set to the value of its
5761 After the body of the inner @code{save-excursion} is evaluated, the
5762 @code{save-excursion} restores the original buffer, but @code{start} and
5763 @code{end} remain set to the values of the beginning and end of the
5764 buffer from which the text will be copied.
5767 The outer @code{save-excursion} expression looks like this:
5772 (@var{inner-}@code{save-excursion}@var{-expression}
5773 (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
5774 (insert-buffer-substring buffer start end)
5775 (setq newmark (point)))
5780 The @code{insert-buffer-substring} function copies the text
5781 @emph{into} the current buffer @emph{from} the region indicated by
5782 @code{start} and @code{end} in @code{buffer}. Since the whole of the
5783 second buffer lies between @code{start} and @code{end}, the whole of
5784 the second buffer is copied into the buffer you are editing. Next,
5785 the value of point, which will be at the end of the inserted text, is
5786 recorded in the variable @code{newmark}.
5788 After the body of the outer @code{save-excursion} is evaluated, point
5789 and mark are relocated to their original places.
5791 However, it is convenient to locate a mark at the end of the newly
5792 inserted text and locate point at its beginning. The @code{newmark}
5793 variable records the end of the inserted text. In the last line of
5794 the @code{let} expression, the @code{(push-mark newmark)} expression
5795 function sets a mark to this location. (The previous location of the
5796 mark is still accessible; it is recorded on the mark ring and you can
5797 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is
5798 located at the beginning of the inserted text, which is where it was
5799 before you called the insert function, the position of which was saved
5800 by the first @code{save-excursion}.
5803 The whole @code{let} expression looks like this:
5807 (let (start end newmark)
5811 (setq start (point-min) end (point-max)))
5812 (insert-buffer-substring buffer start end)
5813 (setq newmark (point)))
5814 (push-mark newmark))
5818 Like the @code{append-to-buffer} function, the @code{insert-buffer}
5819 function uses @code{let}, @code{save-excursion}, and
5820 @code{set-buffer}. In addition, the function illustrates one way to
5821 use @code{or}. All these functions are building blocks that we will
5822 find and use again and again.
5824 @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
5825 @comment node-name, next, previous, up
5826 @section Complete Definition of @code{beginning-of-buffer}
5827 @findex beginning-of-buffer
5829 The basic structure of the @code{beginning-of-buffer} function has
5830 already been discussed. (@xref{simplified-beginning-of-buffer, , A
5831 Simplified @code{beginning-of-buffer} Definition}.)
5832 This section describes the complex part of the definition.
5834 As previously described, when invoked without an argument,
5835 @code{beginning-of-buffer} moves the cursor to the beginning of the
5836 buffer, leaving the mark at the previous position. However, when the
5837 command is invoked with a number between one and ten, the function
5838 considers that number to be a fraction of the length of the buffer,
5839 measured in tenths, and Emacs moves the cursor that fraction of the way
5840 from the beginning of the buffer. Thus, you can either call this
5841 function with the key command @kbd{M-<}, which will move the cursor to
5842 the beginning of the buffer, or with a key command such as @kbd{C-u 7
5843 M-<} which will move the cursor to a point 70% of the way through the
5844 buffer. If a number bigger than ten is used for the argument, it moves
5845 to the end of the buffer.
5847 The @code{beginning-of-buffer} function can be called with or without an
5848 argument. The use of the argument is optional.
5851 * Optional Arguments::
5852 * beginning-of-buffer opt arg:: Example with optional argument.
5853 * beginning-of-buffer complete::
5856 @node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
5857 @subsection Optional Arguments
5859 Unless told otherwise, Lisp expects that a function with an argument in
5860 its function definition will be called with a value for that argument.
5861 If that does not happen, you get an error and a message that says
5862 @samp{Wrong number of arguments}.
5864 @cindex Optional arguments
5867 However, optional arguments are a feature of Lisp: a @dfn{keyword} may
5868 be used to tell the Lisp interpreter that an argument is optional.
5869 The keyword is @code{&optional}. (The @samp{&} in front of
5870 @samp{optional} is part of the keyword.) In a function definition, if
5871 an argument follows the keyword @code{&optional}, a value does not
5872 need to be passed to that argument when the function is called.
5875 The first line of the function definition of @code{beginning-of-buffer}
5876 therefore looks like this:
5879 (defun beginning-of-buffer (&optional arg)
5883 In outline, the whole function looks like this:
5887 (defun beginning-of-buffer (&optional arg)
5888 "@var{documentation}@dots{}"
5892 (@var{if-there-is-an-argument}
5893 @var{figure-out-where-to-go}
5899 The function is similar to the @code{simplified-beginning-of-buffer}
5900 function except that the @code{interactive} expression has @code{"P"}
5901 as an argument and the @code{goto-char} function is followed by an
5902 if-then-else expression that figures out where to put the cursor if
5903 there is an argument.
5905 The @code{"P"} in the @code{interactive} expression tells Emacs to pass
5906 a prefix argument, if there is one, to the function. A prefix argument
5907 is made by typing the @key{META} key followed by a number, or by typing
5908 @kbd{C-u} and then a number (if you don't type a number, @kbd{C-u}
5911 The true-or-false-test of the @code{if} expression is simple: it is
5912 simply the argument @code{arg}. If @code{arg} has a value that is not
5913 @code{nil}, which will be the case if @code{beginning-of-buffer} is
5914 called with an argument, then this true-or-false-test will return true
5915 and the then-part of the @code{if} expression will be evaluated. On the
5916 other hand, if @code{beginning-of-buffer} is not called with an
5917 argument, the value of @code{arg} will be @code{nil} and the else-part
5918 of the @code{if} expression will be evaluated. The else-part is simply
5919 @code{point-min}, and when this is the outcome, the whole
5920 @code{goto-char} expression is @code{(goto-char (point-min))}, which is
5921 how we saw the @code{beginning-of-buffer} function in its simplified
5924 @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
5925 @subsection @code{beginning-of-buffer} with an Argument
5927 When @code{beginning-of-buffer} is called with an argument, an
5928 expression is evaluated which calculates what value to pass to
5929 @code{goto-char}. This expression is rather complicated at first sight.
5930 It includes an inner @code{if} expression and much arithmetic. It looks
5935 (if (> (buffer-size) 10000)
5936 ;; @r{Avoid overflow for large buffer sizes!}
5937 (* (prefix-numeric-value arg) (/ (buffer-size) 10))
5941 (buffer-size) (prefix-numeric-value arg))) 10))
5946 * Disentangle beginning-of-buffer::
5947 * Large buffer case::
5948 * Small buffer case::
5951 @node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg
5953 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
5956 Like other complex-looking expressions, the conditional expression
5957 within @code{beginning-of-buffer} can be disentangled by looking at it
5958 as parts of a template, in this case, the template for an if-then-else
5959 expression. In skeletal form, the expression looks like this:
5963 (if (@var{buffer-is-large}
5964 @var{divide-buffer-size-by-10-and-multiply-by-arg}
5965 @var{else-use-alternate-calculation}
5969 The true-or-false-test of this inner @code{if} expression checks the
5970 size of the buffer. The reason for this is that the old Version 18
5971 Emacs used numbers that are no bigger than eight million or so
5972 and in the computation that followed, the programmer feared that Emacs
5973 might try to use over-large numbers if the buffer were large. The
5974 term `overflow', mentioned in the comment, means numbers that are over
5975 large. Version 21 Emacs uses larger numbers, but this code has not
5976 been touched, if only because people now look at buffers that are far,
5977 far larger than ever before.
5979 There are two cases: if the buffer is large and if it is not.
5981 @node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg
5982 @comment node-name, next, previous, up
5983 @unnumberedsubsubsec What happens in a large buffer
5985 In @code{beginning-of-buffer}, the inner @code{if} expression tests
5986 whether the size of the buffer is greater than 10,000 characters. To do
5987 this, it uses the @code{>} function and the @code{buffer-size} function.
5990 The line looks like this:
5993 (if (> (buffer-size) 10000)
5998 When the buffer is large, the then-part of the @code{if} expression is
5999 evaluated. It reads like this (after formatting for easy reading):
6004 (prefix-numeric-value arg)
6005 (/ (buffer-size) 10))
6010 This expression is a multiplication, with two arguments to the function
6013 The first argument is @code{(prefix-numeric-value arg)}. When
6014 @code{"P"} is used as the argument for @code{interactive}, the value
6015 passed to the function as its argument is passed a ``raw prefix
6016 argument'', and not a number. (It is a number in a list.) To perform
6017 the arithmetic, a conversion is necessary, and
6018 @code{prefix-numeric-value} does the job.
6020 @findex / @r{(division)}
6022 The second argument is @code{(/ (buffer-size) 10)}. This expression
6023 divides the numeric value of the buffer by ten. This produces a number
6024 that tells how many characters make up one tenth of the buffer size.
6025 (In Lisp, @code{/} is used for division, just as @code{*} is
6026 used for multiplication.)
6029 In the multiplication expression as a whole, this amount is multiplied
6030 by the value of the prefix argument---the multiplication looks like this:
6034 (* @var{numeric-value-of-prefix-arg}
6035 @var{number-of-characters-in-one-tenth-of-the-buffer})
6040 If, for example, the prefix argument is @samp{7}, the one-tenth value
6041 will be multiplied by 7 to give a position 70% of the way through the
6045 The result of all this is that if the buffer is large, the
6046 @code{goto-char} expression reads like this:
6050 (goto-char (* (prefix-numeric-value arg)
6051 (/ (buffer-size) 10)))
6055 This puts the cursor where we want it.
6057 @node Small buffer case, , Large buffer case, beginning-of-buffer opt arg
6058 @comment node-name, next, previous, up
6059 @unnumberedsubsubsec What happens in a small buffer
6061 If the buffer contains fewer than 10,000 characters, a slightly
6062 different computation is performed. You might think this is not
6063 necessary, since the first computation could do the job. However, in
6064 a small buffer, the first method may not put the cursor on exactly the
6065 desired line; the second method does a better job.
6068 The code looks like this:
6070 @c Keep this on one line.
6072 (/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10))
6077 This is code in which you figure out what happens by discovering how the
6078 functions are embedded in parentheses. It is easier to read if you
6079 reformat it with each expression indented more deeply than its
6080 enclosing expression:
6088 (prefix-numeric-value arg)))
6095 Looking at parentheses, we see that the innermost operation is
6096 @code{(prefix-numeric-value arg)}, which converts the raw argument to a
6097 number. This number is multiplied by the buffer size in the following
6101 (* (buffer-size) (prefix-numeric-value arg))
6105 This multiplication creates a number that may be larger than the size of
6106 the buffer---seven times larger if the argument is 7, for example. Ten
6107 is then added to this number and finally the large number is divided by
6108 ten to provide a value that is one character larger than the percentage
6109 position in the buffer.
6111 The number that results from all this is passed to @code{goto-char} and
6112 the cursor is moved to that point.
6115 @node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer
6116 @comment node-name, next, previous, up
6117 @subsection The Complete @code{beginning-of-buffer}
6120 Here is the complete text of the @code{beginning-of-buffer} function:
6125 (defun beginning-of-buffer (&optional arg)
6126 "Move point to the beginning of the buffer;
6127 leave mark at previous position.
6128 With arg N, put point N/10 of the way
6129 from the true beginning.
6132 Don't use this in Lisp programs!
6133 \(goto-char (point-min)) is faster
6134 and does not set the mark."
6141 (if (> (buffer-size) 10000)
6142 ;; @r{Avoid overflow for large buffer sizes!}
6143 (* (prefix-numeric-value arg)
6144 (/ (buffer-size) 10))
6147 (/ (+ 10 (* (buffer-size)
6148 (prefix-numeric-value arg)))
6151 (if arg (forward-line 1)))
6156 Except for two small points, the previous discussion shows how this
6157 function works. The first point deals with a detail in the
6158 documentation string, and the second point concerns the last line of
6162 In the documentation string, there is reference to an expression:
6165 \(goto-char (point-min))
6169 A @samp{\} is used before the first parenthesis of this expression.
6170 This @samp{\} tells the Lisp interpreter that the expression should be
6171 printed as shown in the documentation rather than evaluated as a
6172 symbolic expression, which is what it looks like.
6175 Finally, the last line of the @code{beginning-of-buffer} command says to
6176 move point to the beginning of the next line if the command is
6177 invoked with an argument:
6180 (if arg (forward-line 1)))
6184 This puts the cursor at the beginning of the first line after the
6185 appropriate tenths position in the buffer. This is a flourish that
6186 means that the cursor is always located @emph{at least} the requested
6187 tenths of the way through the buffer, which is a nicety that is,
6188 perhaps, not necessary, but which, if it did not occur, would be sure to
6191 @node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
6192 @comment node-name, next, previous, up
6195 Here is a brief summary of some of the topics covered in this chapter.
6199 Evaluate each argument in sequence, and return the value of the first
6200 argument that is not @code{nil}; if none return a value that is not
6201 @code{nil}, return @code{nil}. In brief, return the first true value
6202 of the arguments; return a true value if one @emph{or} any of the
6206 Evaluate each argument in sequence, and if any are @code{nil}, return
6207 @code{nil}; if none are @code{nil}, return the value of the last
6208 argument. In brief, return a true value only if all the arguments are
6209 true; return a true value if one @emph{and} each of the others is
6213 A keyword used to indicate that an argument to a function definition
6214 is optional; this means that the function can be evaluated without the
6215 argument, if desired.
6217 @item prefix-numeric-value
6218 Convert the `raw prefix argument' produced by @code{(interactive
6219 "P")} to a numeric value.
6222 Move point forward to the beginning of the next line, or if the argument
6223 is greater than one, forward that many lines. If it can't move as far
6224 forward as it is supposed to, @code{forward-line} goes forward as far as
6225 it can and then returns a count of the number of additional lines it was
6226 supposed to move but couldn't.
6229 Delete the entire contents of the current buffer.
6232 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
6235 @node optional Exercise, , Second Buffer Related Review, More Complex
6236 @section @code{optional} Argument Exercise
6238 Write an interactive function with an optional argument that tests
6239 whether its argument, a number, is greater than or equal to, or else,
6240 less than the value of @code{fill-column}, and tells you which, in a
6241 message. However, if you do not pass an argument to the function, use
6242 56 as a default value.
6244 @node Narrowing & Widening, car cdr & cons, More Complex, Top
6245 @comment node-name, next, previous, up
6246 @chapter Narrowing and Widening
6247 @cindex Focusing attention (narrowing)
6251 Narrowing is a feature of Emacs that makes it possible for you to focus
6252 on a specific part of a buffer, and work without accidentally changing
6253 other parts. Narrowing is normally disabled since it can confuse
6257 * Narrowing advantages:: The advantages of narrowing
6258 * save-restriction:: The @code{save-restriction} special form.
6259 * what-line:: The number of the line that point is on.
6263 @node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
6265 @unnumberedsec The Advantages of Narrowing
6268 With narrowing, the rest of a buffer is made invisible, as if it weren't
6269 there. This is an advantage if, for example, you want to replace a word
6270 in one part of a buffer but not in another: you narrow to the part you want
6271 and the replacement is carried out only in that section, not in the rest
6272 of the buffer. Searches will only work within a narrowed region, not
6273 outside of one, so if you are fixing a part of a document, you can keep
6274 yourself from accidentally finding parts you do not need to fix by
6275 narrowing just to the region you want.
6276 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
6278 However, narrowing does make the rest of the buffer invisible, which
6279 can scare people who inadvertently invoke narrowing and think they
6280 have deleted a part of their file. Moreover, the @code{undo} command
6281 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
6282 (nor should it), so people can become quite desperate if they do not
6283 know that they can return the rest of a buffer to visibility with the
6284 @code{widen} command.
6285 (The key binding for @code{widen} is @kbd{C-x n w}.)
6287 Narrowing is just as useful to the Lisp interpreter as to a human.
6288 Often, an Emacs Lisp function is designed to work on just part of a
6289 buffer; or conversely, an Emacs Lisp function needs to work on all of a
6290 buffer that has been narrowed. The @code{what-line} function, for
6291 example, removes the narrowing from a buffer, if it has any narrowing
6292 and when it has finished its job, restores the narrowing to what it was.
6293 On the other hand, the @code{count-lines} function, which is called by
6294 @code{what-line}, uses narrowing to restrict itself to just that portion
6295 of the buffer in which it is interested and then restores the previous
6298 @node save-restriction, what-line, Narrowing advantages, Narrowing & Widening
6299 @comment node-name, next, previous, up
6300 @section The @code{save-restriction} Special Form
6301 @findex save-restriction
6303 In Emacs Lisp, you can use the @code{save-restriction} special form to
6304 keep track of whatever narrowing is in effect, if any. When the Lisp
6305 interpreter meets with @code{save-restriction}, it executes the code
6306 in the body of the @code{save-restriction} expression, and then undoes
6307 any changes to narrowing that the code caused. If, for example, the
6308 buffer is narrowed and the code that follows @code{save-restriction}
6309 gets rid of the narrowing, @code{save-restriction} returns the buffer
6310 to its narrowed region afterwards. In the @code{what-line} command,
6311 any narrowing the buffer may have is undone by the @code{widen}
6312 command that immediately follows the @code{save-restriction} command.
6313 Any original narrowing is restored just before the completion of the
6317 The template for a @code{save-restriction} expression is simple:
6327 The body of the @code{save-restriction} is one or more expressions that
6328 will be evaluated in sequence by the Lisp interpreter.
6330 Finally, a point to note: when you use both @code{save-excursion} and
6331 @code{save-restriction}, one right after the other, you should use
6332 @code{save-excursion} outermost. If you write them in reverse order,
6333 you may fail to record narrowing in the buffer to which Emacs switches
6334 after calling @code{save-excursion}. Thus, when written together,
6335 @code{save-excursion} and @code{save-restriction} should be written
6346 In other circumstances, when not written together, the
6347 @code{save-excursion} and @code{save-restriction} special forms must
6348 be written in the order appropriate to the function.
6362 @node what-line, narrow Exercise, save-restriction, Narrowing & Widening
6363 @comment node-name, next, previous, up
6364 @section @code{what-line}
6366 @cindex Widening, example of
6368 The @code{what-line} command tells you the number of the line in which
6369 the cursor is located. The function illustrates the use of the
6370 @code{save-restriction} and @code{save-excursion} commands. Here is the
6371 original text of the function:
6376 "Print the current line number (in the buffer) of point."
6383 (1+ (count-lines 1 (point)))))))
6387 (In recent versions of GNU Emacs, the @code{what-line} function has
6388 been expanded to tell you your line number in a narrowed buffer as
6389 well as your line number in a widened buffer. The recent version is
6390 more complex than the version shown here. If you feel adventurous,
6391 you might want to look at it after figuring out how this version
6392 works. The newer version uses a conditional to determine whether the
6393 buffer has been narrowed, and rather than use @code{beginning-of-line}
6394 to move point to the beginning of the current line, if need be, the
6395 function uses @code{(forward-line 0)}.)
6397 The function as shown here has a documentation line and is
6398 interactive, as you would expect. The next two lines use the
6399 functions @code{save-restriction} and @code{widen}.
6401 The @code{save-restriction} special form notes whatever narrowing is in
6402 effect, if any, in the current buffer and restores that narrowing after
6403 the code in the body of the @code{save-restriction} has been evaluated.
6405 The @code{save-restriction} special form is followed by @code{widen}.
6406 This function undoes any narrowing the current buffer may have had
6407 when @code{what-line} was called. (The narrowing that was there is
6408 the narrowing that @code{save-restriction} remembers.) This widening
6409 makes it possible for the line counting commands to count from the
6410 beginning of the buffer. Otherwise, they would have been limited to
6411 counting within the accessible region. Any original narrowing is
6412 restored just before the completion of the function by the
6413 @code{save-restriction} special form.
6415 The call to @code{widen} is followed by @code{save-excursion}, which
6416 saves the location of the cursor (i.e., of point) and of the mark, and
6417 restores them after the code in the body of the @code{save-excursion}
6418 uses the @code{beginning-of-line} function to move point.
6420 (Note that the @code{(widen)} expression comes between the
6421 @code{save-restriction} and @code{save-excursion} special forms. When
6422 you write the two @code{save- @dots{}} expressions in sequence, write
6423 @code{save-excursion} outermost.)
6426 The last two lines of the @code{what-line} function are functions to
6427 count the number of lines in the buffer and then print the number in the
6433 (1+ (count-lines 1 (point)))))))
6437 The @code{message} function prints a one-line message at the bottom of the
6438 Emacs screen. The first argument is inside of quotation marks and is
6439 printed as a string of characters. However, it may contain @samp{%d},
6440 @samp{%s}, or @samp{%c} to print arguments that follow the string.
6441 @samp{%d} prints the argument as a decimal, so the message will say
6442 something such as @samp{Line 243}.
6446 The number that is printed in place of the @samp{%d} is computed by the
6447 last line of the function:
6450 (1+ (count-lines 1 (point)))
6454 What this does is count the lines from the first position of the
6455 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
6456 one to that number. (The @code{1+} function adds one to its
6457 argument.) We add one to it because line 2 has only one line before
6458 it, and @code{count-lines} counts only the lines @emph{before} the
6461 After @code{count-lines} has done its job, and the message has been
6462 printed in the echo area, the @code{save-excursion} restores point and
6463 mark to their original positions; and @code{save-restriction} restores
6464 the original narrowing, if any.
6466 @node narrow Exercise, , what-line, Narrowing & Widening
6467 @section Exercise with Narrowing
6469 Write a function that will display the first 60 characters of the
6470 current buffer, even if you have narrowed the buffer to its latter
6471 half so that the first line is inaccessible. Restore point, mark, and
6472 narrowing. For this exercise, you need to use a whole potpourri of
6473 functions, including @code{save-restriction}, @code{widen},
6474 @code{goto-char}, @code{point-min}, @code{message}, and
6475 @code{buffer-substring}.
6477 @cindex Properties, mention of @code{buffer-substring-no-properties}
6478 (@code{buffer-substring} is a previously unmentioned function you will
6479 have to investigate yourself; or perhaps you will have to use
6480 @code{buffer-substring-no-properties} @dots{}, yet another function
6481 and one that introduces text properties, a feature otherwise not
6482 discussed here. @xref{Text Properties, , Text Properties, elisp, The
6483 GNU Emacs Lisp Reference Manual}. Additionally, do you really need
6484 @code{goto-char} or @code{point-min}? Or can you write the function
6487 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
6488 @comment node-name, next, previous, up
6489 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
6490 @findex car, @r{introduced}
6491 @findex cdr, @r{introduced}
6493 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
6494 functions. The @code{cons} function is used to construct lists, and
6495 the @code{car} and @code{cdr} functions are used to take them apart.
6497 In the walk through of the @code{copy-region-as-kill} function, we
6498 will see @code{cons} as well as two variants on @code{cdr},
6499 namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
6502 * Strange Names:: An historical aside: why the strange names?
6503 * car & cdr:: Functions for extracting part of a list.
6504 * cons:: Constructing a list.
6505 * nthcdr:: Calling @code{cdr} repeatedly.
6507 * setcar:: Changing the first element of a list.
6508 * setcdr:: Changing the rest of a list.
6512 @node Strange Names, car & cdr, car cdr & cons, car cdr & cons
6514 @unnumberedsec Strange Names
6517 The name of the @code{cons} function is not unreasonable: it is an
6518 abbreviation of the word `construct'. The origins of the names for
6519 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
6520 is an acronym from the phrase `Contents of the Address part of the
6521 Register'; and @code{cdr} (pronounced `could-er') is an acronym from
6522 the phrase `Contents of the Decrement part of the Register'. These
6523 phrases refer to specific pieces of hardware on the very early
6524 computer on which the original Lisp was developed. Besides being
6525 obsolete, the phrases have been completely irrelevant for more than 25
6526 years to anyone thinking about Lisp. Nonetheless, although a few
6527 brave scholars have begun to use more reasonable names for these
6528 functions, the old terms are still in use. In particular, since the
6529 terms are used in the Emacs Lisp source code, we will use them in this
6532 @node car & cdr, cons, Strange Names, car cdr & cons
6533 @comment node-name, next, previous, up
6534 @section @code{car} and @code{cdr}
6536 The @sc{car} of a list is, quite simply, the first item in the list.
6537 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
6541 If you are reading this in Info in GNU Emacs, you can see this by
6542 evaluating the following:
6545 (car '(rose violet daisy buttercup))
6549 After evaluating the expression, @code{rose} will appear in the echo
6552 Clearly, a more reasonable name for the @code{car} function would be
6553 @code{first} and this is often suggested.
6555 @code{car} does not remove the first item from the list; it only reports
6556 what it is. After @code{car} has been applied to a list, the list is
6557 still the same as it was. In the jargon, @code{car} is
6558 `non-destructive'. This feature turns out to be important.
6560 The @sc{cdr} of a list is the rest of the list, that is, the
6561 @code{cdr} function returns the part of the list that follows the
6562 first item. Thus, while the @sc{car} of the list @code{'(rose violet
6563 daisy buttercup)} is @code{rose}, the rest of the list, the value
6564 returned by the @code{cdr} function, is @code{(violet daisy
6568 You can see this by evaluating the following in the usual way:
6571 (cdr '(rose violet daisy buttercup))
6575 When you evaluate this, @code{(violet daisy buttercup)} will appear in
6578 Like @code{car}, @code{cdr} does not remove any elements from the
6579 list---it just returns a report of what the second and subsequent
6582 Incidentally, in the example, the list of flowers is quoted. If it were
6583 not, the Lisp interpreter would try to evaluate the list by calling
6584 @code{rose} as a function. In this example, we do not want to do that.
6586 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
6588 (There is a lesson here: when you name new functions, consider very
6589 carefully what you are doing, since you may be stuck with the names
6590 for far longer than you expect. The reason this document perpetuates
6591 these names is that the Emacs Lisp source code uses them, and if I did
6592 not use them, you would have a hard time reading the code; but do,
6593 please, try to avoid using these terms yourself. The people who come
6594 after you will be grateful to you.)
6596 When @code{car} and @code{cdr} are applied to a list made up of symbols,
6597 such as the list @code{(pine fir oak maple)}, the element of the list
6598 returned by the function @code{car} is the symbol @code{pine} without
6599 any parentheses around it. @code{pine} is the first element in the
6600 list. However, the @sc{cdr} of the list is a list itself, @code{(fir
6601 oak maple)}, as you can see by evaluating the following expressions in
6606 (car '(pine fir oak maple))
6608 (cdr '(pine fir oak maple))
6612 On the other hand, in a list of lists, the first element is itself a
6613 list. @code{car} returns this first element as a list. For example,
6614 the following list contains three sub-lists, a list of carnivores, a
6615 list of herbivores and a list of sea mammals:
6619 (car '((lion tiger cheetah)
6620 (gazelle antelope zebra)
6621 (whale dolphin seal)))
6626 In this example, the first element or @sc{car} of the list is the list of
6627 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
6628 @code{((gazelle antelope zebra) (whale dolphin seal))}.
6632 (cdr '((lion tiger cheetah)
6633 (gazelle antelope zebra)
6634 (whale dolphin seal)))
6638 It is worth saying again that @code{car} and @code{cdr} are
6639 non-destructive---that is, they do not modify or change lists to which
6640 they are applied. This is very important for how they are used.
6642 Also, in the first chapter, in the discussion about atoms, I said that
6643 in Lisp, ``certain kinds of atom, such as an array, can be separated
6644 into parts; but the mechanism for doing this is different from the
6645 mechanism for splitting a list. As far as Lisp is concerned, the
6646 atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The
6647 @code{car} and @code{cdr} functions are used for splitting lists and
6648 are considered fundamental to Lisp. Since they cannot split or gain
6649 access to the parts of an array, an array is considered an atom.
6650 Conversely, the other fundamental function, @code{cons}, can put
6651 together or construct a list, but not an array. (Arrays are handled
6652 by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU
6653 Emacs Lisp Reference Manual}.)
6655 @node cons, nthcdr, car & cdr, car cdr & cons
6656 @comment node-name, next, previous, up
6657 @section @code{cons}
6658 @findex cons, @r{introduced}
6660 The @code{cons} function constructs lists; it is the inverse of
6661 @code{car} and @code{cdr}. For example, @code{cons} can be used to make
6662 a four element list from the three element list, @code{(fir oak maple)}:
6665 (cons 'pine '(fir oak maple))
6670 After evaluating this list, you will see
6673 (pine fir oak maple)
6677 appear in the echo area. @code{cons} causes the creation of a new
6678 list in which the element is followed by the elements of the original
6681 We often say that `@code{cons} puts a new element at the beginning of
6682 a list; it attaches or pushes elements onto the list', but this
6683 phrasing can be misleading, since @code{cons} does not change an
6684 existing list, but creates a new one.
6686 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
6690 * length:: How to find the length of a list.
6693 @node Build a list, length, cons, cons
6695 @unnumberedsubsec Build a list
6698 @code{cons} must have a list to attach to.@footnote{Actually, you can
6699 @code{cons} an element to an atom to produce a dotted pair. Dotted
6700 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
6701 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You
6702 cannot start from absolutely nothing. If you are building a list, you
6703 need to provide at least an empty list at the beginning. Here is a
6704 series of @code{cons} expressions that build up a list of flowers. If
6705 you are reading this in Info in GNU Emacs, you can evaluate each of
6706 the expressions in the usual way; the value is printed in this text
6707 after @samp{@result{}}, which you may read as `evaluates to'.
6711 (cons 'buttercup ())
6712 @result{} (buttercup)
6716 (cons 'daisy '(buttercup))
6717 @result{} (daisy buttercup)
6721 (cons 'violet '(daisy buttercup))
6722 @result{} (violet daisy buttercup)
6726 (cons 'rose '(violet daisy buttercup))
6727 @result{} (rose violet daisy buttercup)
6732 In the first example, the empty list is shown as @code{()} and a list
6733 made up of @code{buttercup} followed by the empty list is constructed.
6734 As you can see, the empty list is not shown in the list that was
6735 constructed. All that you see is @code{(buttercup)}. The empty list is
6736 not counted as an element of a list because there is nothing in an empty
6737 list. Generally speaking, an empty list is invisible.
6739 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
6740 two element list by putting @code{daisy} in front of @code{buttercup};
6741 and the third example constructs a three element list by putting
6742 @code{violet} in front of @code{daisy} and @code{buttercup}.
6744 @node length, , Build a list, cons
6745 @comment node-name, next, previous, up
6746 @subsection Find the Length of a List: @code{length}
6749 You can find out how many elements there are in a list by using the Lisp
6750 function @code{length}, as in the following examples:
6754 (length '(buttercup))
6759 (length '(daisy buttercup))
6764 (length (cons 'violet '(daisy buttercup)))
6770 In the third example, the @code{cons} function is used to construct a
6771 three element list which is then passed to the @code{length} function as
6775 We can also use @code{length} to count the number of elements in an
6786 As you would expect, the number of elements in an empty list is zero.
6788 An interesting experiment is to find out what happens if you try to find
6789 the length of no list at all; that is, if you try to call @code{length}
6790 without giving it an argument, not even an empty list:
6798 What you see, if you evaluate this, is the error message
6801 Wrong number of arguments: #<subr length>, 0
6805 This means that the function receives the wrong number of
6806 arguments, zero, when it expects some other number of arguments. In
6807 this case, one argument is expected, the argument being a list whose
6808 length the function is measuring. (Note that @emph{one} list is
6809 @emph{one} argument, even if the list has many elements inside it.)
6811 The part of the error message that says @samp{#<subr length>} is the
6812 name of the function. This is written with a special notation,
6813 @samp{#<subr}, that indicates that the function @code{length} is one
6814 of the primitive functions written in C rather than in Emacs Lisp.
6815 (@samp{subr} is an abbreviation for `subroutine'.) @xref{What Is a
6816 Function, , What Is a Function?, elisp , The GNU Emacs Lisp Reference
6817 Manual}, for more about subroutines.
6819 @node nthcdr, nth, cons, car cdr & cons
6820 @comment node-name, next, previous, up
6821 @section @code{nthcdr}
6824 The @code{nthcdr} function is associated with the @code{cdr} function.
6825 What it does is take the @sc{cdr} of a list repeatedly.
6827 If you take the @sc{cdr} of the list @code{(pine fir
6828 oak maple)}, you will be returned the list @code{(fir oak maple)}. If you
6829 repeat this on what was returned, you will be returned the list
6830 @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original
6831 list will just give you the original @sc{cdr} since the function does
6832 not change the list. You need to evaluate the @sc{cdr} of the
6833 @sc{cdr} and so on.) If you continue this, eventually you will be
6834 returned an empty list, which in this case, instead of being shown as
6835 @code{()} is shown as @code{nil}.
6838 For review, here is a series of repeated @sc{cdr}s, the text following
6839 the @samp{@result{}} shows what is returned.
6843 (cdr '(pine fir oak maple))
6844 @result{}(fir oak maple)
6848 (cdr '(fir oak maple))
6849 @result{} (oak maple)
6874 You can also do several @sc{cdr}s without printing the values in
6879 (cdr (cdr '(pine fir oak maple)))
6880 @result{} (oak maple)
6885 In this example, the Lisp interpreter evaluates the innermost list first.
6886 The innermost list is quoted, so it just passes the list as it is to the
6887 innermost @code{cdr}. This @code{cdr} passes a list made up of the
6888 second and subsequent elements of the list to the outermost @code{cdr},
6889 which produces a list composed of the third and subsequent elements of
6890 the original list. In this example, the @code{cdr} function is repeated
6891 and returns a list that consists of the original list without its
6894 The @code{nthcdr} function does the same as repeating the call to
6895 @code{cdr}. In the following example, the argument 2 is passed to the
6896 function @code{nthcdr}, along with the list, and the value returned is
6897 the list without its first two items, which is exactly the same
6898 as repeating @code{cdr} twice on the list:
6902 (nthcdr 2 '(pine fir oak maple))
6903 @result{} (oak maple)
6908 Using the original four element list, we can see what happens when
6909 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
6914 ;; @r{Leave the list as it was.}
6915 (nthcdr 0 '(pine fir oak maple))
6916 @result{} (pine fir oak maple)
6920 ;; @r{Return a copy without the first element.}
6921 (nthcdr 1 '(pine fir oak maple))
6922 @result{} (fir oak maple)
6926 ;; @r{Return a copy of the list without three elements.}
6927 (nthcdr 3 '(pine fir oak maple))
6932 ;; @r{Return a copy lacking all four elements.}
6933 (nthcdr 4 '(pine fir oak maple))
6938 ;; @r{Return a copy lacking all elements.}
6939 (nthcdr 5 '(pine fir oak maple))
6944 @node nth, setcar, nthcdr, car cdr & cons
6945 @comment node-name, next, previous, up
6949 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
6950 The @code{nth} function takes the @sc{car} of the result returned by
6951 @code{nthcdr}. It returns the Nth element of the list.
6954 Thus, if it were not defined in C for speed, the definition of
6955 @code{nth} would be:
6960 "Returns the Nth element of LIST.
6961 N counts from zero. If LIST is not that long, nil is returned."
6962 (car (nthcdr n list)))
6967 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
6968 but its definition was redone in C in the 1980s.)
6970 The @code{nth} function returns a single element of a list.
6971 This can be very convenient.
6973 Note that the elements are numbered from zero, not one. That is to
6974 say, the first element of a list, its @sc{car} is the zeroth element.
6975 This is called `zero-based' counting and often bothers people who
6976 are accustomed to the first element in a list being number one, which
6984 (nth 0 '("one" "two" "three"))
6987 (nth 1 '("one" "two" "three"))
6992 It is worth mentioning that @code{nth}, like @code{nthcdr} and
6993 @code{cdr}, does not change the original list---the function is
6994 non-destructive. This is in sharp contrast to the @code{setcar} and
6995 @code{setcdr} functions.
6997 @node setcar, setcdr, nth, car cdr & cons
6998 @comment node-name, next, previous, up
6999 @section @code{setcar}
7002 As you might guess from their names, the @code{setcar} and @code{setcdr}
7003 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
7004 They actually change the original list, unlike @code{car} and @code{cdr}
7005 which leave the original list as it was. One way to find out how this
7006 works is to experiment. We will start with the @code{setcar} function.
7009 First, we can make a list and then set the value of a variable to the
7010 list, using the @code{setq} function. Here is a list of animals:
7013 (setq animals '(antelope giraffe lion tiger))
7017 If you are reading this in Info inside of GNU Emacs, you can evaluate
7018 this expression in the usual fashion, by positioning the cursor after
7019 the expression and typing @kbd{C-x C-e}. (I'm doing this right here as
7020 I write this. This is one of the advantages of having the interpreter
7021 built into the computing environment.)
7024 When we evaluate the variable @code{animals}, we see that it is bound to
7025 the list @code{(antelope giraffe lion tiger)}:
7030 @result{} (antelope giraffe lion tiger)
7035 Put another way, the variable @code{animals} points to the list
7036 @code{(antelope giraffe lion tiger)}.
7038 Next, evaluate the function @code{setcar} while passing it two
7039 arguments, the variable @code{animals} and the quoted symbol
7040 @code{hippopotamus}; this is done by writing the three element list
7041 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
7045 (setcar animals 'hippopotamus)
7050 After evaluating this expression, evaluate the variable @code{animals}
7051 again. You will see that the list of animals has changed:
7056 @result{} (hippopotamus giraffe lion tiger)
7061 The first element on the list, @code{antelope} is replaced by
7062 @code{hippopotamus}.
7064 So we can see that @code{setcar} did not add a new element to the list
7065 as @code{cons} would have; it replaced @code{antelope} with
7066 @code{hippopotamus}; it @emph{changed} the list.
7068 @node setcdr, cons Exercise, setcar, car cdr & cons
7069 @comment node-name, next, previous, up
7070 @section @code{setcdr}
7073 The @code{setcdr} function is similar to the @code{setcar} function,
7074 except that the function replaces the second and subsequent elements of
7075 a list rather than the first element.
7077 (To see how to change the last element of a list, look ahead to
7078 @ref{kill-new function, , The @code{kill-new} function}, which uses
7079 the @code{nthcdr} and @code{setcdr} functions.)
7082 To see how this works, set the value of the variable to a list of
7083 domesticated animals by evaluating the following expression:
7086 (setq domesticated-animals '(horse cow sheep goat))
7091 If you now evaluate the list, you will be returned the list
7092 @code{(horse cow sheep goat)}:
7096 domesticated-animals
7097 @result{} (horse cow sheep goat)
7102 Next, evaluate @code{setcdr} with two arguments, the name of the
7103 variable which has a list as its value, and the list to which the
7104 @sc{cdr} of the first list will be set;
7107 (setcdr domesticated-animals '(cat dog))
7111 If you evaluate this expression, the list @code{(cat dog)} will appear
7112 in the echo area. This is the value returned by the function. The
7113 result we are interested in is the ``side effect'', which we can see by
7114 evaluating the variable @code{domesticated-animals}:
7118 domesticated-animals
7119 @result{} (horse cat dog)
7124 Indeed, the list is changed from @code{(horse cow sheep goat)} to
7125 @code{(horse cat dog)}. The @sc{cdr} of the list is changed from
7126 @code{(cow sheep goat)} to @code{(cat dog)}.
7128 @node cons Exercise, , setcdr, car cdr & cons
7131 Construct a list of four birds by evaluating several expressions with
7132 @code{cons}. Find out what happens when you @code{cons} a list onto
7133 itself. Replace the first element of the list of four birds with a
7134 fish. Replace the rest of that list with a list of other fish.
7136 @node Cutting & Storing Text, List Implementation, car cdr & cons, Top
7137 @comment node-name, next, previous, up
7138 @chapter Cutting and Storing Text
7139 @cindex Cutting and storing text
7140 @cindex Storing and cutting text
7141 @cindex Killing text
7142 @cindex Clipping text
7143 @cindex Erasing text
7144 @cindex Deleting text
7146 Whenever you cut or clip text out of a buffer with a `kill' command in
7147 GNU Emacs, it is stored in a list and you can bring it back with a
7150 (The use of the word `kill' in Emacs for processes which specifically
7151 @emph{do not} destroy the values of the entities is an unfortunate
7152 historical accident. A much more appropriate word would be `clip' since
7153 that is what the kill commands do; they clip text out of a buffer and
7154 put it into storage from which it can be brought back. I have often
7155 been tempted to replace globally all occurrences of `kill' in the Emacs
7156 sources with `clip' and all occurrences of `killed' with `clipped'.)
7159 * Storing Text:: Text is stored in a list.
7160 * zap-to-char:: Cutting out text up to a character.
7161 * kill-region:: Cutting text out of a region.
7162 * Digression into C:: Minor note on C programming language macros.
7163 * defvar:: How to give a variable an initial value.
7164 * copy-region-as-kill:: A definition for copying text.
7165 * cons & search-fwd Review::
7166 * search Exercises::
7169 @node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text
7171 @unnumberedsec Storing Text in a List
7174 When text is cut out of a buffer, it is stored on a list. Successive
7175 pieces of text are stored on the list successively, so the list might
7179 ("a piece of text" "previous piece")
7184 The function @code{cons} can be used to to create a new list from a
7185 piece of text (an `atom', to use the jargon) and an existing list,
7190 (cons "another piece"
7191 '("a piece of text" "previous piece"))
7197 If you evaluate this expression, a list of three elements will appear in
7201 ("another piece" "a piece of text" "previous piece")
7204 With the @code{car} and @code{nthcdr} functions, you can retrieve
7205 whichever piece of text you want. For example, in the following code,
7206 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
7207 and the @code{car} returns the first element of that remainder---the
7208 second element of the original list:
7212 (car (nthcdr 1 '("another piece"
7215 @result{} "a piece of text"
7219 The actual functions in Emacs are more complex than this, of course.
7220 The code for cutting and retrieving text has to be written so that
7221 Emacs can figure out which element in the list you want---the first,
7222 second, third, or whatever. In addition, when you get to the end of
7223 the list, Emacs should give you the first element of the list, rather
7224 than nothing at all.
7226 The list that holds the pieces of text is called the @dfn{kill ring}.
7227 This chapter leads up to a description of the kill ring and how it is
7228 used by first tracing how the @code{zap-to-char} function works. This
7229 function uses (or `calls') a function that invokes a function that
7230 manipulates the kill ring. Thus, before reaching the mountains, we
7231 climb the foothills.
7233 A subsequent chapter describes how text that is cut from the buffer is
7234 retrieved. @xref{Yanking, , Yanking Text Back}.
7236 @node zap-to-char, kill-region, Storing Text, Cutting & Storing Text
7237 @comment node-name, next, previous, up
7238 @section @code{zap-to-char}
7241 The @code{zap-to-char} function barely changed between GNU Emacs
7242 version 19 and GNU Emacs version 21. However, @code{zap-to-char}
7243 calls another function, @code{kill-region}, which enjoyed a major rewrite
7244 on the way to version 21.
7246 The @code{kill-region} function in Emacs 19 is complex, but does not
7247 use code that is important at this time. We will skip it.
7249 The @code{kill-region} function in Emacs 21 is easier to read than the
7250 same function in Emacs 19 and introduces a very important concept,
7251 that of error handling. We will walk through the function.
7253 But first, let us look at the interactive @code{zap-to-char} function.
7256 * Complete zap-to-char:: The complete implementation.
7257 * zap-to-char interactive:: A three part interactive expression.
7258 * zap-to-char body:: A short overview.
7259 * search-forward:: How to search for a string.
7260 * progn:: The @code{progn} special form.
7261 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
7264 @node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
7266 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
7269 The GNU Emacs version 19 and version 21 implementations of the
7270 @code{zap-to-char} function are nearly identical in form, and they
7271 work alike. The function removes the text in the region between the
7272 location of the cursor (i.e., of point) up to and including the next
7273 occurrence of a specified character. The text that @code{zap-to-char}
7274 removes is put in the kill ring; and it can be retrieved from the kill
7275 ring by typing @kbd{C-y} (@code{yank}). If the command is given an
7276 argument, it removes text through that number of occurrences. Thus,
7277 if the cursor were at the beginning of this sentence and the character
7278 were @samp{s}, @samp{Thus} would be removed. If the argument were
7279 two, @samp{Thus, if the curs} would be removed, up to and including
7280 the @samp{s} in @samp{cursor}.
7282 If the specified character is not found, @code{zap-to-char} will say
7283 ``Search failed'', tell you the character you typed, and not remove
7286 In order to determine how much text to remove, @code{zap-to-char} uses
7287 a search function. Searches are used extensively in code that
7288 manipulates text, and we will focus attention on them as well as on the
7292 Here is the complete text of the version 19 implementation of the function:
7297 (defun zap-to-char (arg char) ; version 19 implementation
7298 "Kill up to and including ARG'th occurrence of CHAR.
7299 Goes backward if ARG is negative; error if CHAR not found."
7300 (interactive "*p\ncZap to char: ")
7301 (kill-region (point)
7304 (char-to-string char) nil nil arg)
7309 @node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char
7310 @comment node-name, next, previous, up
7311 @subsection The @code{interactive} Expression
7314 The interactive expression in the @code{zap-to-char} command looks like
7318 (interactive "*p\ncZap to char: ")
7321 The part within quotation marks, @code{"*p\ncZap to char:@: "}, specifies
7322 three different things. First, and most simply, the asterisk, @samp{*},
7323 causes an error to be signaled if the buffer is read-only. This means that
7324 if you try @code{zap-to-char} in a read-only buffer you will not be able to
7325 remove text, and you will receive a message that says ``Buffer is
7326 read-only''; your terminal may beep at you as well.
7328 The version 21 implementation does not have the asterisk, @samp{*}. The
7329 function works the same as in version 19: in both cases, it cannot
7330 remove text from a read-only buffer but the function does copy the
7331 text that would have been removed to the kill ring. Also, in both
7332 cases, you see an error message.
7334 However, the version 19 implementation copies text from a read-only
7335 buffer only because of a mistake in the implementation of
7336 @code{interactive}. According to the documentation for
7337 @code{interactive}, the asterisk, @samp{*}, should prevent the
7338 @code{zap-to-char} function from doing anything at all when the buffer
7339 is read only. In version 19, the function should not copy the text to
7340 the kill ring. It is a bug that it does.
7342 In version 21, the function is designed to copy the text to the kill
7343 ring; moreover, @code{interactive} is implemented correctly. So the
7344 asterisk, @samp{*}, had to be removed from the interactive
7345 specification. However, if you insert an @samp{*} yourself and
7346 evaluate the function definition, then the next time you run the
7347 @code{zap-to-char} function on a read-only buffer, you will not copy
7350 That change aside, and a change to the documentation, the two versions
7351 of the @code{zap-to-char} function are identical.
7353 Let us continue with the interactive specification.
7355 The second part of @code{"*p\ncZap to char:@: "} is the @samp{p}.
7356 This part is separated from the next part by a newline, @samp{\n}.
7357 The @samp{p} means that the first argument to the function will be
7358 passed the value of a `processed prefix'. The prefix argument is
7359 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If
7360 the function is called interactively without a prefix, 1 is passed to
7363 The third part of @code{"*p\ncZap to char:@: "} is @samp{cZap to char:@:
7364 }. In this part, the lower case @samp{c} indicates that
7365 @code{interactive} expects a prompt and that the argument will be a
7366 character. The prompt follows the @samp{c} and is the string @samp{Zap
7367 to char:@: } (with a space after the colon to make it look good).
7369 What all this does is prepare the arguments to @code{zap-to-char} so they
7370 are of the right type, and give the user a prompt.
7372 @node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
7373 @comment node-name, next, previous, up
7374 @subsection The Body of @code{zap-to-char}
7376 The body of the @code{zap-to-char} function contains the code that
7377 kills (that is, removes) the text in the region from the current
7378 position of the cursor up to and including the specified character.
7379 The first part of the code looks like this:
7382 (kill-region (point) @dots{}
7386 @code{(point)} is the current position of the cursor.
7388 The next part of the code is an expression using @code{progn}. The body
7389 of the @code{progn} consists of calls to @code{search-forward} and
7392 It is easier to understand how @code{progn} works after learning about
7393 @code{search-forward}, so we will look at @code{search-forward} and
7394 then at @code{progn}.
7396 @node search-forward, progn, zap-to-char body, zap-to-char
7397 @comment node-name, next, previous, up
7398 @subsection The @code{search-forward} Function
7399 @findex search-forward
7401 The @code{search-forward} function is used to locate the
7402 zapped-for-character in @code{zap-to-char}. If the search is
7403 successful, @code{search-forward} leaves point immediately after the
7404 last character in the target string. (In @code{zap-to-char}, the
7405 target string is just one character long.) If the search is
7406 backwards, @code{search-forward} leaves point just before the first
7407 character in the target. Also, @code{search-forward} returns @code{t}
7408 for true. (Moving point is therefore a `side effect'.)
7411 In @code{zap-to-char}, the @code{search-forward} function looks like this:
7414 (search-forward (char-to-string char) nil nil arg)
7417 The @code{search-forward} function takes four arguments:
7421 The first argument is the target, what is searched for. This must be a
7422 string, such as @samp{"z"}.
7424 As it happens, the argument passed to @code{zap-to-char} is a single
7425 character. Because of the way computers are built, the Lisp
7426 interpreter may treat a single character as being different from a
7427 string of characters. Inside the computer, a single character has a
7428 different electronic format than a string of one character. (A single
7429 character can often be recorded in the computer using exactly one
7430 byte; but a string may be longer, and the computer needs to be ready
7431 for this.) Since the @code{search-forward} function searches for a
7432 string, the character that the @code{zap-to-char} function receives as
7433 its argument must be converted inside the computer from one format to
7434 the other; otherwise the @code{search-forward} function will fail.
7435 The @code{char-to-string} function is used to make this conversion.
7438 The second argument bounds the search; it is specified as a position in
7439 the buffer. In this case, the search can go to the end of the buffer,
7440 so no bound is set and the second argument is @code{nil}.
7443 The third argument tells the function what it should do if the search
7444 fails---it can signal an error (and print a message) or it can return
7445 @code{nil}. A @code{nil} as the third argument causes the function to
7446 signal an error when the search fails.
7449 The fourth argument to @code{search-forward} is the repeat count---how
7450 many occurrences of the string to look for. This argument is optional
7451 and if the function is called without a repeat count, this argument is
7452 passed the value 1. If this argument is negative, the search goes
7457 In template form, a @code{search-forward} expression looks like this:
7461 (search-forward "@var{target-string}"
7462 @var{limit-of-search}
7463 @var{what-to-do-if-search-fails}
7468 We will look at @code{progn} next.
7470 @node progn, Summing up zap-to-char, search-forward, zap-to-char
7471 @comment node-name, next, previous, up
7472 @subsection The @code{progn} Special Form
7475 @code{progn} is a special form that causes each of its arguments to be
7476 evaluated in sequence and then returns the value of the last one. The
7477 preceding expressions are evaluated only for the side effects they
7478 perform. The values produced by them are discarded.
7481 The template for a @code{progn} expression is very simple:
7490 In @code{zap-to-char}, the @code{progn} expression has to do two things:
7491 put point in exactly the right position; and return the location of
7492 point so that @code{kill-region} will know how far to kill to.
7494 The first argument to the @code{progn} is @code{search-forward}. When
7495 @code{search-forward} finds the string, the function leaves point
7496 immediately after the last character in the target string. (In this
7497 case the target string is just one character long.) If the search is
7498 backwards, @code{search-forward} leaves point just before the first
7499 character in the target. The movement of point is a side effect.
7501 The second and last argument to @code{progn} is the expression
7502 @code{(point)}. This expression returns the value of point, which in
7503 this case will be the location to which it has been moved by
7504 @code{search-forward}. This value is returned by the @code{progn}
7505 expression and is passed to @code{kill-region} as @code{kill-region}'s
7508 @node Summing up zap-to-char, , progn, zap-to-char
7509 @comment node-name, next, previous, up
7510 @subsection Summing up @code{zap-to-char}
7512 Now that we have seen how @code{search-forward} and @code{progn} work,
7513 we can see how the @code{zap-to-char} function works as a whole.
7515 The first argument to @code{kill-region} is the position of the cursor
7516 when the @code{zap-to-char} command is given---the value of point at
7517 that time. Within the @code{progn}, the search function then moves
7518 point to just after the zapped-to-character and @code{point} returns the
7519 value of this location. The @code{kill-region} function puts together
7520 these two values of point, the first one as the beginning of the region
7521 and the second one as the end of the region, and removes the region.
7523 The @code{progn} special form is necessary because the @code{kill-region}
7524 command takes two arguments; and it would fail if @code{search-forward}
7525 and @code{point} expressions were written in sequence as two
7526 additional arguments. The @code{progn} expression is a single argument
7527 to @code{kill-region} and returns the one value that @code{kill-region}
7528 needs for its second argument.
7530 @node kill-region, Digression into C, zap-to-char, Cutting & Storing Text
7531 @comment node-name, next, previous, up
7532 @section @code{kill-region}
7535 The @code{zap-to-char} function uses the @code{kill-region} function.
7536 This function clips text from a region and copies that text to
7537 the kill ring, from which it may be retrieved.
7539 The Emacs 21 version of that function uses @code{condition-case} and
7540 @code{copy-region-as-kill}, both of which we will explain.
7541 @code{condition-case} is an important special form.
7543 In essence, the @code{kill-region} function calls
7544 @code{condition-case}, which takes three arguments. In this function,
7545 the first argument does nothing. The second argument contains the
7546 code that does the work when all goes well. The third argument
7547 contains the code that is called in the event of an error.
7550 * Complete kill-region:: The function definition.
7551 * condition-case:: Dealing with a problem.
7552 * delete-and-extract-region:: Doing the work.
7555 @node Complete kill-region, condition-case, kill-region, kill-region
7557 @unnumberedsubsec The Complete @code{kill-region} Definition
7561 We will go through the @code{condition-case} code in a moment. First,
7562 let us look at the original definition of @code{kill-region}, with
7563 comments added (the newer definition has an optional third argument
7564 and is more complex):
7569 (defun kill-region (beg end)
7570 "Kill between point and mark.
7571 The text is deleted but saved in the kill ring."
7576 ;; 1. `condition-case' takes three arguments.
7577 ;; If the first argument is nil, as it is here,
7578 ;; information about the error signal is not
7579 ;; stored for use by another function.
7584 ;; 2. The second argument to `condition-case'
7585 ;; tells the Lisp interpreter what to do when all goes well.
7589 ;; The `delete-and-extract-region' function usually does the
7590 ;; work. If the beginning and ending of the region are both
7591 ;; the same, then the variable `string' will be empty, or nil
7592 (let ((string (delete-and-extract-region beg end)))
7596 ;; `when' is an `if' clause that cannot take an `else-part'.
7597 ;; Emacs normally sets the value of `last-command' to the
7598 ;; previous command.
7601 ;; `kill-append' concatenates the new string and the old.
7602 ;; `kill-new' inserts text into a new item in the kill ring.
7604 (if (eq last-command 'kill-region)
7605 ;; if true, prepend string
7606 (kill-append string (< end beg))
7608 (setq this-command 'kill-region))
7612 ;; 3. The third argument to `condition-case' tells the interpreter
7613 ;; what to do with an error.
7616 ;; The third argument has a conditions part and a body part.
7617 ;; If the conditions are met (in this case,
7618 ;; if text or buffer is read-only)
7619 ;; then the body is executed.
7622 ((buffer-read-only text-read-only) ;; this is the if-part
7624 (copy-region-as-kill beg end)
7627 (if kill-read-only-ok ;; usually this variable is nil
7628 (message "Read only text copied to kill ring")
7629 ;; or else, signal an error if the buffer is read-only;
7630 (barf-if-buffer-read-only)
7631 ;; and, in any case, signal that the text is read-only.
7632 (signal 'text-read-only (list (current-buffer)))))))
7636 @node condition-case, delete-and-extract-region, Complete kill-region, kill-region
7637 @comment node-name, next, previous, up
7638 @subsection @code{condition-case}
7639 @findex condition-case
7641 As we have seen earlier (@pxref{Making Errors, , Generate an Error
7642 Message}), when the Emacs Lisp interpreter has trouble evaluating an
7643 expression, it provides you with help; in the jargon, this is called
7644 ``signaling an error''. Usually, the computer stops the program and
7645 shows you a message.
7647 However, some programs undertake complicated actions. They should not
7648 simply stop on an error. In the @code{kill-region} function, the most
7649 likely error is that you will try to kill text that is read-only and
7650 cannot be removed. So the @code{kill-region} function contains code
7651 to handle this circumstance. This code, which makes up the body of
7652 the @code{kill-region} function, is inside of a @code{condition-case}
7656 The template for @code{condition-case} looks like this:
7663 @var{error-handler}@dots{})
7667 The second argument, @var{bodyform}, is straightforward. The
7668 @code{condition-case} special form causes the Lisp interpreter to
7669 evaluate the code in @var{bodyform}. If no error occurs, the special
7670 form returns the code's value and produces the side-effects, if any.
7672 In short, the @var{bodyform} part of a @code{condition-case}
7673 expression determines what should happen when everything works
7676 However, if an error occurs, among its other actions, the function
7677 generating the error signal will define one or more error condition
7680 An error handler is the third argument to @code{condition case}.
7681 An error handler has two parts, a @var{condition-name} and a
7682 @var{body}. If the @var{condition-name} part of an error handler
7683 matches a condition name generated by an error, then the @var{body}
7684 part of the error handler is run.
7686 As you will expect, the @var{condition-name} part of an error handler
7687 may be either a single condition name or a list of condition names.
7689 Also, a complete @code{condition-case} expression may contain more
7690 than one error handler. When an error occurs, the first applicable
7693 Lastly, the first argument to the @code{condition-case} expression,
7694 the @var{var} argument, is sometimes bound to a variable that
7695 contains information about the error. However, if that argument is
7696 nil, as is the case in @code{kill-region}, that information is
7700 In brief, in the @code{kill-region} function, the code
7701 @code{condition-case} works like this:
7705 @var{If no errors}, @var{run only this code}
7706 @var{but}, @var{if errors}, @var{run this other code}.
7710 @node delete-and-extract-region, , condition-case, kill-region
7711 @comment node-name, next, previous, up
7712 @subsection @code{delete-and-extract-region}
7713 @findex delete-and-extract-region
7715 A @code{condition-case} expression has two parts, a part that is
7716 evaluated in the expectation that all will go well, but which may
7717 generate an error; and a part that is evaluated when there is an
7720 First, let us look at the code in @code{kill-region} that is run in
7721 the expectation that all goes well. This is the core of the function.
7722 The code looks like this:
7726 (let ((string (delete-and-extract-region beg end)))
7728 (if (eq last-command 'kill-region)
7729 (kill-append string (< end beg))
7731 (setq this-command 'kill-region))
7735 It looks complicated because we have the new functions
7736 @code{delete-and-extract-region}, @code{kill-append}, and
7737 @code{kill-new} as well as the new variables,
7738 @code{last-command} and @code{this-command}.
7740 The @code{delete-and-extract-region} function is straightforward. It
7741 is a built-in function that deletes the text in a region (a side
7742 effect) and also returns that text. This is the function that
7743 actually removes the text. (And if it cannot do that, it signals the
7746 In this @code{let} expression, the text that
7747 @code{delete-and-extract-region} returns is placed in the local
7748 variable called @samp{string}. This is the text that is removed from
7749 the buffer. (To be more precise, the variable is set to point to the
7750 address of the extracted text; to say it is `placed in' the variable
7751 is simply a shorthand.)
7753 If the variable @samp{string} does point to text, that text is added
7754 to the kill ring. The variable will have a @code{nil} value if no
7757 The code uses @code{when} to determine whether the variable
7758 @samp{string} points to text. A @code{when} statement is simply a
7759 programmers' convenience. A @code{when} statement is an @code{if}
7760 statement without the possibility of an else clause. In your mind, you
7761 can replace @code{when} with @code{if} and understand what goes on.
7762 That is what the Lisp interpreter does.
7766 Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro}
7767 enables you to define new control constructs and other language
7768 features. It tells the interpreter how to compute another Lisp
7769 expression which will in turn compute the value. In this case, the
7770 `other expression' is an @code{if} expression. For more about Lisp
7771 macros, see @ref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference
7772 Manual}. The C programming language also provides macros. These are
7773 different, but also useful. We will briefly look at C macros in
7774 @ref{Digression into C}.
7777 If the string has content, then another conditional expression is
7778 executed. This is an @code{if} with both a then-part and an else-part.
7782 (if (eq last-command 'kill-region)
7783 (kill-append string (< end beg))
7788 The then-part is evaluated if the previous command was another call to
7789 @code{kill-region}; if not, the else-part is evaluated.
7791 @code{last-command} is a variable that comes with Emacs that we have
7792 not seen before. Normally, whenever a function is executed, Emacs
7793 sets the value of @code{last-command} to the previous command.
7796 In this segment of the definition, the @code{if} expression checks
7797 whether the previous command was @code{kill-region}. If it was,
7800 (kill-append string (< end beg))
7804 concatenates a copy of the newly clipped text to the just previously
7805 clipped text in the kill ring. (If the @w{@code{(< end beg))}}
7806 expression is true, @code{kill-append} prepends the string to the just
7807 previously clipped text. For a detailed discussion, see
7808 @ref{kill-append function, , The @code{kill-append} function}.)
7810 If you then yank back the text, i.e., `paste' it, you get both
7811 pieces of text at once. That way, if you delete two words in a row,
7812 and then yank them back, you get both words, in their proper order,
7813 with one yank. (The @w{@code{(< end beg))}} expression makes sure the
7816 On the other hand, if the previous command is not @code{kill-region},
7817 then the @code{kill-new} function is called, which adds the text to
7818 the kill ring as the latest item, and sets the
7819 @code{kill-ring-yank-pointer} variable to point to it.
7821 @node Digression into C, defvar, kill-region, Cutting & Storing Text
7822 @comment node-name, next, previous, up
7823 @section Digression into C
7824 @findex delete-and-extract-region
7825 @cindex C, a digression into
7826 @cindex Digression into C
7828 The @code{zap-to-char} command uses the
7829 @code{delete-and-extract-region} function, which in turn uses two
7830 other functions, @code{copy-region-as-kill} and
7831 @code{del_range_1}. The @code{copy-region-as-kill} function will be
7832 described in a following section; it puts a copy of the region in the
7833 kill ring so it can be yanked back. (@xref{copy-region-as-kill, ,
7834 @code{copy-region-as-kill}}.)
7836 The @code{delete-and-extract-region} function removes the contents of
7837 a region and you cannot get them back.
7839 Unlike the other code discussed here, @code{delete-and-extract-region}
7840 is not written in Emacs Lisp; it is written in C and is one of the
7841 primitives of the GNU Emacs system. Since it is very simple, I will
7842 digress briefly from Lisp and describe it here.
7845 Like many of the other Emacs primitives,
7846 @code{delete-and-extract-region} is written as an instance of a C
7847 macro, a macro being a template for code. The complete macro looks
7850 @c /usr/local/src/emacs/src/editfns.c
7853 DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
7854 Sdelete_and_extract_region, 2, 2, 0,
7855 "Delete the text between START and END and return it.")
7857 Lisp_Object start, end;
7859 validate_region (&start, &end);
7860 return del_range_1 (XINT (start), XINT (end), 1, 1);
7865 Without going into the details of the macro writing process, let me
7866 point out that this macro starts with the word @code{DEFUN}. The word
7867 @code{DEFUN} was chosen since the code serves the same purpose as
7868 @code{defun} does in Lisp. The word @code{DEFUN} is followed by seven
7869 parts inside of parentheses:
7873 The first part is the name given to the function in Lisp,
7874 @code{delete-and-extract-region}.
7877 The second part is the name of the function in C,
7878 @code{Fdelete_and_extract_region}. By convention, it starts with
7879 @samp{F}. Since C does not use hyphens in names, underscores are used
7883 The third part is the name for the C constant structure that records
7884 information on this function for internal use. It is the name of the
7885 function in C but begins with an @samp{S} instead of an @samp{F}.
7888 The fourth and fifth parts specify the minimum and maximum number of
7889 arguments the function can have. This function demands exactly 2
7893 The sixth part is nearly like the argument that follows the
7894 @code{interactive} declaration in a function written in Lisp: a letter
7895 followed, perhaps, by a prompt. The only difference from the Lisp is
7896 when the macro is called with no arguments. Then you write a @code{0}
7897 (which is a `null string'), as in this macro.
7899 If you were to specify arguments, you would place them between
7900 quotation marks. The C macro for @code{goto-char} includes
7901 @code{"NGoto char: "} in this position to indicate that the function
7902 expects a raw prefix, in this case, a numerical location in a buffer,
7903 and provides a prompt.
7906 The seventh part is a documentation string, just like the one for a
7907 function written in Emacs Lisp, except that every newline must be
7908 written explicitly as @samp{\n} followed by a backslash and carriage
7912 Thus, the first two lines of documentation for @code{goto-char} are
7917 "Set point to POSITION, a number or marker.\n\
7918 Beginning of buffer is position (point-min), end is (point-max).
7924 In a C macro, the formal parameters come next, with a statement of
7925 what kind of object they are, followed by what might be called the `body'
7926 of the macro. For @code{delete-and-extract-region} the `body'
7927 consists of the following two lines:
7931 validate_region (&start, &end);
7932 return del_range_1 (XINT (start), XINT (end), 1, 1);
7936 The first function, @code{validate_region} checks whether the values
7937 passed as the beginning and end of the region are the proper type and
7938 are within range. The second function, @code{del_range_1}, actually
7941 @code{del_range_1} is a complex function we will not look into. It
7942 updates the buffer and does other things.
7944 However, it is worth looking at the two arguments passed to
7945 @code{del_range}. These are @w{@code{XINT (start)}} and @w{@code{XINT
7948 As far as the C language is concerned, @code{start} and @code{end} are
7949 two integers that mark the beginning and end of the region to be
7950 deleted@footnote{More precisely, and requiring more expert knowledge
7951 to understand, the two integers are of type `Lisp_Object', which can
7952 also be a C union instead of an integer type.}.
7954 In early versions of Emacs, these two numbers were thirty-two bits
7955 long, but the code is slowly being generalized to handle other
7956 lengths. Three of the available bits are used to specify the type of
7957 information and a fourth bit is used for handling the computer's
7958 memory; the remaining bits are used as `content'.
7960 @samp{XINT} is a C macro that extracts the relevant number from the
7961 longer collection of bits; the four other bits are discarded.
7964 The command in @code{delete-and-extract-region} looks like this:
7967 del_range_1 (XINT (start), XINT (end), 1, 1);
7971 It deletes the region between the beginning position, @code{start},
7972 and the ending position, @code{end}.
7974 From the point of view of the person writing Lisp, Emacs is all very
7975 simple; but hidden underneath is a great deal of complexity to make it
7978 @node defvar, copy-region-as-kill, Digression into C, Cutting & Storing Text
7979 @comment node-name, next, previous, up
7980 @section Initializing a Variable with @code{defvar}
7982 @cindex Initializing a variable
7983 @cindex Variable initialization
7985 Unlike the @code{delete-and-extract-region} function, the
7986 @code{copy-region-as-kill} function is written in Emacs Lisp. Two
7987 functions within it, @code{kill-append} and @code{kill-new}, copy a
7988 region in a buffer and save it in a variable called the
7989 @code{kill-ring}. This section describes how the @code{kill-ring}
7990 variable is created and initialized using the @code{defvar} special
7993 (Again we note that the term @code{kill-ring} is a misnomer. The text
7994 that is clipped out of the buffer can be brought back; it is not a ring
7995 of corpses, but a ring of resurrectable text.)
7997 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
7998 given an initial value by using the @code{defvar} special form. The
7999 name comes from ``define variable''.
8001 The @code{defvar} special form is similar to @code{setq} in that it sets
8002 the value of a variable. It is unlike @code{setq} in two ways: first,
8003 it only sets the value of the variable if the variable does not already
8004 have a value. If the variable already has a value, @code{defvar} does
8005 not override the existing value. Second, @code{defvar} has a
8006 documentation string.
8008 (Another special form, @code{defcustom}, is designed for variables
8009 that people customize. It has more features than @code{defvar}.
8010 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
8013 * See variable current value::
8014 * defvar and asterisk:: An old-time convention.
8017 @node See variable current value, defvar and asterisk, defvar, defvar
8019 @unnumberedsubsec Seeing the Current Value of a Variable
8022 You can see the current value of a variable, any variable, by using
8023 the @code{describe-variable} function, which is usually invoked by
8024 typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
8025 (followed by @key{RET}) when prompted, you will see what is in your
8026 current kill ring---this may be quite a lot! Conversely, if you have
8027 been doing nothing this Emacs session except read this document, you
8028 may have nothing in it. Also, you will see the documentation for
8034 List of killed text sequences.
8035 Since the kill ring is supposed to interact nicely with cut-and-paste
8036 facilities offered by window systems, use of this variable should
8039 interact nicely with `interprogram-cut-function' and
8040 `interprogram-paste-function'. The functions `kill-new',
8041 `kill-append', and `current-kill' are supposed to implement this
8042 interaction; you may want to use them instead of manipulating the kill
8048 The kill ring is defined by a @code{defvar} in the following way:
8052 (defvar kill-ring nil
8053 "List of killed text sequences.
8059 In this variable definition, the variable is given an initial value of
8060 @code{nil}, which makes sense, since if you have saved nothing, you want
8061 nothing back if you give a @code{yank} command. The documentation
8062 string is written just like the documentation string of a @code{defun}.
8063 As with the documentation string of the @code{defun}, the first line of
8064 the documentation should be a complete sentence, since some commands,
8065 like @code{apropos}, print only the first line of documentation.
8066 Succeeding lines should not be indented; otherwise they look odd when
8067 you use @kbd{C-h v} (@code{describe-variable}).
8069 @node defvar and asterisk, , See variable current value, defvar
8070 @subsection @code{defvar} and an asterisk
8071 @findex defvar @r{for a user customizable variable}
8072 @findex defvar @r{with an asterisk}
8074 In the past, Emacs used the @code{defvar} special form both for
8075 internal variables that you would not expect a user to change and for
8076 variables that you do expect a user to change. Although you can still
8077 use @code{defvar} for user customizable variables, please use
8078 @code{defcustom} instead, since that special form provides a path into
8079 the Customization commands. (@xref{defcustom, , Specifying Variables
8080 using @code{defcustom}}.)
8082 When you specified a variable using the @code{defvar} special form,
8083 you could distinguish a readily settable variable from others by
8084 typing an asterisk, @samp{*}, in the first column of its documentation
8085 string. For example:
8089 (defvar shell-command-default-error-buffer nil
8090 "*Buffer name for `shell-command' @dots{} error output.
8095 @findex set-variable
8097 You could (and still can) use the @code{set-variable} command to
8098 change the value of @code{shell-command-default-error-buffer}
8099 temporarily. However, options set using @code{set-variable} are set
8100 only for the duration of your editing session. The new values are not
8101 saved between sessions. Each time Emacs starts, it reads the original
8102 value, unless you change the value within your @file{.emacs} file,
8103 either by setting it manually or by using @code{customize}.
8104 @xref{Emacs Initialization, , Your @file{.emacs} File}.
8106 For me, the major use of the @code{set-variable} command is to suggest
8107 variables that I might want to set in my @file{.emacs} file. There
8108 are now more than 700 such variables --- far too many to remember
8109 readily. Fortunately, you can press @key{TAB} after calling the
8110 @code{M-x set-variable} command to see the list of variables.
8111 (@xref{Examining, , Examining and Setting Variables, emacs,
8112 The GNU Emacs Manual}.)
8114 @node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text
8115 @comment node-name, next, previous, up
8116 @section @code{copy-region-as-kill}
8117 @findex copy-region-as-kill
8120 The @code{copy-region-as-kill} function copies a region of text from a
8121 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
8122 in the @code{kill-ring}.
8124 If you call @code{copy-region-as-kill} immediately after a
8125 @code{kill-region} command, Emacs appends the newly copied text to the
8126 previously copied text. This means that if you yank back the text, you
8127 get it all, from both this and the previous operation. On the other
8128 hand, if some other command precedes the @code{copy-region-as-kill},
8129 the function copies the text into a separate entry in the kill ring.
8132 * Complete copy-region-as-kill:: The complete function definition.
8133 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
8136 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
8138 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
8142 Here is the complete text of the version 21 @code{copy-region-as-kill}
8145 @c !!! for no text properties, use buffer-substring-no-properties
8149 (defun copy-region-as-kill (beg end)
8150 "Save the region as if killed, but don't kill it.
8151 In Transient Mark mode, deactivate the mark.
8152 If `interprogram-cut-function' is non-nil, also save
8153 the text for a window system cut and paste."
8157 (if (eq last-command 'kill-region)
8158 (kill-append (buffer-substring beg end) (< end beg))
8159 (kill-new (buffer-substring beg end)))
8162 (if transient-mark-mode
8163 (setq deactivate-mark t))
8169 As usual, this function can be divided into its component parts:
8173 (defun copy-region-as-kill (@var{argument-list})
8174 "@var{documentation}@dots{}"
8180 The arguments are @code{beg} and @code{end} and the function is
8181 interactive with @code{"r"}, so the two arguments must refer to the
8182 beginning and end of the region. If you have been reading though this
8183 document from the beginning, understanding these parts of a function is
8184 almost becoming routine.
8186 The documentation is somewhat confusing unless you remember that the
8187 word `kill' has a meaning different from its usual meaning. The
8188 `Transient Mark' and @code{interprogram-cut-function} comments explain
8189 certain side-effects.
8191 After you once set a mark, a buffer always contains a region. If you
8192 wish, you can use Transient Mark mode to highlight the region
8193 temporarily. (No one wants to highlight the region all the time, so
8194 Transient Mark mode highlights it only at appropriate times. Many
8195 people turn off Transient Mark mode, so the region is never
8198 Also, a windowing system allows you to copy, cut, and paste among
8199 different programs. In the X windowing system, for example, the
8200 @code{interprogram-cut-function} function is @code{x-select-text},
8201 which works with the windowing system's equivalent of the Emacs kill
8204 The body of the @code{copy-region-as-kill} function starts with an
8205 @code{if} clause. What this clause does is distinguish between two
8206 different situations: whether or not this command is executed
8207 immediately after a previous @code{kill-region} command. In the first
8208 case, the new region is appended to the previously copied text.
8209 Otherwise, it is inserted into the beginning of the kill ring as a
8210 separate piece of text from the previous piece.
8212 The last two lines of the function prevent the region from lighting up
8213 if Transient Mark mode is turned on.
8215 The body of @code{copy-region-as-kill} merits discussion in detail.
8217 @node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
8218 @comment node-name, next, previous, up
8219 @subsection The Body of @code{copy-region-as-kill}
8221 The @code{copy-region-as-kill} function works in much the same way as
8222 the @code{kill-region} function (@pxref{kill-region,
8223 ,@code{kill-region}}). Both are written so that two or more kills in
8224 a row combine their text into a single entry. If you yank back the
8225 text from the kill ring, you get it all in one piece. Moreover, kills
8226 that kill forward from the current position of the cursor are added to
8227 the end of the previously copied text and commands that copy text
8228 backwards add it to the beginning of the previously copied text. This
8229 way, the words in the text stay in the proper order.
8231 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
8232 use of the @code{last-command} variable that keeps track of the
8233 previous Emacs command.
8236 * last-command & this-command::
8237 * kill-append function::
8238 * kill-new function::
8241 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
8243 @unnumberedsubsubsec @code{last-command} and @code{this-command}
8246 Normally, whenever a function is executed, Emacs sets the value of
8247 @code{this-command} to the function being executed (which in this case
8248 would be @code{copy-region-as-kill}). At the same time, Emacs sets
8249 the value of @code{last-command} to the previous value of
8250 @code{this-command}.
8252 In the first part of the body of the @code{copy-region-as-kill}
8253 function, an @code{if} expression determines whether the value of
8254 @code{last-command} is @code{kill-region}. If so, the then-part of
8255 the @code{if} expression is evaluated; it uses the @code{kill-append}
8256 function to concatenate the text copied at this call to the function
8257 with the text already in the first element (the @sc{car}) of the kill
8258 ring. On the other hand, if the value of @code{last-command} is not
8259 @code{kill-region}, then the @code{copy-region-as-kill} function
8260 attaches a new element to the kill ring using the @code{kill-new}
8264 The @code{if} expression reads as follows; it uses @code{eq}, which is
8265 a function we have not yet seen:
8269 (if (eq last-command 'kill-region)
8271 (kill-append (buffer-substring beg end) (< end beg))
8273 (kill-new (buffer-substring beg end)))
8277 @findex eq @r{(example of use)}
8279 The @code{eq} function tests whether its first argument is the same Lisp
8280 object as its second argument. The @code{eq} function is similar to the
8281 @code{equal} function in that it is used to test for equality, but
8282 differs in that it determines whether two representations are actually
8283 the same object inside the computer, but with different names.
8284 @code{equal} determines whether the structure and contents of two
8285 expressions are the same.
8287 If the previous command was @code{kill-region}, then the Emacs Lisp
8288 interpreter calls the @code{kill-append} function
8290 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
8291 @unnumberedsubsubsec The @code{kill-append} function
8295 The @code{kill-append} function looks like this:
8299 (defun kill-append (string before-p)
8300 "Append STRING to the end of the latest kill in the kill ring.
8301 If BEFORE-P is non-nil, prepend STRING to the kill.
8302 If `interprogram-cut-function' is set, pass the resulting kill to
8304 (kill-new (if before-p
8305 (concat string (car kill-ring))
8306 (concat (car kill-ring) string))
8312 The @code{kill-append} function is fairly straightforward. It uses
8313 the @code{kill-new} function, which we will discuss in more detail in
8316 First, let us look at the conditional that is one of the two arguments
8317 to @code{kill-new}. It uses @code{concat} to concatenate the new text
8318 to the @sc{car} of the kill ring. Whether it prepends or appends the
8319 text depends on the results of an @code{if} expression:
8323 (if before-p ; @r{if-part}
8324 (concat string (car kill-ring)) ; @r{then-part}
8325 (concat (car kill-ring) string)) ; @r{else-part}
8330 If the region being killed is before the region that was killed in the
8331 last command, then it should be prepended before the material that was
8332 saved in the previous kill; and conversely, if the killed text follows
8333 what was just killed, it should be appended after the previous text.
8334 The @code{if} expression depends on the predicate @code{before-p} to
8335 decide whether the newly saved text should be put before or after the
8336 previously saved text.
8338 The symbol @code{before-p} is the name of one of the arguments to
8339 @code{kill-append}. When the @code{kill-append} function is
8340 evaluated, it is bound to the value returned by evaluating the actual
8341 argument. In this case, this is the expression @code{(< end beg)}.
8342 This expression does not directly determine whether the killed text in
8343 this command is located before or after the kill text of the last
8344 command; what it does is determine whether the value of the variable
8345 @code{end} is less than the value of the variable @code{beg}. If it
8346 is, it means that the user is most likely heading towards the
8347 beginning of the buffer. Also, the result of evaluating the predicate
8348 expression, @code{(< end beg)}, will be true and the text will be
8349 prepended before the previous text. On the other hand, if the value of
8350 the variable @code{end} is greater than the value of the variable
8351 @code{beg}, the text will be appended after the previous text.
8354 When the newly saved text will be prepended, then the string with the new
8355 text will be concatenated before the old text:
8358 (concat string (car kill-ring))
8363 But if the text will be appended, it will be concatenated
8367 (concat (car kill-ring) string))
8370 To understand how this works, we first need to review the
8371 @code{concat} function. The @code{concat} function links together or
8372 unites two strings of text. The result is a string. For example:
8376 (concat "abc" "def")
8382 (car '("first element" "second element")))
8383 @result{} "new first element"
8386 '("first element" "second element")) " modified")
8387 @result{} "first element modified"
8391 We can now make sense of @code{kill-append}: it modifies the contents
8392 of the kill ring. The kill ring is a list, each element of which is
8393 saved text. The @code{kill-append} function uses the @code{kill-new}
8394 function which in turn uses the @code{setcar} function.
8396 @node kill-new function, , kill-append function, copy-region-as-kill body
8397 @unnumberedsubsubsec The @code{kill-new} function
8401 The @code{kill-new} function looks like this:
8405 (defun kill-new (string &optional replace)
8406 "Make STRING the latest kill in the kill ring.
8407 Set the kill-ring-yank pointer to point to it.
8408 If `interprogram-cut-function' is non-nil, apply it to STRING.
8409 Optional second argument REPLACE non-nil means that STRING will replace
8410 the front of the kill ring, rather than being added to the list."
8413 (and (fboundp 'menu-bar-update-yank-menu)
8414 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8417 (if (and replace kill-ring)
8418 (setcar kill-ring string)
8419 (setq kill-ring (cons string kill-ring))
8420 (if (> (length kill-ring) kill-ring-max)
8421 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8424 (setq kill-ring-yank-pointer kill-ring)
8425 (if interprogram-cut-function
8426 (funcall interprogram-cut-function string (not replace))))
8430 As usual, we can look at this function in parts.
8433 The first line of the documentation makes sense:
8436 Make STRING the latest kill in the kill ring.
8440 Let's skip over the rest of the documentation for the moment.
8442 Also, let's skip over the first two lines of code, those involving
8443 @code{menu-bar-update-yank-menu}. We will explain them below.
8446 The critical lines are these:
8450 (if (and replace kill-ring)
8452 (setcar kill-ring string)
8456 (setq kill-ring (cons string kill-ring))
8457 (if (> (length kill-ring) kill-ring-max)
8458 ;; @r{avoid overly long kill ring}
8459 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
8462 (setq kill-ring-yank-pointer kill-ring)
8463 (if interprogram-cut-function
8464 (funcall interprogram-cut-function string (not replace))))
8468 The conditional test is @w{@code{(and replace kill-ring)}}.
8469 This will be true when two conditions are met: the kill ring has
8470 something in it, and the @code{replace} variable is true.
8473 The @code{kill-append} function sets @code{replace} to be true; then,
8474 when the kill ring has at least one item in it, the @code{setcar}
8475 expression is executed:
8478 (setcar kill-ring string)
8481 The @code{setcar} function actually changes the first element of the
8482 @code{kill-ring} list to the value of @code{string}. It replaces the
8485 On the other hand, if the kill ring is empty, or replace is false, the
8486 else-part of the condition is executed:
8490 (setq kill-ring (cons string kill-ring))
8491 (if (> (length kill-ring) kill-ring-max)
8492 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8497 This expression first constructs a new version of the kill ring by
8498 prepending @code{string} to the existing kill ring as a new element.
8499 Then it executes a second @code{if} clause. This second @code{if}
8500 clause keeps the kill ring from growing too long.
8502 Let's look at these two expressions in order.
8504 The @code{setq} line of the else-part sets the new value of the kill
8505 ring to what results from adding the string being killed to the old kill
8509 We can see how this works with an example:
8512 (setq example-list '("here is a clause" "another clause"))
8517 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
8518 @code{example-list} and see what it returns:
8523 @result{} ("here is a clause" "another clause")
8529 Now, we can add a new element on to this list by evaluating the
8530 following expression:
8531 @findex cons, @r{example}
8534 (setq example-list (cons "a third clause" example-list))
8539 When we evaluate @code{example-list}, we find its value is:
8544 @result{} ("a third clause" "here is a clause" "another clause")
8549 Thus, the third clause was added to the list by @code{cons}.
8552 This is exactly similar to what the @code{setq} and @code{cons} do in
8553 the function. Here is the line again:
8556 (setq kill-ring (cons string kill-ring))
8560 Now for the second part of the @code{if} clause. This expression
8561 keeps the kill ring from growing too long. It looks like this:
8565 (if (> (length kill-ring) kill-ring-max)
8566 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
8570 The code checks whether the length of the kill ring is greater than
8571 the maximum permitted length. This is the value of
8572 @code{kill-ring-max} (which is 60, by default). If the length of the
8573 kill ring is too long, then this code sets the last element of the
8574 kill ring to @code{nil}. It does this by using two functions,
8575 @code{nthcdr} and @code{setcdr}.
8577 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
8578 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
8579 @sc{car} of a list. In this case, however, @code{setcdr} will not be
8580 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
8581 function is used to cause it to set the @sc{cdr} of the next to last
8582 element of the kill ring---this means that since the @sc{cdr} of the
8583 next to last element is the last element of the kill ring, it will set
8584 the last element of the kill ring.
8586 @findex nthcdr, @r{example}
8587 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
8588 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
8589 @dots{} It does this @var{N} times and returns the results.
8591 @findex setcdr, @r{example}
8592 Thus, if we had a four element list that was supposed to be three
8593 elements long, we could set the @sc{cdr} of the next to last element
8594 to @code{nil}, and thereby shorten the list. (If you sent the last
8595 element to some other value than @code{nil}, which you could do, then
8596 you would not have shortened the list.)
8598 You can see shortening by evaluating the following three expressions
8599 in turn. First set the value of @code{trees} to @code{(maple oak pine
8600 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
8601 and then find the value of @code{trees}:
8605 (setq trees '(maple oak pine birch))
8606 @result{} (maple oak pine birch)
8610 (setcdr (nthcdr 2 trees) nil)
8614 @result{} (maple oak pine)
8619 (The value returned by the @code{setcdr} expression is @code{nil} since
8620 that is what the @sc{cdr} is set to.)
8622 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
8623 @sc{cdr} a number of times that is one less than the maximum permitted
8624 size of the kill ring and sets the @sc{cdr} of that element (which
8625 will be the rest of the elements in the kill ring) to @code{nil}.
8626 This prevents the kill ring from growing too long.
8629 The next to last expression in the @code{kill-new} function is
8632 (setq kill-ring-yank-pointer kill-ring)
8635 The @code{kill-ring-yank-pointer} is a global variable that is set to be
8636 the @code{kill-ring}.
8638 Even though the @code{kill-ring-yank-pointer} is called a
8639 @samp{pointer}, it is a variable just like the kill ring. However, the
8640 name has been chosen to help humans understand how the variable is used.
8641 The variable is used in functions such as @code{yank} and
8642 @code{yank-pop} (@pxref{Yanking, , Yanking Text Back}).
8645 Now, to return to the first two lines in the body of the function:
8649 (and (fboundp 'menu-bar-update-yank-menu)
8650 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
8655 This is an expression whose first element is the function @code{and}.
8657 @findex and, @r{introduced}
8658 The @code{and} special form evaluates each of its arguments until one of
8659 the arguments returns a value of @code{nil}, in which case the
8660 @code{and} expression returns @code{nil}; however, if none of the
8661 arguments returns a value of @code{nil}, the value resulting from
8662 evaluating the last argument is returned. (Since such a value is not
8663 @code{nil}, it is considered true in Emacs Lisp.) In other words, an
8664 @code{and} expression returns a true value only if all its arguments
8668 In this case, the expression tests first to see whether
8669 @code{menu-bar-update-yank-menu} exists as a function, and if so,
8670 calls it. The @code{fboundp} function returns true if the symbol it
8671 is testing has a function definition that `is not void'. If the
8672 symbol's function definition were void, we would receive an error
8673 message, as we did when we created errors intentionally (@pxref{Making
8674 Errors, , Generate an Error Message}).
8677 Essentially, the @code{and} is an @code{if} expression that reads like
8682 if @var{the-menu-bar-function-exists}
8683 then @var{execute-it}
8687 @code{menu-bar-update-yank-menu} is one of the functions that make it
8688 possible to use the `Select and Paste' menu in the Edit item of a menu
8689 bar; using a mouse, you can look at the various pieces of text you
8690 have saved and select one piece to paste.
8692 Finally, the last expression in the @code{kill-new} function adds the
8693 newly copied string to whatever facility exists for copying and
8694 pasting among different programs running in a windowing system. In
8695 the X Windowing system, for example, the @code{x-select-text} function
8696 takes the string and stores it in memory operated by X. You can paste
8697 the string in another program, such as an Xterm.
8700 The expression looks like this:
8704 (if interprogram-cut-function
8705 (funcall interprogram-cut-function string (not replace))))
8709 If an @code{interprogram-cut-function} exists, then Emacs executes
8710 @code{funcall}, which in turn calls its first argument as a function
8711 and passes the remaining arguments to it. (Incidentally, as far as I
8712 can see, this @code{if} expression could be replaced by an @code{and}
8713 expression similar to the one in the first part of the function.)
8715 We are not going to discuss windowing systems and other programs
8716 further, but merely note that this is a mechanism that enables GNU
8717 Emacs to work easily and well with other programs.
8719 This code for placing text in the kill ring, either concatenated with
8720 an existing element or as a new element, leads us to the code for
8721 bringing back text that has been cut out of the buffer---the yank
8722 commands. However, before discussing the yank commands, it is better
8723 to learn how lists are implemented in a computer. This will make
8724 clear such mysteries as the use of the term `pointer'.
8727 @node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text
8728 @comment node-name, next, previous, up
8731 Here is a brief summary of some recently introduced functions.
8736 @code{car} returns the first element of a list; @code{cdr} returns the
8737 second and subsequent elements of a list.
8744 (car '(1 2 3 4 5 6 7))
8746 (cdr '(1 2 3 4 5 6 7))
8747 @result{} (2 3 4 5 6 7)
8752 @code{cons} constructs a list by prepending its first argument to its
8766 Return the result of taking @sc{cdr} `n' times on a list.
8774 The `rest of the rest', as it were.
8781 (nthcdr 3 '(1 2 3 4 5 6 7))
8788 @code{setcar} changes the first element of a list; @code{setcdr}
8789 changes the second and subsequent elements of a list.
8796 (setq triple '(1 2 3))
8803 (setcdr triple '("foo" "bar"))
8806 @result{} (37 "foo" "bar")
8811 Evaluate each argument in sequence and then return the value of the
8824 @item save-restriction
8825 Record whatever narrowing is in effect in the current buffer, if any,
8826 and restore that narrowing after evaluating the arguments.
8828 @item search-forward
8829 Search for a string, and if the string is found, move point.
8833 Takes four arguments:
8837 The string to search for.
8840 Optionally, the limit of the search.
8843 Optionally, what to do if the search fails, return @code{nil} or an
8847 Optionally, how many times to repeat the search; if negative, the
8848 search goes backwards.
8852 @itemx delete-and-extract-region
8853 @itemx copy-region-as-kill
8855 @code{kill-region} cuts the text between point and mark from the
8856 buffer and stores that text in the kill ring, so you can get it back
8859 @code{delete-and-extract-region} removes the text between point and
8860 mark from the buffer and throws it away. You cannot get it back.
8862 @code{copy-region-as-kill} copies the text between point and mark into
8863 the kill ring, from which you can get it by yanking. The function
8864 does not cut or remove the text from the buffer.
8868 @node search Exercises, , cons & search-fwd Review, Cutting & Storing Text
8869 @section Searching Exercises
8873 Write an interactive function that searches for a string. If the
8874 search finds the string, leave point after it and display a message
8875 that says ``Found!''. (Do not use @code{search-forward} for the name
8876 of this function; if you do, you will overwrite the existing version of
8877 @code{search-forward} that comes with Emacs. Use a name such as
8878 @code{test-search} instead.)
8881 Write a function that prints the third element of the kill ring in the
8882 echo area, if any; if the kill ring does not contain a third element,
8883 print an appropriate message.
8886 @node List Implementation, Yanking, Cutting & Storing Text, Top
8887 @comment node-name, next, previous, up
8888 @chapter How Lists are Implemented
8889 @cindex Lists in a computer
8891 In Lisp, atoms are recorded in a straightforward fashion; if the
8892 implementation is not straightforward in practice, it is, nonetheless,
8893 straightforward in theory. The atom @samp{rose}, for example, is
8894 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
8895 @samp{e}. A list, on the other hand, is kept differently. The mechanism
8896 is equally simple, but it takes a moment to get used to the idea. A
8897 list is kept using a series of pairs of pointers. In the series, the
8898 first pointer in each pair points to an atom or to another list, and the
8899 second pointer in each pair points to the next pair, or to the symbol
8900 @code{nil}, which marks the end of the list.
8902 A pointer itself is quite simply the electronic address of what is
8903 pointed to. Hence, a list is kept as a series of electronic addresses.
8906 * Lists diagrammed::
8907 * Symbols as Chest:: Exploring a powerful metaphor.
8911 @node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
8913 @unnumberedsec Lists diagrammed
8916 For example, the list @code{(rose violet buttercup)} has three elements,
8917 @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the
8918 electronic address of @samp{rose} is recorded in a segment of computer
8919 memory along with the address that gives the electronic address of where
8920 the atom @samp{violet} is located; and that address (the one that tells
8921 where @samp{violet} is located) is kept along with an address that tells
8922 where the address for the atom @samp{buttercup} is located.
8925 This sounds more complicated than it is and is easier seen in a diagram:
8927 @c clear print-postscript-figures
8928 @c !!! cons-cell-diagram #1
8932 ___ ___ ___ ___ ___ ___
8933 |___|___|--> |___|___|--> |___|___|--> nil
8936 --> rose --> violet --> buttercup
8940 @ifset print-postscript-figures
8944 %%%% old method of including an image
8945 % \input /usr/local/lib/tex/inputs/psfig.tex
8946 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
8951 @ifclear print-postscript-figures
8955 ___ ___ ___ ___ ___ ___
8956 |___|___|--> |___|___|--> |___|___|--> nil
8959 --> rose --> violet --> buttercup
8966 In the diagram, each box represents a word of computer memory that
8967 holds a Lisp object, usually in the form of a memory address. The boxes,
8968 i.e.@: the addresses, are in pairs. Each arrow points to what the address
8969 is the address of, either an atom or another pair of addresses. The
8970 first box is the electronic address of @samp{rose} and the arrow points
8971 to @samp{rose}; the second box is the address of the next pair of boxes,
8972 the first part of which is the address of @samp{violet} and the second
8973 part of which is the address of the next pair. The very last box
8974 points to the symbol @code{nil}, which marks the end of the list.
8977 When a variable is set to a list with a function such as @code{setq},
8978 it stores the address of the first box in the variable. Thus,
8979 evaluation of the expression
8982 (setq bouquet '(rose violet buttercup))
8987 creates a situation like this:
8989 @c cons-cell-diagram #2
8995 | ___ ___ ___ ___ ___ ___
8996 --> |___|___|--> |___|___|--> |___|___|--> nil
8999 --> rose --> violet --> buttercup
9003 @ifset print-postscript-figures
9007 %%%% old method of including an image
9008 % \input /usr/local/lib/tex/inputs/psfig.tex
9009 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
9014 @ifclear print-postscript-figures
9020 | ___ ___ ___ ___ ___ ___
9021 --> |___|___|--> |___|___|--> |___|___|--> nil
9024 --> rose --> violet --> buttercup
9031 In this example, the symbol @code{bouquet} holds the address of the first
9035 This same list can be illustrated in a different sort of box notation
9038 @c cons-cell-diagram #2a
9044 | -------------- --------------- ----------------
9045 | | car | cdr | | car | cdr | | car | cdr |
9046 -->| rose | o------->| violet | o------->| butter- | nil |
9047 | | | | | | | cup | |
9048 -------------- --------------- ----------------
9052 @ifset print-postscript-figures
9056 %%%% old method of including an image
9057 % \input /usr/local/lib/tex/inputs/psfig.tex
9058 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
9063 @ifclear print-postscript-figures
9069 | -------------- --------------- ----------------
9070 | | car | cdr | | car | cdr | | car | cdr |
9071 -->| rose | o------->| violet | o------->| butter- | nil |
9072 | | | | | | | cup | |
9073 -------------- --------------- ----------------
9079 (Symbols consist of more than pairs of addresses, but the structure of
9080 a symbol is made up of addresses. Indeed, the symbol @code{bouquet}
9081 consists of a group of address-boxes, one of which is the address of
9082 the printed word @samp{bouquet}, a second of which is the address of a
9083 function definition attached to the symbol, if any, a third of which
9084 is the address of the first pair of address-boxes for the list
9085 @code{(rose violet buttercup)}, and so on. Here we are showing that
9086 the symbol's third address-box points to the first pair of
9087 address-boxes for the list.)
9089 If a symbol is set to the @sc{cdr} of a list, the list itself is not
9090 changed; the symbol simply has an address further down the list. (In
9091 the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus,
9092 evaluation of the following expression
9095 (setq flowers (cdr bouquet))
9102 @c cons-cell-diagram #3
9109 | ___ ___ | ___ ___ ___ ___
9110 --> | | | --> | | | | | |
9111 |___|___|----> |___|___|--> |___|___|--> nil
9114 --> rose --> violet --> buttercup
9119 @ifset print-postscript-figures
9123 %%%% old method of including an image
9124 % \input /usr/local/lib/tex/inputs/psfig.tex
9125 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
9130 @ifclear print-postscript-figures
9137 | ___ ___ | ___ ___ ___ ___
9138 --> | | | --> | | | | | |
9139 |___|___|----> |___|___|--> |___|___|--> nil
9142 --> rose --> violet --> buttercup
9150 The value of @code{flowers} is @code{(violet buttercup)}, which is
9151 to say, the symbol @code{flowers} holds the address of the pair of
9152 address-boxes, the first of which holds the address of @code{violet},
9153 and the second of which holds the address of @code{buttercup}.
9155 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
9156 pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
9157 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
9158 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
9159 information about cons cells and dotted pairs.
9162 The function @code{cons} adds a new pair of addresses to the front of
9163 a series of addresses like that shown above. For example, evaluating
9167 (setq bouquet (cons 'lily bouquet))
9174 @c cons-cell-diagram #4
9181 | ___ ___ ___ ___ | ___ ___ ___ ___
9182 --> | | | | | | --> | | | | | |
9183 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9186 --> lily --> rose --> violet --> buttercup
9191 @ifset print-postscript-figures
9195 %%%% old method of including an image
9196 % \input /usr/local/lib/tex/inputs/psfig.tex
9197 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
9202 @ifclear print-postscript-figures
9209 | ___ ___ ___ ___ | ___ ___ ___ ___
9210 --> | | | | | | --> | | | | | |
9211 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
9214 --> lily --> rose --> violet --> buttercup
9223 However, this does not change the value of the symbol
9224 @code{flowers}, as you can see by evaluating the following,
9227 (eq (cdr (cdr bouquet)) flowers)
9231 which returns @code{t} for true.
9233 Until it is reset, @code{flowers} still has the value
9234 @code{(violet buttercup)}; that is, it has the address of the cons
9235 cell whose first address is of @code{violet}. Also, this does not
9236 alter any of the pre-existing cons cells; they are all still there.
9238 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
9239 of the next cons cell in the series; to get the @sc{car} of a list,
9240 you get the address of the first element of the list; to @code{cons} a
9241 new element on a list, you add a new cons cell to the front of the list.
9242 That is all there is to it! The underlying structure of Lisp is
9245 And what does the last address in a series of cons cells refer to? It
9246 is the address of the empty list, of @code{nil}.
9248 In summary, when a Lisp variable is set to a value, it is provided with
9249 the address of the list to which the variable refers.
9251 @node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation
9252 @section Symbols as a Chest of Drawers
9253 @cindex Symbols as a Chest of Drawers
9254 @cindex Chest of Drawers, metaphor for a symbol
9255 @cindex Drawers, Chest of, metaphor for a symbol
9257 In an earlier section, I suggested that you might imagine a symbol as
9258 being a chest of drawers. The function definition is put in one
9259 drawer, the value in another, and so on. What is put in the drawer
9260 holding the value can be changed without affecting the contents of the
9261 drawer holding the function definition, and vice-versa.
9263 Actually, what is put in each drawer is the address of the value or
9264 function definition. It is as if you found an old chest in the attic,
9265 and in one of its drawers you found a map giving you directions to
9266 where the buried treasure lies.
9268 (In addition to its name, symbol definition, and variable value, a
9269 symbol has a `drawer' for a @dfn{property list} which can be used to
9270 record other information. Property lists are not discussed here; see
9271 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
9275 Here is a fanciful representation:
9277 @c chest-of-drawers diagram
9282 Chest of Drawers Contents of Drawers
9286 ---------------------
9287 | directions to | [map to]
9288 | symbol name | bouquet
9290 +---------------------+
9292 | symbol definition | [none]
9294 +---------------------+
9295 | directions to | [map to]
9296 | variable value | (rose violet buttercup)
9298 +---------------------+
9300 | property list | [not described here]
9302 +---------------------+
9308 @ifset print-postscript-figures
9312 %%%% old method of including an image
9313 % \input /usr/local/lib/tex/inputs/psfig.tex
9314 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
9319 @ifclear print-postscript-figures
9324 Chest of Drawers Contents of Drawers
9328 ---------------------
9329 | directions to | [map to]
9330 | symbol name | bouquet
9332 +---------------------+
9334 | symbol definition | [none]
9336 +---------------------+
9337 | directions to | [map to]
9338 | variable value | (rose violet buttercup)
9340 +---------------------+
9342 | property list | [not described here]
9344 +---------------------+
9352 @node List Exercise, , Symbols as Chest, List Implementation
9355 Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two
9356 more flowers on to this list and set this new list to
9357 @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish.
9358 What does the @code{more-flowers} list now contain?
9360 @node Yanking, Loops & Recursion, List Implementation, Top
9361 @comment node-name, next, previous, up
9362 @chapter Yanking Text Back
9364 @findex rotate-yank-pointer
9365 @cindex Text retrieval
9366 @cindex Retrieving text
9367 @cindex Pasting text
9369 Whenever you cut text out of a buffer with a `kill' command in GNU Emacs,
9370 you can bring it back with a `yank' command. The text that is cut out of
9371 the buffer is put in the kill ring and the yank commands insert the
9372 appropriate contents of the kill ring back into a buffer (not necessarily
9373 the original buffer).
9375 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
9376 the kill ring into the current buffer. If the @kbd{C-y} command is
9377 followed immediately by @kbd{M-y}, the first element is replaced by
9378 the second element. Successive @kbd{M-y} commands replace the second
9379 element with the third, fourth, or fifth element, and so on. When the
9380 last element in the kill ring is reached, it is replaced by the first
9381 element and the cycle is repeated. (Thus the kill ring is called a
9382 `ring' rather than just a `list'. However, the actual data structure
9383 that holds the text is a list.
9384 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
9385 list is handled as a ring.)
9388 * Kill Ring Overview:: The kill ring is a list.
9389 * kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable.
9390 * yank nthcdr Exercises::
9393 @node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
9394 @comment node-name, next, previous, up
9395 @section Kill Ring Overview
9396 @cindex Kill ring overview
9398 The kill ring is a list of textual strings. This is what it looks like:
9401 ("some text" "a different piece of text" "yet more text")
9404 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
9405 string of characters saying @samp{some text} would be inserted in this
9406 buffer where my cursor is located.
9408 The @code{yank} command is also used for duplicating text by copying it.
9409 The copied text is not cut from the buffer, but a copy of it is put on the
9410 kill ring and is inserted by yanking it back.
9412 Three functions are used for bringing text back from the kill ring:
9413 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
9414 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
9415 which is used by the two other functions.
9417 These functions refer to the kill ring through a variable called the
9418 @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the
9419 @code{yank} and @code{yank-pop} functions is:
9422 (insert (car kill-ring-yank-pointer))
9425 To begin to understand how @code{yank} and @code{yank-pop} work, it is
9426 first necessary to look at the @code{kill-ring-yank-pointer} variable
9427 and the @code{rotate-yank-pointer} function.
9429 @node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking
9430 @comment node-name, next, previous, up
9431 @section The @code{kill-ring-yank-pointer} Variable
9433 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
9434 a variable. It points to something by being bound to the value of what
9435 it points to, like any other Lisp variable.
9438 Thus, if the value of the kill ring is:
9441 ("some text" "a different piece of text" "yet more text")
9446 and the @code{kill-ring-yank-pointer} points to the second clause, the
9447 value of @code{kill-ring-yank-pointer} is:
9450 ("a different piece of text" "yet more text")
9453 As explained in the previous chapter (@pxref{List Implementation}), the
9454 computer does not keep two different copies of the text being pointed to
9455 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The
9456 words ``a different piece of text'' and ``yet more text'' are not
9457 duplicated. Instead, the two Lisp variables point to the same pieces of
9458 text. Here is a diagram:
9460 @c cons-cell-diagram #5
9464 kill-ring kill-ring-yank-pointer
9466 | ___ ___ | ___ ___ ___ ___
9467 ---> | | | --> | | | | | |
9468 |___|___|----> |___|___|--> |___|___|--> nil
9471 | | --> "yet more text"
9473 | --> "a different piece of text
9480 @ifset print-postscript-figures
9484 %%%% old method of including an image
9485 % \input /usr/local/lib/tex/inputs/psfig.tex
9486 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
9491 @ifclear print-postscript-figures
9495 kill-ring kill-ring-yank-pointer
9497 | ___ ___ | ___ ___ ___ ___
9498 ---> | | | --> | | | | | |
9499 |___|___|----> |___|___|--> |___|___|--> nil
9502 | | --> "yet more text"
9504 | --> "a different piece of text
9513 Both the variable @code{kill-ring} and the variable
9514 @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is
9515 usually described as if it were actually what it is composed of. The
9516 @code{kill-ring} is spoken of as if it were the list rather than that it
9517 points to the list. Conversely, the @code{kill-ring-yank-pointer} is
9518 spoken of as pointing to a list.
9520 These two ways of talking about the same thing sound confusing at first but
9521 make sense on reflection. The kill ring is generally thought of as the
9522 complete structure of data that holds the information of what has recently
9523 been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer}
9524 on the other hand, serves to indicate---that is, to `point to'---that part
9525 of the kill ring of which the first element (the @sc{car}) will be
9528 The @code{rotate-yank-pointer} function changes the element in the
9529 kill ring to which the @code{kill-ring-yank-pointer} points; when the
9530 pointer is set to point to the next element beyond the end of the kill
9531 ring, it automatically sets it to point to the first element of the
9532 kill ring. This is how the list is transformed into a ring. The
9533 @code{rotate-yank-pointer} function itself is not difficult, but
9534 contains many details. It and the much simpler @code{yank} and
9535 @code{yank-pop} functions are described in an appendix.
9536 @xref{Kill Ring, , Handling the Kill Ring}.
9539 @node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking
9540 @section Exercises with @code{yank} and @code{nthcdr}
9544 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
9545 your kill ring. Add several items to your kill ring; look at its
9546 value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way
9547 around the kill ring. How many items were in your kill ring? Find
9548 the value of @code{kill-ring-max}. Was your kill ring full, or could
9549 you have kept more blocks of text within it?
9552 Using @code{nthcdr} and @code{car}, construct a series of expressions
9553 to return the first, second, third, and fourth elements of a list.
9556 @node Loops & Recursion, Regexp Search, Yanking, Top
9557 @comment node-name, next, previous, up
9558 @chapter Loops and Recursion
9559 @cindex Loops and recursion
9560 @cindex Recursion and loops
9561 @cindex Repetition (loops)
9563 Emacs Lisp has two primary ways to cause an expression, or a series of
9564 expressions, to be evaluated repeatedly: one uses a @code{while}
9565 loop, and the other uses @dfn{recursion}.
9567 Repetition can be very valuable. For example, to move forward four
9568 sentences, you need only write a program that will move forward one
9569 sentence and then repeat the process four times. Since a computer does
9570 not get bored or tired, such repetitive action does not have the
9571 deleterious effects that excessive or the wrong kinds of repetition can
9574 People mostly write Emacs Lisp functions using @code{while} loops and
9575 their kin; but you can use recursion, which provides a very powerful
9576 way to think about and then to solve problems@footnote{You can write
9577 recursive functions to be frugal or wasteful of mental or computer
9578 resources; as it happens, methods that people find easy---that are
9579 frugal of `mental resources'---sometimes use considerable computer
9580 resources. Emacs was designed to run on machines that we now consider
9581 limited and its default settings are conservative. You may want to
9582 increase the values of @code{max-specpdl-size} and
9583 @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to
9584 15 and 30 times their default value.}.
9587 * while:: Causing a stretch of code to repeat.
9589 * Recursion:: Causing a function to call itself.
9590 * Looping exercise::
9593 @node while, dolist dotimes, Loops & Recursion, Loops & Recursion
9594 @comment node-name, next, previous, up
9595 @section @code{while}
9599 The @code{while} special form tests whether the value returned by
9600 evaluating its first argument is true or false. This is similar to what
9601 the Lisp interpreter does with an @code{if}; what the interpreter does
9602 next, however, is different.
9604 In a @code{while} expression, if the value returned by evaluating the
9605 first argument is false, the Lisp interpreter skips the rest of the
9606 expression (the @dfn{body} of the expression) and does not evaluate it.
9607 However, if the value is true, the Lisp interpreter evaluates the body
9608 of the expression and then again tests whether the first argument to
9609 @code{while} is true or false. If the value returned by evaluating the
9610 first argument is again true, the Lisp interpreter again evaluates the
9611 body of the expression.
9614 The template for a @code{while} expression looks like this:
9618 (while @var{true-or-false-test}
9624 * Looping with while:: Repeat so long as test returns true.
9625 * Loop Example:: A @code{while} loop that uses a list.
9626 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
9627 * Incrementing Loop:: A loop with an incrementing counter.
9628 * Decrementing Loop:: A loop with a decrementing counter.
9631 @node Looping with while, Loop Example, while, while
9633 @unnumberedsubsec Looping with @code{while}
9636 So long as the true-or-false-test of the @code{while} expression
9637 returns a true value when it is evaluated, the body is repeatedly
9638 evaluated. This process is called a loop since the Lisp interpreter
9639 repeats the same thing again and again, like an airplane doing a loop.
9640 When the result of evaluating the true-or-false-test is false, the
9641 Lisp interpreter does not evaluate the rest of the @code{while}
9642 expression and `exits the loop'.
9644 Clearly, if the value returned by evaluating the first argument to
9645 @code{while} is always true, the body following will be evaluated
9646 again and again @dots{} and again @dots{} forever. Conversely, if the
9647 value returned is never true, the expressions in the body will never
9648 be evaluated. The craft of writing a @code{while} loop consists of
9649 choosing a mechanism such that the true-or-false-test returns true
9650 just the number of times that you want the subsequent expressions to
9651 be evaluated, and then have the test return false.
9653 The value returned by evaluating a @code{while} is the value of the
9654 true-or-false-test. An interesting consequence of this is that a
9655 @code{while} loop that evaluates without error will return @code{nil}
9656 or false regardless of whether it has looped 1 or 100 times or none at
9657 all. A @code{while} expression that evaluates successfully never
9658 returns a true value! What this means is that @code{while} is always
9659 evaluated for its side effects, which is to say, the consequences of
9660 evaluating the expressions within the body of the @code{while} loop.
9661 This makes sense. It is not the mere act of looping that is desired,
9662 but the consequences of what happens when the expressions in the loop
9663 are repeatedly evaluated.
9665 @node Loop Example, print-elements-of-list, Looping with while, while
9666 @comment node-name, next, previous, up
9667 @subsection A @code{while} Loop and a List
9669 A common way to control a @code{while} loop is to test whether a list
9670 has any elements. If it does, the loop is repeated; but if it does not,
9671 the repetition is ended. Since this is an important technique, we will
9672 create a short example to illustrate it.
9674 A simple way to test whether a list has elements is to evaluate the
9675 list: if it has no elements, it is an empty list and will return the
9676 empty list, @code{()}, which is a synonym for @code{nil} or false. On
9677 the other hand, a list with elements will return those elements when it
9678 is evaluated. Since Emacs Lisp considers as true any value that is not
9679 @code{nil}, a list that returns elements will test true in a
9683 For example, you can set the variable @code{empty-list} to @code{nil} by
9684 evaluating the following @code{setq} expression:
9687 (setq empty-list ())
9691 After evaluating the @code{setq} expression, you can evaluate the
9692 variable @code{empty-list} in the usual way, by placing the cursor after
9693 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
9700 On the other hand, if you set a variable to be a list with elements, the
9701 list will appear when you evaluate the variable, as you can see by
9702 evaluating the following two expressions:
9706 (setq animals '(gazelle giraffe lion tiger))
9712 Thus, to create a @code{while} loop that tests whether there are any
9713 items in the list @code{animals}, the first part of the loop will be
9724 When the @code{while} tests its first argument, the variable
9725 @code{animals} is evaluated. It returns a list. So long as the list
9726 has elements, the @code{while} considers the results of the test to be
9727 true; but when the list is empty, it considers the results of the test
9730 To prevent the @code{while} loop from running forever, some mechanism
9731 needs to be provided to empty the list eventually. An oft-used
9732 technique is to have one of the subsequent forms in the @code{while}
9733 expression set the value of the list to be the @sc{cdr} of the list.
9734 Each time the @code{cdr} function is evaluated, the list will be made
9735 shorter, until eventually only the empty list will be left. At this
9736 point, the test of the @code{while} loop will return false, and the
9737 arguments to the @code{while} will no longer be evaluated.
9739 For example, the list of animals bound to the variable @code{animals}
9740 can be set to be the @sc{cdr} of the original list with the
9741 following expression:
9744 (setq animals (cdr animals))
9748 If you have evaluated the previous expressions and then evaluate this
9749 expression, you will see @code{(giraffe lion tiger)} appear in the echo
9750 area. If you evaluate the expression again, @code{(lion tiger)} will
9751 appear in the echo area. If you evaluate it again and yet again,
9752 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
9754 A template for a @code{while} loop that uses the @code{cdr} function
9755 repeatedly to cause the true-or-false-test eventually to test false
9760 (while @var{test-whether-list-is-empty}
9762 @var{set-list-to-cdr-of-list})
9766 This test and use of @code{cdr} can be put together in a function that
9767 goes through a list and prints each element of the list on a line of its
9770 @node print-elements-of-list, Incrementing Loop, Loop Example, while
9771 @subsection An Example: @code{print-elements-of-list}
9772 @findex print-elements-of-list
9774 The @code{print-elements-of-list} function illustrates a @code{while}
9777 @cindex @file{*scratch*} buffer
9778 The function requires several lines for its output. If you are
9779 reading this in Emacs 21 or a later version, you can evaluate the
9780 following expression inside of Info, as usual.
9782 If you are using an earlier version of Emacs, you need to copy the
9783 necessary expressions to your @file{*scratch*} buffer and evaluate
9784 them there. This is because the echo area had only one line in the
9787 You can copy the expressions by marking the beginning of the region
9788 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
9789 the end of the region and then copying the region using @kbd{M-w}
9790 (@code{copy-region-as-kill}). In the @file{*scratch*} buffer, you can
9791 yank the expressions back by typing @kbd{C-y} (@code{yank}).
9793 After you have copied the expressions to the @file{*scratch*} buffer,
9794 evaluate each expression in turn. Be sure to evaluate the last
9795 expression, @code{(print-elements-of-list animals)}, by typing
9796 @kbd{C-u C-x C-e}, that is, by giving an argument to
9797 @code{eval-last-sexp}. This will cause the result of the evaluation
9798 to be printed in the @file{*scratch*} buffer instead of being printed
9799 in the echo area. (Otherwise you will see something like this in your
9800 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
9801 each @samp{^J} stands for a `newline'.)
9804 If you are using Emacs 21 or later, you can evaluate these expressions
9805 directly in the Info buffer, and the echo area will grow to show the
9810 (setq animals '(gazelle giraffe lion tiger))
9812 (defun print-elements-of-list (list)
9813 "Print each element of LIST on a line of its own."
9816 (setq list (cdr list))))
9818 (print-elements-of-list animals)
9824 When you evaluate the three expressions in sequence, you will see
9840 Each element of the list is printed on a line of its own (that is what
9841 the function @code{print} does) and then the value returned by the
9842 function is printed. Since the last expression in the function is the
9843 @code{while} loop, and since @code{while} loops always return
9844 @code{nil}, a @code{nil} is printed after the last element of the list.
9846 @node Incrementing Loop, Decrementing Loop, print-elements-of-list, while
9847 @comment node-name, next, previous, up
9848 @subsection A Loop with an Incrementing Counter
9850 A loop is not useful unless it stops when it ought. Besides
9851 controlling a loop with a list, a common way of stopping a loop is to
9852 write the first argument as a test that returns false when the correct
9853 number of repetitions are complete. This means that the loop must
9854 have a counter---an expression that counts how many times the loop
9857 The test can be an expression such as @code{(< count desired-number)}
9858 which returns @code{t} for true if the value of @code{count} is less
9859 than the @code{desired-number} of repetitions and @code{nil} for false if
9860 the value of @code{count} is equal to or is greater than the
9861 @code{desired-number}. The expression that increments the count can be
9862 a simple @code{setq} such as @code{(setq count (1+ count))}, where
9863 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
9864 argument. (The expression @w{@code{(1+ count)}} has the same result as
9865 @w{@code{(+ count 1)}}, but is easier for a human to read.)
9868 The template for a @code{while} loop controlled by an incrementing
9869 counter looks like this:
9873 @var{set-count-to-initial-value}
9874 (while (< count desired-number) ; @r{true-or-false-test}
9876 (setq count (1+ count))) ; @r{incrementer}
9881 Note that you need to set the initial value of @code{count}; usually it
9885 * Incrementing Example:: Counting pebbles in a triangle.
9886 * Inc Example parts:: The parts of the function definition.
9887 * Inc Example altogether:: Putting the function definition together.
9890 @node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop
9891 @unnumberedsubsubsec Example with incrementing counter
9893 Suppose you are playing on the beach and decide to make a triangle of
9894 pebbles, putting one pebble in the first row, two in the second row,
9895 three in the third row and so on, like this:
9914 @bullet{} @bullet{} @bullet{}
9915 @bullet{} @bullet{} @bullet{} @bullet{}
9922 (About 2500 years ago, Pythagoras and others developed the beginnings of
9923 number theory by considering questions such as this.)
9925 Suppose you want to know how many pebbles you will need to make a
9926 triangle with 7 rows?
9928 Clearly, what you need to do is add up the numbers from 1 to 7. There
9929 are two ways to do this; start with the smallest number, one, and add up
9930 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
9931 number and add the list going down: 7, 6, 5, 4 and so on. Because both
9932 mechanisms illustrate common ways of writing @code{while} loops, we will
9933 create two examples, one counting up and the other counting down. In
9934 this first example, we will start with 1 and add 2, 3, 4 and so on.
9936 If you are just adding up a short list of numbers, the easiest way to do
9937 it is to add up all the numbers at once. However, if you do not know
9938 ahead of time how many numbers your list will have, or if you want to be
9939 prepared for a very long list, then you need to design your addition so
9940 that what you do is repeat a simple process many times instead of doing
9941 a more complex process once.
9943 For example, instead of adding up all the pebbles all at once, what you
9944 can do is add the number of pebbles in the first row, 1, to the number
9945 in the second row, 2, and then add the total of those two rows to the
9946 third row, 3. Then you can add the number in the fourth row, 4, to the
9947 total of the first three rows; and so on.
9949 The critical characteristic of the process is that each repetitive
9950 action is simple. In this case, at each step we add only two numbers,
9951 the number of pebbles in the row and the total already found. This
9952 process of adding two numbers is repeated again and again until the last
9953 row has been added to the total of all the preceding rows. In a more
9954 complex loop the repetitive action might not be so simple, but it will
9955 be simpler than doing everything all at once.
9957 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop
9958 @unnumberedsubsubsec The parts of the function definition
9960 The preceding analysis gives us the bones of our function definition:
9961 first, we will need a variable that we can call @code{total} that will
9962 be the total number of pebbles. This will be the value returned by
9965 Second, we know that the function will require an argument: this
9966 argument will be the total number of rows in the triangle. It can be
9967 called @code{number-of-rows}.
9969 Finally, we need a variable to use as a counter. We could call this
9970 variable @code{counter}, but a better name is @code{row-number}.
9971 That is because what the counter does is count rows, and a program
9972 should be written to be as understandable as possible.
9974 When the Lisp interpreter first starts evaluating the expressions in the
9975 function, the value of @code{total} should be set to zero, since we have
9976 not added anything to it. Then the function should add the number of
9977 pebbles in the first row to the total, and then add the number of
9978 pebbles in the second to the total, and then add the number of
9979 pebbles in the third row to the total, and so on, until there are no
9980 more rows left to add.
9982 Both @code{total} and @code{row-number} are used only inside the
9983 function, so they can be declared as local variables with @code{let}
9984 and given initial values. Clearly, the initial value for @code{total}
9985 should be 0. The initial value of @code{row-number} should be 1,
9986 since we start with the first row. This means that the @code{let}
9987 statement will look like this:
9997 After the internal variables are declared and bound to their initial
9998 values, we can begin the @code{while} loop. The expression that serves
9999 as the test should return a value of @code{t} for true so long as the
10000 @code{row-number} is less than or equal to the @code{number-of-rows}.
10001 (If the expression tests true only so long as the row number is less
10002 than the number of rows in the triangle, the last row will never be
10003 added to the total; hence the row number has to be either less than or
10004 equal to the number of rows.)
10007 @findex <= @r{(less than or equal)}
10008 Lisp provides the @code{<=} function that returns true if the value of
10009 its first argument is less than or equal to the value of its second
10010 argument and false otherwise. So the expression that the @code{while}
10011 will evaluate as its test should look like this:
10014 (<= row-number number-of-rows)
10017 The total number of pebbles can be found by repeatedly adding the number
10018 of pebbles in a row to the total already found. Since the number of
10019 pebbles in the row is equal to the row number, the total can be found by
10020 adding the row number to the total. (Clearly, in a more complex
10021 situation, the number of pebbles in the row might be related to the row
10022 number in a more complicated way; if this were the case, the row number
10023 would be replaced by the appropriate expression.)
10026 (setq total (+ total row-number))
10030 What this does is set the new value of @code{total} to be equal to the
10031 sum of adding the number of pebbles in the row to the previous total.
10033 After setting the value of @code{total}, the conditions need to be
10034 established for the next repetition of the loop, if there is one. This
10035 is done by incrementing the value of the @code{row-number} variable,
10036 which serves as a counter. After the @code{row-number} variable has
10037 been incremented, the true-or-false-test at the beginning of the
10038 @code{while} loop tests whether its value is still less than or equal to
10039 the value of the @code{number-of-rows} and if it is, adds the new value
10040 of the @code{row-number} variable to the @code{total} of the previous
10041 repetition of the loop.
10044 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
10045 @code{row-number} variable can be incremented with this expression:
10048 (setq row-number (1+ row-number))
10051 @node Inc Example altogether, , Inc Example parts, Incrementing Loop
10052 @unnumberedsubsubsec Putting the function definition together
10054 We have created the parts for the function definition; now we need to
10058 First, the contents of the @code{while} expression:
10062 (while (<= row-number number-of-rows) ; @r{true-or-false-test}
10063 (setq total (+ total row-number))
10064 (setq row-number (1+ row-number))) ; @r{incrementer}
10068 Along with the @code{let} expression varlist, this very nearly
10069 completes the body of the function definition. However, it requires
10070 one final element, the need for which is somewhat subtle.
10072 The final touch is to place the variable @code{total} on a line by
10073 itself after the @code{while} expression. Otherwise, the value returned
10074 by the whole function is the value of the last expression that is
10075 evaluated in the body of the @code{let}, and this is the value
10076 returned by the @code{while}, which is always @code{nil}.
10078 This may not be evident at first sight. It almost looks as if the
10079 incrementing expression is the last expression of the whole function.
10080 But that expression is part of the body of the @code{while}; it is the
10081 last element of the list that starts with the symbol @code{while}.
10082 Moreover, the whole of the @code{while} loop is a list within the body
10086 In outline, the function will look like this:
10090 (defun @var{name-of-function} (@var{argument-list})
10091 "@var{documentation}@dots{}"
10092 (let (@var{varlist})
10093 (while (@var{true-or-false-test})
10094 @var{body-of-while}@dots{} )
10095 @dots{} ) ; @r{Need final expression here.}
10099 The result of evaluating the @code{let} is what is going to be returned
10100 by the @code{defun} since the @code{let} is not embedded within any
10101 containing list, except for the @code{defun} as a whole. However, if
10102 the @code{while} is the last element of the @code{let} expression, the
10103 function will always return @code{nil}. This is not what we want!
10104 Instead, what we want is the value of the variable @code{total}. This
10105 is returned by simply placing the symbol as the last element of the list
10106 starting with @code{let}. It gets evaluated after the preceding
10107 elements of the list are evaluated, which means it gets evaluated after
10108 it has been assigned the correct value for the total.
10110 It may be easier to see this by printing the list starting with
10111 @code{let} all on one line. This format makes it evident that the
10112 @var{varlist} and @code{while} expressions are the second and third
10113 elements of the list starting with @code{let}, and the @code{total} is
10118 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
10123 Putting everything together, the @code{triangle} function definition
10128 (defun triangle (number-of-rows) ; @r{Version with}
10129 ; @r{ incrementing counter.}
10130 "Add up the number of pebbles in a triangle.
10131 The first row has one pebble, the second row two pebbles,
10132 the third row three pebbles, and so on.
10133 The argument is NUMBER-OF-ROWS."
10138 (while (<= row-number number-of-rows)
10139 (setq total (+ total row-number))
10140 (setq row-number (1+ row-number)))
10146 After you have installed @code{triangle} by evaluating the function, you
10147 can try it out. Here are two examples:
10158 The sum of the first four numbers is 10 and the sum of the first seven
10161 @node Decrementing Loop, , Incrementing Loop, while
10162 @comment node-name, next, previous, up
10163 @subsection Loop with a Decrementing Counter
10165 Another common way to write a @code{while} loop is to write the test
10166 so that it determines whether a counter is greater than zero. So long
10167 as the counter is greater than zero, the loop is repeated. But when
10168 the counter is equal to or less than zero, the loop is stopped. For
10169 this to work, the counter has to start out greater than zero and then
10170 be made smaller and smaller by a form that is evaluated
10173 The test will be an expression such as @code{(> counter 0)} which
10174 returns @code{t} for true if the value of @code{counter} is greater
10175 than zero, and @code{nil} for false if the value of @code{counter} is
10176 equal to or less than zero. The expression that makes the number
10177 smaller and smaller can be a simple @code{setq} such as @code{(setq
10178 counter (1- counter))}, where @code{1-} is a built-in function in
10179 Emacs Lisp that subtracts 1 from its argument.
10182 The template for a decrementing @code{while} loop looks like this:
10186 (while (> counter 0) ; @r{true-or-false-test}
10188 (setq counter (1- counter))) ; @r{decrementer}
10193 * Decrementing Example:: More pebbles on the beach.
10194 * Dec Example parts:: The parts of the function definition.
10195 * Dec Example altogether:: Putting the function definition together.
10198 @node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
10199 @unnumberedsubsubsec Example with decrementing counter
10201 To illustrate a loop with a decrementing counter, we will rewrite the
10202 @code{triangle} function so the counter decreases to zero.
10204 This is the reverse of the earlier version of the function. In this
10205 case, to find out how many pebbles are needed to make a triangle with
10206 3 rows, add the number of pebbles in the third row, 3, to the number
10207 in the preceding row, 2, and then add the total of those two rows to
10208 the row that precedes them, which is 1.
10210 Likewise, to find the number of pebbles in a triangle with 7 rows, add
10211 the number of pebbles in the seventh row, 7, to the number in the
10212 preceding row, which is 6, and then add the total of those two rows to
10213 the row that precedes them, which is 5, and so on. As in the previous
10214 example, each addition only involves adding two numbers, the total of
10215 the rows already added up and the number of pebbles in the row that is
10216 being added to the total. This process of adding two numbers is
10217 repeated again and again until there are no more pebbles to add.
10219 We know how many pebbles to start with: the number of pebbles in the
10220 last row is equal to the number of rows. If the triangle has seven
10221 rows, the number of pebbles in the last row is 7. Likewise, we know how
10222 many pebbles are in the preceding row: it is one less than the number in
10225 @node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop
10226 @unnumberedsubsubsec The parts of the function definition
10228 We start with three variables: the total number of rows in the
10229 triangle; the number of pebbles in a row; and the total number of
10230 pebbles, which is what we want to calculate. These variables can be
10231 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
10232 @code{total}, respectively.
10234 Both @code{total} and @code{number-of-pebbles-in-row} are used only
10235 inside the function and are declared with @code{let}. The initial
10236 value of @code{total} should, of course, be zero. However, the
10237 initial value of @code{number-of-pebbles-in-row} should be equal to
10238 the number of rows in the triangle, since the addition will start with
10242 This means that the beginning of the @code{let} expression will look
10248 (number-of-pebbles-in-row number-of-rows))
10253 The total number of pebbles can be found by repeatedly adding the number
10254 of pebbles in a row to the total already found, that is, by repeatedly
10255 evaluating the following expression:
10258 (setq total (+ total number-of-pebbles-in-row))
10262 After the @code{number-of-pebbles-in-row} is added to the @code{total},
10263 the @code{number-of-pebbles-in-row} should be decremented by one, since
10264 the next time the loop repeats, the preceding row will be
10265 added to the total.
10267 The number of pebbles in a preceding row is one less than the number of
10268 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
10269 used to compute the number of pebbles in the preceding row. This can be
10270 done with the following expression:
10274 (setq number-of-pebbles-in-row
10275 (1- number-of-pebbles-in-row))
10279 Finally, we know that the @code{while} loop should stop making repeated
10280 additions when there are no pebbles in a row. So the test for
10281 the @code{while} loop is simply:
10284 (while (> number-of-pebbles-in-row 0)
10287 @node Dec Example altogether, , Dec Example parts, Decrementing Loop
10288 @unnumberedsubsubsec Putting the function definition together
10290 We can put these expressions together to create a function definition
10291 that works. However, on examination, we find that one of the local
10292 variables is unneeded!
10295 The function definition looks like this:
10299 ;;; @r{First subtractive version.}
10300 (defun triangle (number-of-rows)
10301 "Add up the number of pebbles in a triangle."
10303 (number-of-pebbles-in-row number-of-rows))
10304 (while (> number-of-pebbles-in-row 0)
10305 (setq total (+ total number-of-pebbles-in-row))
10306 (setq number-of-pebbles-in-row
10307 (1- number-of-pebbles-in-row)))
10312 As written, this function works.
10314 However, we do not need @code{number-of-pebbles-in-row}.
10316 @cindex Argument as local variable
10317 When the @code{triangle} function is evaluated, the symbol
10318 @code{number-of-rows} will be bound to a number, giving it an initial
10319 value. That number can be changed in the body of the function as if
10320 it were a local variable, without any fear that such a change will
10321 effect the value of the variable outside of the function. This is a
10322 very useful characteristic of Lisp; it means that the variable
10323 @code{number-of-rows} can be used anywhere in the function where
10324 @code{number-of-pebbles-in-row} is used.
10327 Here is a second version of the function written a bit more cleanly:
10331 (defun triangle (number) ; @r{Second version.}
10332 "Return sum of numbers 1 through NUMBER inclusive."
10334 (while (> number 0)
10335 (setq total (+ total number))
10336 (setq number (1- number)))
10341 In brief, a properly written @code{while} loop will consist of three parts:
10345 A test that will return false after the loop has repeated itself the
10346 correct number of times.
10349 An expression the evaluation of which will return the value desired
10350 after being repeatedly evaluated.
10353 An expression to change the value passed to the true-or-false-test so
10354 that the test returns false after the loop has repeated itself the right
10358 @node dolist dotimes, Recursion, while, Loops & Recursion
10359 @comment node-name, next, previous, up
10360 @section Save your time: @code{dolist} and @code{dotimes}
10362 In addition to @code{while}, both @code{dolist} and @code{dotimes}
10363 provide for looping. Sometimes these are quicker to write than the
10364 equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, ,
10365 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
10367 @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a
10368 list': @code{dolist} automatically shortens the list each time it
10369 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
10370 each shorter version of the list to the first of its arguments.
10372 @code{dotimes} loops a specific number of times: you specify the number.
10379 @node dolist, dotimes, dolist dotimes, dolist dotimes
10380 @unnumberedsubsubsec The @code{dolist} Macro
10383 Suppose, for example, you want to reverse a list, so that
10384 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
10387 In practice, you would use the @code{reverse} function, like this:
10391 (setq animals '(gazelle giraffe lion tiger))
10399 Here is how you could reverse the list using a @code{while} loop:
10403 (setq animals '(gazelle giraffe lion tiger))
10405 (defun reverse-list-with-while (list)
10406 "Using while, reverse the order of LIST."
10407 (let (value) ; make sure list starts empty
10409 (setq value (cons (car list) value))
10410 (setq list (cdr list)))
10413 (reverse-list-with-while animals)
10419 And here is how you could use the @code{dolist} macro:
10423 (setq animals '(gazelle giraffe lion tiger))
10425 (defun reverse-list-with-dolist (list)
10426 "Using dolist, reverse the order of LIST."
10427 (let (value) ; make sure list starts empty
10428 (dolist (element list value)
10429 (setq value (cons element value)))))
10431 (reverse-list-with-dolist animals)
10437 In Info, you can place your cursor after the closing parenthesis of
10438 each expression and type @kbd{C-x C-e}; in each case, you should see
10441 (tiger lion giraffe gazelle)
10447 For this example, the existing @code{reverse} function is obviously best.
10448 The @code{while} loop is just like our first example (@pxref{Loop
10449 Example, , A @code{while} Loop and a List}). The @code{while} first
10450 checks whether the list has elements; if so, it constructs a new list
10451 by adding the first element of the list to the existing list (which in
10452 the first iteration of the loop is @code{nil}). Since the second
10453 element is prepended in front of the first element, and the third
10454 element is prepended in front of the second element, the list is reversed.
10456 In the expression using a @code{while} loop,
10457 the @w{@code{(setq list (cdr list))}}
10458 expression shortens the list, so the @code{while} loop eventually
10459 stops. In addition, it provides the @code{cons} expression with a new
10460 first element by creating a new and shorter list at each repetition of
10463 The @code{dolist} expression does very much the same as the
10464 @code{while} expression, except that the @code{dolist} macro does some
10465 of the work you have to do when writing a @code{while} expression.
10467 Like a @code{while} loop, a @code{dolist} loops. What is different is
10468 that it automatically shortens the list each time it loops --- it
10469 `@sc{cdr}s down the list' on its own --- and it automatically binds
10470 the @sc{car} of each shorter version of the list to the first of its
10473 In the example, the @sc{car} of each shorter version of the list is
10474 referred to using the symbol @samp{element}, the list itself is called
10475 @samp{list}, and the value returned is called @samp{value}. The
10476 remainder of the @code{dolist} expression is the body.
10478 The @code{dolist} expression binds the @sc{car} of each shorter
10479 version of the list to @code{element} and then evaluates the body of
10480 the expression; and repeats the loop. The result is returned in
10483 @node dotimes, , dolist, dolist dotimes
10484 @unnumberedsubsubsec The @code{dotimes} Macro
10487 The @code{dotimes} macro is similar to @code{dolist}, except that it
10488 loops a specific number of times.
10490 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
10491 and so forth each time around the loop, and the value of the third
10492 argument is returned. You need to provide the value of the second
10493 argument, which is how many times the macro loops.
10496 For example, the following binds the numbers from 0 up to, but not
10497 including, the number 3 to the first argument, @var{number}, and then
10498 constructs a list of the three numbers. (The first number is 0, the
10499 second number is 1, and the third number is 2; this makes a total of
10500 three numbers in all, starting with zero as the first number.)
10504 (let (value) ; otherwise a value is a void variable
10505 (dotimes (number 3 value)
10506 (setq value (cons number value))))
10513 @code{dotimes} returns @code{value}, so the way to use
10514 @code{dotimes} is to operate on some expression @var{number} number of
10515 times and then return the result, either as a list or an atom.
10518 Here is an example of a @code{defun} that uses @code{dotimes} to add
10519 up the number of pebbles in a triangle.
10523 (defun triangle-using-dotimes (number-of-rows)
10524 "Using dotimes, add up the number of pebbles in a triangle."
10525 (let ((total 0)) ; otherwise a total is a void variable
10526 (dotimes (number number-of-rows total)
10527 (setq total (+ total (1+ number))))))
10529 (triangle-using-dotimes 4)
10533 @node Recursion, Looping exercise, dolist dotimes, Loops & Recursion
10534 @comment node-name, next, previous, up
10538 A recursive function contains code that tells the Lisp interpreter to
10539 call a program that runs exactly like itself, but with slightly
10540 different arguments. The code runs exactly the same because it has
10541 the same name. However, even though the program has the same name, it
10542 is not the same entity. It is different. In the jargon, it is a
10543 different `instance'.
10545 Eventually, if the program is written correctly, the `slightly
10546 different arguments' will become sufficiently different from the first
10547 arguments that the final instance will stop.
10550 * Building Robots:: Same model, different serial number ...
10551 * Recursive Definition Parts:: Walk until you stop ...
10552 * Recursion with list:: Using a list as the test whether to recurse.
10553 * Recursive triangle function::
10554 * Recursion with cond::
10555 * Recursive Patterns:: Often used templates.
10556 * No Deferment:: Don't store up work ...
10557 * No deferment solution::
10560 @node Building Robots, Recursive Definition Parts, Recursion, Recursion
10561 @comment node-name, next, previous, up
10562 @subsection Building Robots: Extending the Metaphor
10563 @cindex Building robots
10564 @cindex Robots, building
10566 It is sometimes helpful to think of a running program as a robot that
10567 does a job. In doing its job, a recursive function calls on a second
10568 robot to help it. The second robot is identical to the first in every
10569 way, except that the second robot helps the first and has been
10570 passed different arguments than the first.
10572 In a recursive function, the second robot may call a third; and the
10573 third may call a fourth, and so on. Each of these is a different
10574 entity; but all are clones.
10576 Since each robot has slightly different instructions---the arguments
10577 will differ from one robot to the next---the last robot should know
10580 Let's expand on the metaphor in which a computer program is a robot.
10582 A function definition provides the blueprints for a robot. When you
10583 install a function definition, that is, when you evaluate a
10584 @code{defun} special form, you install the necessary equipment to
10585 build robots. It is as if you were in a factory, setting up an
10586 assembly line. Robots with the same name are built according to the
10587 same blueprints. So they have, as it were, the same `model number',
10588 but a different `serial number'.
10590 We often say that a recursive function `calls itself'. What we mean
10591 is that the instructions in a recursive function cause the Lisp
10592 interpreter to run a different function that has the same name and
10593 does the same job as the first, but with different arguments.
10595 It is important that the arguments differ from one instance to the
10596 next; otherwise, the process will never stop.
10598 @node Recursive Definition Parts, Recursion with list, Building Robots, Recursion
10599 @comment node-name, next, previous, up
10600 @subsection The Parts of a Recursive Definition
10601 @cindex Parts of a Recursive Definition
10602 @cindex Recursive Definition Parts
10604 A recursive function typically contains a conditional expression which
10609 A true-or-false-test that determines whether the function is called
10610 again, here called the @dfn{do-again-test}.
10613 The name of the function. When this name is called, a new instance of
10614 the function---a new robot, as it were---is created and told what to do.
10617 An expression that returns a different value each time the function is
10618 called, here called the @dfn{next-step-expression}. Consequently, the
10619 argument (or arguments) passed to the new instance of the function
10620 will be different from that passed to the previous instance. This
10621 causes the conditional expression, the @dfn{do-again-test}, to test
10622 false after the correct number of repetitions.
10625 Recursive functions can be much simpler than any other kind of
10626 function. Indeed, when people first start to use them, they often look
10627 so mysteriously simple as to be incomprehensible. Like riding a
10628 bicycle, reading a recursive function definition takes a certain knack
10629 which is hard at first but then seems simple.
10632 There are several different common recursive patterns. A very simple
10633 pattern looks like this:
10637 (defun @var{name-of-recursive-function} (@var{argument-list})
10638 "@var{documentation}@dots{}"
10639 (if @var{do-again-test}
10641 (@var{name-of-recursive-function}
10642 @var{next-step-expression})))
10646 Each time a recursive function is evaluated, a new instance of it is
10647 created and told what to do. The arguments tell the instance what to do.
10649 An argument is bound to the value of the next-step-expression. Each
10650 instance runs with a different value of the next-step-expression.
10652 The value in the next-step-expression is used in the do-again-test.
10654 The value returned by the next-step-expression is passed to the new
10655 instance of the function, which evaluates it (or some
10656 transmogrification of it) to determine whether to continue or stop.
10657 The next-step-expression is designed so that the do-again-test returns
10658 false when the function should no longer be repeated.
10660 The do-again-test is sometimes called the @dfn{stop condition},
10661 since it stops the repetitions when it tests false.
10663 @node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion
10664 @comment node-name, next, previous, up
10665 @subsection Recursion with a List
10667 The example of a @code{while} loop that printed the elements of a list
10668 of numbers can be written recursively. Here is the code, including
10669 an expression to set the value of the variable @code{animals} to a list.
10671 If you are using Emacs 20 or before, this example must be copied to
10672 the @file{*scratch*} buffer and each expression must be evaluated
10673 there. Use @kbd{C-u C-x C-e} to evaluate the
10674 @code{(print-elements-recursively animals)} expression so that the
10675 results are printed in the buffer; otherwise the Lisp interpreter will
10676 try to squeeze the results into the one line of the echo area.
10678 Also, place your cursor immediately after the last closing parenthesis
10679 of the @code{print-elements-recursively} function, before the comment.
10680 Otherwise, the Lisp interpreter will try to evaluate the comment.
10682 If you are using Emacs 21 or later, you can evaluate this expression
10685 @findex print-elements-recursively
10688 (setq animals '(gazelle giraffe lion tiger))
10690 (defun print-elements-recursively (list)
10691 "Print each element of LIST on a line of its own.
10693 (if list ; @r{do-again-test}
10695 (print (car list)) ; @r{body}
10696 (print-elements-recursively ; @r{recursive call}
10697 (cdr list))))) ; @r{next-step-expression}
10699 (print-elements-recursively animals)
10703 The @code{print-elements-recursively} function first tests whether
10704 there is any content in the list; if there is, the function prints the
10705 first element of the list, the @sc{car} of the list. Then the
10706 function `invokes itself', but gives itself as its argument, not the
10707 whole list, but the second and subsequent elements of the list, the
10708 @sc{cdr} of the list.
10710 Put another way, if the list is not empty, the function invokes
10711 another instance of code that is similar to the initial code, but is a
10712 different thread of execution, with different arguments than the first
10715 Put in yet another way, if the list is not empty, the first robot
10716 assemblies a second robot and tells it what to do; the second robot is
10717 a different individual from the first, but is the same model.
10719 When the second evaluation occurs, the @code{if} expression is
10720 evaluated and if true, prints the first element of the list it
10721 receives as its argument (which is the second element of the original
10722 list). Then the function `calls itself' with the @sc{cdr} of the list
10723 it is invoked with, which (the second time around) is the @sc{cdr} of
10724 the @sc{cdr} of the original list.
10726 Note that although we say that the function `calls itself', what we
10727 mean is that the Lisp interpreter assembles and instructs a new
10728 instance of the program. The new instance is a clone of the first,
10729 but is a separate individual.
10731 Each time the function `invokes itself', it invokes itself on a
10732 shorter version of the original list. It creates a new instance that
10733 works on a shorter list.
10735 Eventually, the function invokes itself on an empty list. It creates
10736 a new instance whose argument is @code{nil}. The conditional expression
10737 tests the value of @code{list}. Since the value of @code{list} is
10738 @code{nil}, the @code{if} expression tests false so the then-part is
10739 not evaluated. The function as a whole then returns @code{nil}.
10742 When you evaluate @code{(print-elements-recursively animals)} in the
10743 @file{*scratch*} buffer, you see this result:
10758 @node Recursive triangle function, Recursion with cond, Recursion with list, Recursion
10759 @comment node-name, next, previous, up
10760 @subsection Recursion in Place of a Counter
10761 @findex triangle-recursively
10764 The @code{triangle} function described in a previous section can also
10765 be written recursively. It looks like this:
10769 (defun triangle-recursively (number)
10770 "Return the sum of the numbers 1 through NUMBER inclusive.
10772 (if (= number 1) ; @r{do-again-test}
10774 (+ number ; @r{else-part}
10775 (triangle-recursively ; @r{recursive call}
10776 (1- number))))) ; @r{next-step-expression}
10778 (triangle-recursively 7)
10783 You can install this function by evaluating it and then try it by
10784 evaluating @code{(triangle-recursively 7)}. (Remember to put your
10785 cursor immediately after the last parenthesis of the function
10786 definition, before the comment.) The function evaluates to 28.
10788 To understand how this function works, let's consider what happens in the
10789 various cases when the function is passed 1, 2, 3, or 4 as the value of
10793 * Recursive Example arg of 1 or 2::
10794 * Recursive Example arg of 3 or 4::
10797 @node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function
10799 @unnumberedsubsubsec An argument of 1 or 2
10802 First, what happens if the value of the argument is 1?
10804 The function has an @code{if} expression after the documentation
10805 string. It tests whether the value of @code{number} is equal to 1; if
10806 so, Emacs evaluates the then-part of the @code{if} expression, which
10807 returns the number 1 as the value of the function. (A triangle with
10808 one row has one pebble in it.)
10810 Suppose, however, that the value of the argument is 2. In this case,
10811 Emacs evaluates the else-part of the @code{if} expression.
10814 The else-part consists of an addition, the recursive call to
10815 @code{triangle-recursively} and a decrementing action; and it looks like
10819 (+ number (triangle-recursively (1- number)))
10822 When Emacs evaluates this expression, the innermost expression is
10823 evaluated first; then the other parts in sequence. Here are the steps
10827 @item Step 1 @w{ } Evaluate the innermost expression.
10829 The innermost expression is @code{(1- number)} so Emacs decrements the
10830 value of @code{number} from 2 to 1.
10832 @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function.
10834 The Lisp interpreter creates an individual instance of
10835 @code{triangle-recursively}. It does not matter that this function is
10836 contained within itself. Emacs passes the result Step 1 as the
10837 argument used by this instance of the @code{triangle-recursively}
10840 In this case, Emacs evaluates @code{triangle-recursively} with an
10841 argument of 1. This means that this evaluation of
10842 @code{triangle-recursively} returns 1.
10844 @item Step 3 @w{ } Evaluate the value of @code{number}.
10846 The variable @code{number} is the second element of the list that
10847 starts with @code{+}; its value is 2.
10849 @item Step 4 @w{ } Evaluate the @code{+} expression.
10851 The @code{+} expression receives two arguments, the first
10852 from the evaluation of @code{number} (Step 3) and the second from the
10853 evaluation of @code{triangle-recursively} (Step 2).
10855 The result of the addition is the sum of 2 plus 1, and the number 3 is
10856 returned, which is correct. A triangle with two rows has three
10860 @node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function
10861 @unnumberedsubsubsec An argument of 3 or 4
10863 Suppose that @code{triangle-recursively} is called with an argument of
10867 @item Step 1 @w{ } Evaluate the do-again-test.
10869 The @code{if} expression is evaluated first. This is the do-again
10870 test and returns false, so the else-part of the @code{if} expression
10871 is evaluated. (Note that in this example, the do-again-test causes
10872 the function to call itself when it tests false, not when it tests
10875 @item Step 2 @w{ } Evaluate the innermost expression of the else-part.
10877 The innermost expression of the else-part is evaluated, which decrements
10878 3 to 2. This is the next-step-expression.
10880 @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function.
10882 The number 2 is passed to the @code{triangle-recursively} function.
10884 We know what happens when Emacs evaluates @code{triangle-recursively} with
10885 an argument of 2. After going through the sequence of actions described
10886 earlier, it returns a value of 3. So that is what will happen here.
10888 @item Step 4 @w{ } Evaluate the addition.
10890 3 will be passed as an argument to the addition and will be added to the
10891 number with which the function was called, which is 3.
10895 The value returned by the function as a whole will be 6.
10897 Now that we know what will happen when @code{triangle-recursively} is
10898 called with an argument of 3, it is evident what will happen if it is
10899 called with an argument of 4:
10903 In the recursive call, the evaluation of
10906 (triangle-recursively (1- 4))
10911 will return the value of evaluating
10914 (triangle-recursively 3)
10918 which is 6 and this value will be added to 4 by the addition in the
10923 The value returned by the function as a whole will be 10.
10925 Each time @code{triangle-recursively} is evaluated, it evaluates a
10926 version of itself---a different instance of itself---with a smaller
10927 argument, until the argument is small enough so that it does not
10930 Note that this particular design for a recursive function
10931 requires that operations be deferred.
10933 Before @code{(triangle-recursively 7)} can calculate its answer, it
10934 must call @code{(triangle-recursively 6)}; and before
10935 @code{(triangle-recursively 6)} can calculate its answer, it must call
10936 @code{(triangle-recursively 5)}; and so on. That is to say, the
10937 calculation that @code{(triangle-recursively 7)} makes must be
10938 deferred until @code{(triangle-recursively 6)} makes its calculation;
10939 and @code{(triangle-recursively 6)} must defer until
10940 @code{(triangle-recursively 5)} completes; and so on.
10942 If each of these instances of @code{triangle-recursively} are thought
10943 of as different robots, the first robot must wait for the second to
10944 complete its job, which must wait until the third completes, and so
10947 There is a way around this kind of waiting, which we will discuss in
10948 @ref{No Deferment, , Recursion without Deferments}.
10950 @node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion
10951 @comment node-name, next, previous, up
10952 @subsection Recursion Example Using @code{cond}
10955 The version of @code{triangle-recursively} described earlier is written
10956 with the @code{if} special form. It can also be written using another
10957 special form called @code{cond}. The name of the special form
10958 @code{cond} is an abbreviation of the word @samp{conditional}.
10960 Although the @code{cond} special form is not used as often in the
10961 Emacs Lisp sources as @code{if}, it is used often enough to justify
10965 The template for a @code{cond} expression looks like this:
10975 where the @var{body} is a series of lists.
10978 Written out more fully, the template looks like this:
10983 (@var{first-true-or-false-test} @var{first-consequent})
10984 (@var{second-true-or-false-test} @var{second-consequent})
10985 (@var{third-true-or-false-test} @var{third-consequent})
10990 When the Lisp interpreter evaluates the @code{cond} expression, it
10991 evaluates the first element (the @sc{car} or true-or-false-test) of
10992 the first expression in a series of expressions within the body of the
10995 If the true-or-false-test returns @code{nil} the rest of that
10996 expression, the consequent, is skipped and the true-or-false-test of the
10997 next expression is evaluated. When an expression is found whose
10998 true-or-false-test returns a value that is not @code{nil}, the
10999 consequent of that expression is evaluated. The consequent can be one
11000 or more expressions. If the consequent consists of more than one
11001 expression, the expressions are evaluated in sequence and the value of
11002 the last one is returned. If the expression does not have a consequent,
11003 the value of the true-or-false-test is returned.
11005 If none of the true-or-false-tests test true, the @code{cond} expression
11006 returns @code{nil}.
11009 Written using @code{cond}, the @code{triangle} function looks like this:
11013 (defun triangle-using-cond (number)
11014 (cond ((<= number 0) 0)
11017 (+ number (triangle-using-cond (1- number))))))
11022 In this example, the @code{cond} returns 0 if the number is less than or
11023 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
11024 number (triangle-using-cond (1- number)))} if the number is greater than
11027 @node Recursive Patterns, No Deferment, Recursion with cond, Recursion
11028 @comment node-name, next, previous, up
11029 @subsection Recursive Patterns
11030 @cindex Recursive Patterns
11032 Here are three common recursive patterns. Each involves a list.
11033 Recursion does not need to involve lists, but Lisp is designed for lists
11034 and this provides a sense of its primal capabilities.
11042 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
11043 @comment node-name, next, previous, up
11044 @unnumberedsubsubsec Recursive Pattern: @emph{every}
11045 @cindex Every, type of recursive pattern
11046 @cindex Recursive pattern: every
11048 In the @code{every} recursive pattern, an action is performed on every
11052 The basic pattern is:
11056 If a list be empty, return @code{nil}.
11058 Else, act on the beginning of the list (the @sc{car} of the list)
11061 through a recursive call by the function on the rest (the
11062 @sc{cdr}) of the list,
11064 and, optionally, combine the acted-on element, using @code{cons},
11065 with the results of acting on the rest.
11074 (defun square-each (numbers-list)
11075 "Square each of a NUMBERS LIST, recursively."
11076 (if (not numbers-list) ; do-again-test
11079 (* (car numbers-list) (car numbers-list))
11080 (square-each (cdr numbers-list))))) ; next-step-expression
11084 (square-each '(1 2 3))
11091 If @code{numbers-list} is empty, do nothing. But if it has content,
11092 construct a list combining the square of the first number in the list
11093 with the result of the recursive call.
11095 (The example follows the pattern exactly: @code{nil} is returned if
11096 the numbers' list is empty. In practice, you would write the
11097 conditional so it carries out the action when the numbers' list is not
11100 The @code{print-elements-recursively} function (@pxref{Recursion with
11101 list, , Recursion with a List}) is another example of an @code{every}
11102 pattern, except in this case, rather than bring the results together
11103 using @code{cons}, we print each element of output.
11106 The @code{print-elements-recursively} function looks like this:
11110 (setq animals '(gazelle giraffe lion tiger))
11114 (defun print-elements-recursively (list)
11115 "Print each element of LIST on a line of its own.
11117 (if list ; @r{do-again-test}
11119 (print (car list)) ; @r{body}
11120 (print-elements-recursively ; @r{recursive call}
11121 (cdr list))))) ; @r{next-step-expression}
11123 (print-elements-recursively animals)
11128 The pattern for @code{print-elements-recursively} is:
11132 If the list be empty, do nothing.
11134 But if the list has at least one element,
11137 act on the beginning of the list (the @sc{car} of the list),
11139 and make a recursive call on the rest (the @sc{cdr}) of the list.
11143 @node Accumulate, Keep, Every, Recursive Patterns
11144 @comment node-name, next, previous, up
11145 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
11146 @cindex Accumulate, type of recursive pattern
11147 @cindex Recursive pattern: accumulate
11149 Another recursive pattern is called the @code{accumulate} pattern. In
11150 the @code{accumulate} recursive pattern, an action is performed on
11151 every element of a list and the result of that action is accumulated
11152 with the results of performing the action on the other elements.
11154 This is very like the `every' pattern using @code{cons}, except that
11155 @code{cons} is not used, but some other combiner.
11162 If a list be empty, return zero or some other constant.
11164 Else, act on the beginning of the list (the @sc{car} of the list),
11167 and combine that acted-on element, using @code{+} or
11168 some other combining function, with
11170 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11175 Here is an example:
11179 (defun add-elements (numbers-list)
11180 "Add the elements of NUMBERS-LIST together."
11181 (if (not numbers-list)
11183 (+ (car numbers-list) (add-elements (cdr numbers-list)))))
11187 (add-elements '(1 2 3 4))
11192 @xref{Files List, , Making a List of Files}, for an example of the
11193 accumulate pattern.
11195 @node Keep, , Accumulate, Recursive Patterns
11196 @comment node-name, next, previous, up
11197 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
11198 @cindex Keep, type of recursive pattern
11199 @cindex Recursive pattern: keep
11201 A third recursive pattern is called the @code{keep} pattern.
11202 In the @code{keep} recursive pattern, each element of a list is tested;
11203 the element is acted on and the results are kept only if the element
11206 Again, this is very like the `every' pattern, except the element is
11207 skipped unless it meets a criterion.
11210 The pattern has three parts:
11214 If a list be empty, return @code{nil}.
11216 Else, if the beginning of the list (the @sc{car} of the list) passes
11220 act on that element and combine it, using @code{cons} with
11222 a recursive call by the function on the rest (the @sc{cdr}) of the list.
11225 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
11229 skip on that element,
11231 and, recursively call the function on the rest (the @sc{cdr}) of the list.
11236 Here is an example that uses @code{cond}:
11240 (defun keep-three-letter-words (word-list)
11241 "Keep three letter words in WORD-LIST."
11243 ;; First do-again-test: stop-condition
11244 ((not word-list) nil)
11246 ;; Second do-again-test: when to act
11247 ((eq 3 (length (symbol-name (car word-list))))
11248 ;; combine acted-on element with recursive call on shorter list
11249 (cons (car word-list) (keep-three-letter-words (cdr word-list))))
11251 ;; Third do-again-test: when to skip element;
11252 ;; recursively call shorter list with next-step expression
11253 (t (keep-three-letter-words (cdr word-list)))))
11257 (keep-three-letter-words '(one two three four five six))
11258 @result{} (one two six)
11262 It goes without saying that you need not use @code{nil} as the test for
11263 when to stop; and you can, of course, combine these patterns.
11265 @node No Deferment, No deferment solution, Recursive Patterns, Recursion
11266 @subsection Recursion without Deferments
11267 @cindex Deferment in recursion
11268 @cindex Recursion without Deferments
11270 Let's consider again what happens with the @code{triangle-recursively}
11271 function. We will find that the intermediate calculations are
11272 deferred until all can be done.
11275 Here is the function definition:
11279 (defun triangle-recursively (number)
11280 "Return the sum of the numbers 1 through NUMBER inclusive.
11282 (if (= number 1) ; @r{do-again-test}
11284 (+ number ; @r{else-part}
11285 (triangle-recursively ; @r{recursive call}
11286 (1- number))))) ; @r{next-step-expression}
11290 What happens when we call this function with a argument of 7?
11292 The first instance of the @code{triangle-recursively} function adds
11293 the number 7 to the value returned by a second instance of
11294 @code{triangle-recursively}, an instance that has been passed an
11295 argument of 6. That is to say, the first calculation is:
11298 (+ 7 (triangle-recursively 6))
11302 The first instance of @code{triangle-recursively}---you may want to
11303 think of it as a little robot---cannot complete its job. It must hand
11304 off the calculation for @code{(triangle-recursively 6)} to a second
11305 instance of the program, to a second robot. This second individual is
11306 completely different from the first one; it is, in the jargon, a
11307 `different instantiation'. Or, put another way, it is a different
11308 robot. It is the same model as the first; it calculates triangle
11309 numbers recursively; but it has a different serial number.
11311 And what does @code{(triangle-recursively 6)} return? It returns the
11312 number 6 added to the value returned by evaluating
11313 @code{triangle-recursively} with an argument of 5. Using the robot
11314 metaphor, it asks yet another robot to help it.
11320 (+ 7 6 (triangle-recursively 5))
11324 And what happens next?
11327 (+ 7 6 5 (triangle-recursively 4))
11330 Each time @code{triangle-recursively} is called, except for the last
11331 time, it creates another instance of the program---another robot---and
11332 asks it to make a calculation.
11335 Eventually, the full addition is set up and performed:
11341 This design for the function defers the calculation of the first step
11342 until the second can be done, and defers that until the third can be
11343 done, and so on. Each deferment means the computer must remember what
11344 is being waited on. This is not a problem when there are only a few
11345 steps, as in this example. But it can be a problem when there are
11348 @node No deferment solution, , No Deferment, Recursion
11349 @subsection No Deferment Solution
11350 @cindex No deferment solution
11351 @cindex Defermentless solution
11352 @cindex Solution without deferment
11354 The solution to the problem of deferred operations is to write in a
11355 manner that does not defer operations@footnote{The phrase @dfn{tail
11356 recursive} is used to describe such a process, one that uses
11357 `constant space'.}. This requires
11358 writing to a different pattern, often one that involves writing two
11359 function definitions, an `initialization' function and a `helper'
11362 The `initialization' function sets up the job; the `helper' function
11366 Here are the two function definitions for adding up numbers. They are
11367 so simple, I find them hard to understand.
11371 (defun triangle-initialization (number)
11372 "Return the sum of the numbers 1 through NUMBER inclusive.
11373 This is the `initialization' component of a two function
11374 duo that uses recursion."
11375 (triangle-recursive-helper 0 0 number))
11381 (defun triangle-recursive-helper (sum counter number)
11382 "Return SUM, using COUNTER, through NUMBER inclusive.
11383 This is the `helper' component of a two function duo
11384 that uses recursion."
11385 (if (> counter number)
11387 (triangle-recursive-helper (+ sum counter) ; @r{sum}
11388 (1+ counter) ; @r{counter}
11389 number))) ; @r{number}
11394 Install both function definitions by evaluating them, then call
11395 @code{triangle-initialization} with 2 rows:
11399 (triangle-initialization 2)
11404 The `initialization' function calls the first instance of the `helper'
11405 function with three arguments: zero, zero, and a number which is the
11406 number of rows in the triangle.
11408 The first two arguments passed to the `helper' function are
11409 initialization values. These values are changed when
11410 @code{triangle-recursive-helper} invokes new instances.@footnote{The
11411 jargon is mildly confusing: @code{triangle-recursive-helper} uses a
11412 process that is iterative in a procedure that is recursive. The
11413 process is called iterative because the computer need only record the
11414 three values, @code{sum}, @code{counter}, and @code{number}; the
11415 procedure is recursive because the function `calls itself'. On the
11416 other hand, both the process and the procedure used by
11417 @code{triangle-recursively} are called recursive. The word
11418 `recursive' has different meanings in the two contexts.}
11420 Let's see what happens when we have a triangle that has one row. (This
11421 triangle will have one pebble in it!)
11424 @code{triangle-initialization} will call its helper with
11425 the arguments @w{@code{0 0 1}}. That function will run the conditional
11426 test whether @code{(> counter number)}:
11434 and find that the result is false, so it will invoke
11435 the then-part of the @code{if} clause:
11439 (triangle-recursive-helper
11440 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
11441 (1+ counter) ; @r{increment counter} @result{} @r{counter}
11442 number) ; @r{number stays the same}
11448 which will first compute:
11452 (triangle-recursive-helper (+ 0 0) ; @r{sum}
11453 (1+ 0) ; @r{counter}
11457 (triangle-recursive-helper 0 1 1)
11461 Again, @code{(> counter number)} will be false, so again, the Lisp
11462 interpreter will evaluate @code{triangle-recursive-helper}, creating a
11463 new instance with new arguments.
11466 This new instance will be;
11470 (triangle-recursive-helper
11471 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
11472 (1+ counter) ; @r{increment counter} @result{} @r{counter}
11473 number) ; @r{number stays the same}
11477 (triangle-recursive-helper 1 2 1)
11481 In this case, the @code{(> counter number)} test will be true! So the
11482 instance will return the value of the sum, which will be 1, as
11485 Now, let's pass @code{triangle-initialization} an argument
11486 of 2, to find out how many pebbles there are in a triangle with two rows.
11488 That function calls @code{(triangle-recursive-helper 0 0 2)}.
11491 In stages, the instances called will be:
11495 @r{sum counter number}
11496 (triangle-recursive-helper 0 1 2)
11498 (triangle-recursive-helper 1 2 2)
11500 (triangle-recursive-helper 3 3 2)
11504 When the last instance is called, the @code{(> counter number)} test
11505 will be true, so the instance will return the value of @code{sum},
11508 This kind of pattern helps when you are writing functions that can use
11509 many resources in a computer.
11512 @node Looping exercise, , Recursion, Loops & Recursion
11513 @section Looping Exercise
11517 Write a function similar to @code{triangle} in which each row has a
11518 value which is the square of the row number. Use a @code{while} loop.
11521 Write a function similar to @code{triangle} that multiplies instead of
11525 Rewrite these two functions recursively. Rewrite these functions
11528 @c comma in printed title causes problem in Info cross reference
11530 Write a function for Texinfo mode that creates an index entry at the
11531 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
11532 (In a Texinfo file, @samp{@@dfn} marks a definition. This book is
11533 written in Texinfo.)
11535 Many of the functions you will need are described in two of the
11536 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
11537 Text}, and @ref{Yanking, , Yanking Text Back}. If you use
11538 @code{forward-paragraph} to put the index entry at the beginning of
11539 the paragraph, you will have to use @w{@kbd{C-h f}}
11540 (@code{describe-function}) to find out how to make the command go
11543 For more information, see
11545 @ref{Indicating, , Indicating Definitions, texinfo}.
11548 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
11549 a Texinfo manual in the current directory. Or, if you are on the
11551 @uref{http://www.gnu.org/manual/texinfo-4.6/html_node/Indicating.html}
11554 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
11555 Documentation Format}.
11559 @node Regexp Search, Counting Words, Loops & Recursion, Top
11560 @comment node-name, next, previous, up
11561 @chapter Regular Expression Searches
11562 @cindex Searches, illustrating
11563 @cindex Regular expression searches
11564 @cindex Patterns, searching for
11565 @cindex Motion by sentence and paragraph
11566 @cindex Sentences, movement by
11567 @cindex Paragraphs, movement by
11569 Regular expression searches are used extensively in GNU Emacs. The
11570 two functions, @code{forward-sentence} and @code{forward-paragraph},
11571 illustrate these searches well. They use regular expressions to find
11572 where to move point. The phrase `regular expression' is often written
11575 Regular expression searches are described in @ref{Regexp Search, ,
11576 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
11577 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
11578 Manual}. In writing this chapter, I am presuming that you have at
11579 least a mild acquaintance with them. The major point to remember is
11580 that regular expressions permit you to search for patterns as well as
11581 for literal strings of characters. For example, the code in
11582 @code{forward-sentence} searches for the pattern of possible
11583 characters that could mark the end of a sentence, and moves point to
11586 Before looking at the code for the @code{forward-sentence} function, it
11587 is worth considering what the pattern that marks the end of a sentence
11588 must be. The pattern is discussed in the next section; following that
11589 is a description of the regular expression search function,
11590 @code{re-search-forward}. The @code{forward-sentence} function
11591 is described in the section following. Finally, the
11592 @code{forward-paragraph} function is described in the last section of
11593 this chapter. @code{forward-paragraph} is a complex function that
11594 introduces several new features.
11597 * sentence-end:: The regular expression for @code{sentence-end}.
11598 * re-search-forward:: Very similar to @code{search-forward}.
11599 * forward-sentence:: A straightforward example of regexp search.
11600 * forward-paragraph:: A somewhat complex example.
11601 * etags:: How to create your own @file{TAGS} table.
11603 * re-search Exercises::
11606 @node sentence-end, re-search-forward, Regexp Search, Regexp Search
11607 @comment node-name, next, previous, up
11608 @section The Regular Expression for @code{sentence-end}
11609 @findex sentence-end
11611 The symbol @code{sentence-end} is bound to the pattern that marks the
11612 end of a sentence. What should this regular expression be?
11614 Clearly, a sentence may be ended by a period, a question mark, or an
11615 exclamation mark. Indeed, only clauses that end with one of those three
11616 characters should be considered the end of a sentence. This means that
11617 the pattern should include the character set:
11623 However, we do not want @code{forward-sentence} merely to jump to a
11624 period, a question mark, or an exclamation mark, because such a character
11625 might be used in the middle of a sentence. A period, for example, is
11626 used after abbreviations. So other information is needed.
11628 According to convention, you type two spaces after every sentence, but
11629 only one space after a period, a question mark, or an exclamation mark in
11630 the body of a sentence. So a period, a question mark, or an exclamation
11631 mark followed by two spaces is a good indicator of an end of sentence.
11632 However, in a file, the two spaces may instead be a tab or the end of a
11633 line. This means that the regular expression should include these three
11634 items as alternatives.
11637 This group of alternatives will look like this:
11648 Here, @samp{$} indicates the end of the line, and I have pointed out
11649 where the tab and two spaces are inserted in the expression. Both are
11650 inserted by putting the actual characters into the expression.
11652 Two backslashes, @samp{\\}, are required before the parentheses and
11653 vertical bars: the first backslash quotes the following backslash in
11654 Emacs; and the second indicates that the following character, the
11655 parenthesis or the vertical bar, is special.
11658 Also, a sentence may be followed by one or more carriage returns, like
11669 Like tabs and spaces, a carriage return is inserted into a regular
11670 expression by inserting it literally. The asterisk indicates that the
11671 @key{RET} is repeated zero or more times.
11673 But a sentence end does not consist only of a period, a question mark or
11674 an exclamation mark followed by appropriate space: a closing quotation
11675 mark or a closing brace of some kind may precede the space. Indeed more
11676 than one such mark or brace may precede the space. These require a
11677 expression that looks like this:
11683 In this expression, the first @samp{]} is the first character in the
11684 expression; the second character is @samp{"}, which is preceded by a
11685 @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last
11686 three characters are @samp{'}, @samp{)}, and @samp{@}}.
11688 All this suggests what the regular expression pattern for matching the
11689 end of a sentence should be; and, indeed, if we evaluate
11690 @code{sentence-end} we find that it returns the following value:
11695 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
11703 (Note that here the @key{TAB}, two spaces, and @key{RET} are shown
11704 literally in the pattern.)
11706 This regular expression can be decyphered as follows:
11710 The first part of the pattern is the three characters, a period, a question
11711 mark and an exclamation mark, within square brackets. The pattern must
11712 begin with one or other of these characters.
11715 The second part of the pattern is the group of closing braces and
11716 quotation marks, which can appear zero or more times. These may follow
11717 the period, question mark or exclamation mark. In a regular expression,
11718 the backslash, @samp{\}, followed by the double quotation mark,
11719 @samp{"}, indicates the class of string-quote characters. Usually, the
11720 double quotation mark is the only character in this class. The
11721 asterisk, @samp{*}, indicates that the items in the previous group (the
11722 group surrounded by square brackets, @samp{[]}) may be repeated zero or
11725 @item \\($\\| \\| \\)
11726 The third part of the pattern is one or other of: either the end of a
11727 line, or two blank spaces, or a tab. The double back-slashes are used
11728 to prevent Emacs from reading the parentheses and vertical bars as part
11729 of the search pattern; the parentheses are used to mark the group and
11730 the vertical bars are used to indicated that the patterns to either side
11731 of them are alternatives. The dollar sign is used to indicate the end
11732 of a line and both the two spaces and the tab are each inserted as is to
11733 indicate what they are.
11736 Finally, the last part of the pattern indicates that the end of the line
11737 or the whitespace following the period, question mark or exclamation
11738 mark may, but need not, be followed by one or more carriage returns. In
11739 the pattern, the carriage return is inserted as an actual carriage
11740 return between square brackets but here it is shown as @key{RET}.
11745 @node re-search-forward, forward-sentence, sentence-end, Regexp Search
11746 @comment node-name, next, previous, up
11747 @section The @code{re-search-forward} Function
11748 @findex re-search-forward
11750 The @code{re-search-forward} function is very like the
11751 @code{search-forward} function. (@xref{search-forward, , The
11752 @code{search-forward} Function}.)
11754 @code{re-search-forward} searches for a regular expression. If the
11755 search is successful, it leaves point immediately after the last
11756 character in the target. If the search is backwards, it leaves point
11757 just before the first character in the target. You may tell
11758 @code{re-search-forward} to return @code{t} for true. (Moving point
11759 is therefore a `side effect'.)
11761 Like @code{search-forward}, the @code{re-search-forward} function takes
11766 The first argument is the regular expression that the function searches
11767 for. The regular expression will be a string between quotations marks.
11770 The optional second argument limits how far the function will search; it is a
11771 bound, which is specified as a position in the buffer.
11774 The optional third argument specifies how the function responds to
11775 failure: @code{nil} as the third argument causes the function to
11776 signal an error (and print a message) when the search fails; any other
11777 value causes it to return @code{nil} if the search fails and @code{t}
11778 if the search succeeds.
11781 The optional fourth argument is the repeat count. A negative repeat
11782 count causes @code{re-search-forward} to search backwards.
11786 The template for @code{re-search-forward} looks like this:
11790 (re-search-forward "@var{regular-expression}"
11791 @var{limit-of-search}
11792 @var{what-to-do-if-search-fails}
11793 @var{repeat-count})
11797 The second, third, and fourth arguments are optional. However, if you
11798 want to pass a value to either or both of the last two arguments, you
11799 must also pass a value to all the preceding arguments. Otherwise, the
11800 Lisp interpreter will mistake which argument you are passing the value
11804 In the @code{forward-sentence} function, the regular expression will be
11805 the value of the variable @code{sentence-end}, namely:
11809 "[.?!][]\"')@}]*\\($\\| \\| \\)[
11815 The limit of the search will be the end of the paragraph (since a
11816 sentence cannot go beyond a paragraph). If the search fails, the
11817 function will return @code{nil}; and the repeat count will be provided
11818 by the argument to the @code{forward-sentence} function.
11820 @node forward-sentence, forward-paragraph, re-search-forward, Regexp Search
11821 @comment node-name, next, previous, up
11822 @section @code{forward-sentence}
11823 @findex forward-sentence
11825 The command to move the cursor forward a sentence is a straightforward
11826 illustration of how to use regular expression searches in Emacs Lisp.
11827 Indeed, the function looks longer and more complicated than it is; this
11828 is because the function is designed to go backwards as well as forwards;
11829 and, optionally, over more than one sentence. The function is usually
11830 bound to the key command @kbd{M-e}.
11833 * Complete forward-sentence::
11834 * fwd-sentence while loops:: Two @code{while} loops.
11835 * fwd-sentence re-search:: A regular expression search.
11838 @node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
11840 @unnumberedsubsec Complete @code{forward-sentence} function definition
11844 Here is the code for @code{forward-sentence}:
11848 (defun forward-sentence (&optional arg)
11849 "Move forward to next sentence-end. With argument, repeat.
11850 With negative argument, move backward repeatedly to sentence-beginning.
11851 Sentence ends are identified by the value of sentence-end
11852 treated as a regular expression. Also, every paragraph boundary
11853 terminates sentences as well."
11857 (or arg (setq arg 1))
11860 (save-excursion (start-of-paragraph-text) (point))))
11861 (if (re-search-backward
11862 (concat sentence-end "[^ \t\n]") par-beg t)
11863 (goto-char (1- (match-end 0)))
11864 (goto-char par-beg)))
11865 (setq arg (1+ arg)))
11868 (save-excursion (end-of-paragraph-text) (point))))
11869 (if (re-search-forward sentence-end par-end t)
11870 (skip-chars-backward " \t\n")
11871 (goto-char par-end)))
11872 (setq arg (1- arg))))
11876 The function looks long at first sight and it is best to look at its
11877 skeleton first, and then its muscle. The way to see the skeleton is to
11878 look at the expressions that start in the left-most columns:
11882 (defun forward-sentence (&optional arg)
11883 "@var{documentation}@dots{}"
11885 (or arg (setq arg 1))
11887 @var{body-of-while-loop}
11889 @var{body-of-while-loop}
11893 This looks much simpler! The function definition consists of
11894 documentation, an @code{interactive} expression, an @code{or}
11895 expression, and @code{while} loops.
11897 Let's look at each of these parts in turn.
11899 We note that the documentation is thorough and understandable.
11901 The function has an @code{interactive "p"} declaration. This means
11902 that the processed prefix argument, if any, is passed to the
11903 function as its argument. (This will be a number.) If the function
11904 is not passed an argument (it is optional) then the argument
11905 @code{arg} will be bound to 1. When @code{forward-sentence} is called
11906 non-interactively without an argument, @code{arg} is bound to
11909 The @code{or} expression handles the prefix argument. What it does is
11910 either leave the value of @code{arg} as it is, but only if @code{arg}
11911 is bound to a value; or it sets the value of @code{arg} to 1, in the
11912 case when @code{arg} is bound to @code{nil}.
11914 @node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
11915 @unnumberedsubsec The @code{while} loops
11917 Two @code{while} loops follow the @code{or} expression. The first
11918 @code{while} has a true-or-false-test that tests true if the prefix
11919 argument for @code{forward-sentence} is a negative number. This is for
11920 going backwards. The body of this loop is similar to the body of the
11921 second @code{while} clause, but it is not exactly the same. We will
11922 skip this @code{while} loop and concentrate on the second @code{while}
11926 The second @code{while} loop is for moving point forward. Its skeleton
11931 (while (> arg 0) ; @r{true-or-false-test}
11933 (if (@var{true-or-false-test})
11936 (setq arg (1- arg)))) ; @code{while} @r{loop decrementer}
11940 The @code{while} loop is of the decrementing kind.
11941 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It
11942 has a true-or-false-test that tests true so long as the counter (in
11943 this case, the variable @code{arg}) is greater than zero; and it has a
11944 decrementer that subtracts 1 from the value of the counter every time
11947 If no prefix argument is given to @code{forward-sentence}, which is
11948 the most common way the command is used, this @code{while} loop will
11949 run once, since the value of @code{arg} will be 1.
11951 The body of the @code{while} loop consists of a @code{let} expression,
11952 which creates and binds a local variable, and has, as its body, an
11953 @code{if} expression.
11956 The body of the @code{while} loop looks like this:
11961 (save-excursion (end-of-paragraph-text) (point))))
11962 (if (re-search-forward sentence-end par-end t)
11963 (skip-chars-backward " \t\n")
11964 (goto-char par-end)))
11968 The @code{let} expression creates and binds the local variable
11969 @code{par-end}. As we shall see, this local variable is designed to
11970 provide a bound or limit to the regular expression search. If the
11971 search fails to find a proper sentence ending in the paragraph, it will
11972 stop on reaching the end of the paragraph.
11974 But first, let us examine how @code{par-end} is bound to the value of
11975 the end of the paragraph. What happens is that the @code{let} sets the
11976 value of @code{par-end} to the value returned when the Lisp interpreter
11977 evaluates the expression
11981 (save-excursion (end-of-paragraph-text) (point))
11986 In this expression, @code{(end-of-paragraph-text)} moves point to the
11987 end of the paragraph, @code{(point)} returns the value of point, and then
11988 @code{save-excursion} restores point to its original position. Thus,
11989 the @code{let} binds @code{par-end} to the value returned by the
11990 @code{save-excursion} expression, which is the position of the end of
11991 the paragraph. (The @code{(end-of-paragraph-text)} function uses
11992 @code{forward-paragraph}, which we will discuss shortly.)
11995 Emacs next evaluates the body of the @code{let}, which is an @code{if}
11996 expression that looks like this:
12000 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
12001 (skip-chars-backward " \t\n") ; @r{then-part}
12002 (goto-char par-end))) ; @r{else-part}
12006 The @code{if} tests whether its first argument is true and if so,
12007 evaluates its then-part; otherwise, the Emacs Lisp interpreter
12008 evaluates the else-part. The true-or-false-test of the @code{if}
12009 expression is the regular expression search.
12011 It may seem odd to have what looks like the `real work' of
12012 the @code{forward-sentence} function buried here, but this is a common
12013 way this kind of operation is carried out in Lisp.
12015 @node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence
12016 @unnumberedsubsec The regular expression search
12018 The @code{re-search-forward} function searches for the end of the
12019 sentence, that is, for the pattern defined by the @code{sentence-end}
12020 regular expression. If the pattern is found---if the end of the sentence is
12021 found---then the @code{re-search-forward} function does two things:
12025 The @code{re-search-forward} function carries out a side effect, which
12026 is to move point to the end of the occurrence found.
12029 The @code{re-search-forward} function returns a value of true. This is
12030 the value received by the @code{if}, and means that the search was
12035 The side effect, the movement of point, is completed before the
12036 @code{if} function is handed the value returned by the successful
12037 conclusion of the search.
12039 When the @code{if} function receives the value of true from a successful
12040 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
12041 which is the expression @code{(skip-chars-backward " \t\n")}. This
12042 expression moves backwards over any blank spaces, tabs or carriage
12043 returns until a printed character is found and then leaves point after
12044 the character. Since point has already been moved to the end of the
12045 pattern that marks the end of the sentence, this action leaves point
12046 right after the closing printed character of the sentence, which is
12049 On the other hand, if the @code{re-search-forward} function fails to
12050 find a pattern marking the end of the sentence, the function returns
12051 false. The false then causes the @code{if} to evaluate its third
12052 argument, which is @code{(goto-char par-end)}: it moves point to the
12053 end of the paragraph.
12055 Regular expression searches are exceptionally useful and the pattern
12056 illustrated by @code{re-search-forward}, in which the search is the
12057 test of an @code{if} expression, is handy. You will see or write code
12058 incorporating this pattern often.
12060 @node forward-paragraph, etags, forward-sentence, Regexp Search
12061 @comment node-name, next, previous, up
12062 @section @code{forward-paragraph}: a Goldmine of Functions
12063 @findex forward-paragraph
12065 The @code{forward-paragraph} function moves point forward to the end
12066 of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
12067 number of functions that are important in themselves, including
12068 @code{let*}, @code{match-beginning}, and @code{looking-at}.
12070 The function definition for @code{forward-paragraph} is considerably
12071 longer than the function definition for @code{forward-sentence}
12072 because it works with a paragraph, each line of which may begin with a
12075 A fill prefix consists of a string of characters that are repeated at
12076 the beginning of each line. For example, in Lisp code, it is a
12077 convention to start each line of a paragraph-long comment with
12078 @samp{;;; }. In Text mode, four blank spaces make up another common
12079 fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , ,
12080 emacs, The GNU Emacs Manual}, for more information about fill
12083 The existence of a fill prefix means that in addition to being able to
12084 find the end of a paragraph whose lines begin on the left-most
12085 column, the @code{forward-paragraph} function must be able to find the
12086 end of a paragraph when all or many of the lines in the buffer begin
12087 with the fill prefix.
12089 Moreover, it is sometimes practical to ignore a fill prefix that
12090 exists, especially when blank lines separate paragraphs.
12091 This is an added complication.
12094 * forward-paragraph in brief:: Key parts of the function definition.
12095 * fwd-para let:: The @code{let*} expression.
12096 * fwd-para while:: The forward motion @code{while} loop.
12097 * fwd-para between paragraphs:: Movement between paragraphs.
12098 * fwd-para within paragraph:: Movement within paragraphs.
12099 * fwd-para no fill prefix:: When there is no fill prefix.
12100 * fwd-para with fill prefix:: When there is a fill prefix.
12101 * fwd-para summary:: Summary of @code{forward-paragraph} code.
12104 @node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
12106 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
12109 Rather than print all of the @code{forward-paragraph} function, we
12110 will only print parts of it. Read without preparation, the function
12114 In outline, the function looks like this:
12118 (defun forward-paragraph (&optional arg)
12119 "@var{documentation}@dots{}"
12121 (or arg (setq arg 1))
12124 (while (< arg 0) ; @r{backward-moving-code}
12126 (setq arg (1+ arg)))
12127 (while (> arg 0) ; @r{forward-moving-code}
12129 (setq arg (1- arg)))))
12133 The first parts of the function are routine: the function's argument
12134 list consists of one optional argument. Documentation follows.
12136 The lower case @samp{p} in the @code{interactive} declaration means
12137 that the processed prefix argument, if any, is passed to the function.
12138 This will be a number, and is the repeat count of how many paragraphs
12139 point will move. The @code{or} expression in the next line handles
12140 the common case when no argument is passed to the function, which occurs
12141 if the function is called from other code rather than interactively.
12142 This case was described earlier. (@xref{forward-sentence, The
12143 @code{forward-sentence} function}.) Now we reach the end of the
12144 familiar part of this function.
12146 @node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph
12147 @unnumberedsubsec The @code{let*} expression
12149 The next line of the @code{forward-paragraph} function begins a
12150 @code{let*} expression. This is a different kind of expression than
12151 we have seen so far. The symbol is @code{let*} not @code{let}.
12153 The @code{let*} special form is like @code{let} except that Emacs sets
12154 each variable in sequence, one after another, and variables in the
12155 latter part of the varlist can make use of the values to which Emacs
12156 set variables in the earlier part of the varlist.
12158 In the @code{let*} expression in this function, Emacs binds two
12159 variables: @code{fill-prefix-regexp} and @code{paragraph-separate}.
12160 The value to which @code{paragraph-separate} is bound depends on the
12161 value of @code{fill-prefix-regexp}.
12164 Let's look at each in turn. The symbol @code{fill-prefix-regexp} is
12165 set to the value returned by evaluating the following list:
12170 (not (equal fill-prefix ""))
12171 (not paragraph-ignore-fill-prefix)
12172 (regexp-quote fill-prefix))
12177 This is an expression whose first element is the @code{and} special form.
12179 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
12180 function}), the @code{and} special form evaluates each of its
12181 arguments until one of the arguments returns a value of @code{nil}, in
12182 which case the @code{and} expression returns @code{nil}; however, if
12183 none of the arguments returns a value of @code{nil}, the value
12184 resulting from evaluating the last argument is returned. (Since such
12185 a value is not @code{nil}, it is considered true in Lisp.) In other
12186 words, an @code{and} expression returns a true value only if all its
12187 arguments are true.
12190 In this case, the variable @code{fill-prefix-regexp} is bound to a
12191 non-@code{nil} value only if the following four expressions produce a
12192 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
12193 @code{fill-prefix-regexp} is bound to @code{nil}.
12197 When this variable is evaluated, the value of the fill prefix, if any,
12198 is returned. If there is no fill prefix, this variable returns
12201 @item (not (equal fill-prefix "")
12202 This expression checks whether an existing fill prefix is an empty
12203 string, that is, a string with no characters in it. An empty string is
12204 not a useful fill prefix.
12206 @item (not paragraph-ignore-fill-prefix)
12207 This expression returns @code{nil} if the variable
12208 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
12209 true value such as @code{t}.
12211 @item (regexp-quote fill-prefix)
12212 This is the last argument to the @code{and} special form. If all the
12213 arguments to the @code{and} are true, the value resulting from
12214 evaluating this expression will be returned by the @code{and} expression
12215 and bound to the variable @code{fill-prefix-regexp},
12218 @findex regexp-quote
12220 The result of evaluating this @code{and} expression successfully is that
12221 @code{fill-prefix-regexp} will be bound to the value of
12222 @code{fill-prefix} as modified by the @code{regexp-quote} function.
12223 What @code{regexp-quote} does is read a string and return a regular
12224 expression that will exactly match the string and match nothing else.
12225 This means that @code{fill-prefix-regexp} will be set to a value that
12226 will exactly match the fill prefix if the fill prefix exists.
12227 Otherwise, the variable will be set to @code{nil}.
12229 The second local variable in the @code{let*} expression is
12230 @code{paragraph-separate}. It is bound to the value returned by
12231 evaluating the expression:
12235 (if fill-prefix-regexp
12236 (concat paragraph-separate
12237 "\\|^" fill-prefix-regexp "[ \t]*$")
12238 paragraph-separate)))
12242 This expression shows why @code{let*} rather than @code{let} was used.
12243 The true-or-false-test for the @code{if} depends on whether the variable
12244 @code{fill-prefix-regexp} evaluates to @code{nil} or some other value.
12246 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
12247 the else-part of the @code{if} expression and binds
12248 @code{paragraph-separate} to its local value.
12249 (@code{paragraph-separate} is a regular expression that matches what
12250 separates paragraphs.)
12252 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
12253 the then-part of the @code{if} expression and binds
12254 @code{paragraph-separate} to a regular expression that includes the
12255 @code{fill-prefix-regexp} as part of the pattern.
12257 Specifically, @code{paragraph-separate} is set to the original value
12258 of the paragraph separate regular expression concatenated with an
12259 alternative expression that consists of the @code{fill-prefix-regexp}
12260 followed by a blank line. The @samp{^} indicates that the
12261 @code{fill-prefix-regexp} must begin a line, and the optional
12262 whitespace to the end of the line is defined by @w{@code{"[ \t]*$"}}.)
12263 The @samp{\\|} defines this portion of the regexp as an alternative to
12264 @code{paragraph-separate}.
12266 Now we get into the body of the @code{let*}. The first part of the body
12267 of the @code{let*} deals with the case when the function is given a
12268 negative argument and is therefore moving backwards. We will skip this
12271 @node fwd-para while, fwd-para between paragraphs, fwd-para let, forward-paragraph
12272 @unnumberedsubsec The forward motion @code{while} loop
12274 The second part of the body of the @code{let*} deals with forward
12275 motion. It is a @code{while} loop that repeats itself so long as the
12276 value of @code{arg} is greater than zero. In the most common use of
12277 the function, the value of the argument is 1, so the body of the
12278 @code{while} loop is evaluated exactly once, and the cursor moves
12279 forward one paragraph.
12281 This part handles three situations: when point is between paragraphs,
12282 when point is within a paragraph and there is a fill prefix, and
12283 when point is within a paragraph and there is no fill prefix.
12286 The @code{while} loop looks like this:
12291 (beginning-of-line)
12293 ;; @r{between paragraphs}
12294 (while (prog1 (and (not (eobp))
12295 (looking-at paragraph-separate))
12300 ;; @r{within paragraphs, with a fill prefix}
12301 (if fill-prefix-regexp
12302 ;; @r{There is a fill prefix; it overrides paragraph-start.}
12303 (while (and (not (eobp))
12304 (not (looking-at paragraph-separate))
12305 (looking-at fill-prefix-regexp))
12310 ;; @r{within paragraphs, no fill prefix}
12311 (if (re-search-forward paragraph-start nil t)
12312 (goto-char (match-beginning 0))
12313 (goto-char (point-max))))
12315 (setq arg (1- arg)))
12319 We can see immediately that this is a decrementing counter @code{while}
12320 loop, using the expression @code{(setq arg (1- arg))} as the decrementer.
12323 The body of the loop consists of three expressions:
12327 ;; @r{between paragraphs}
12328 (beginning-of-line)
12330 @var{body-of-while})
12334 ;; @r{within paragraphs, with fill prefix}
12335 (if @var{true-or-false-test}
12340 ;; @r{within paragraphs, no fill prefix}
12346 When the Emacs Lisp interpreter evaluates the body of the
12347 @code{while} loop, the first thing it does is evaluate the
12348 @code{(beginning-of-line)} expression and move point to the beginning
12349 of the line. Then there is an inner @code{while} loop. This
12350 @code{while} loop is designed to move the cursor out of the blank
12351 space between paragraphs, if it should happen to be there. Finally,
12352 there is an @code{if} expression that actually moves point to the end
12355 @node fwd-para between paragraphs, fwd-para within paragraph, fwd-para while, forward-paragraph
12356 @unnumberedsubsec Between paragraphs
12358 First, let us look at the inner @code{while} loop. This loop handles
12359 the case when point is between paragraphs; it uses three functions
12360 that are new to us: @code{prog1}, @code{eobp} and @code{looking-at}.
12367 @code{prog1} is similar to the @code{progn} special form,
12368 except that @code{prog1} evaluates its arguments in sequence and then
12369 returns the value of its first argument as the value of the whole
12370 expression. (@code{progn} returns the value of its last argument as the
12371 value of the expression.) The second and subsequent arguments to
12372 @code{prog1} are evaluated only for their side effects.
12375 @code{eobp} is an abbreviation of @samp{End Of Buffer P} and is a
12376 function that returns true if point is at the end of the buffer.
12379 @code{looking-at} is a function that returns true if the text following
12380 point matches the regular expression passed @code{looking-at} as its
12385 The @code{while} loop we are studying looks like this:
12389 (while (prog1 (and (not (eobp))
12390 (looking-at paragraph-separate))
12397 This is a @code{while} loop with no body! The true-or-false-test of the
12398 loop is the expression:
12402 (prog1 (and (not (eobp))
12403 (looking-at paragraph-separate))
12409 The first argument to the @code{prog1} is the @code{and} expression. It
12410 has within in it a test of whether point is at the end of the buffer and
12411 also a test of whether the pattern following point matches the regular
12412 expression for separating paragraphs.
12414 If the cursor is not at the end of the buffer and if the characters
12415 following the cursor mark the separation between two paragraphs, then
12416 the @code{and} expression is true. After evaluating the @code{and}
12417 expression, the Lisp interpreter evaluates the second argument to
12418 @code{prog1}, which is @code{forward-line}. This moves point forward
12419 one line. The value returned by the @code{prog1} however, is the
12420 value of its first argument, so the @code{while} loop continues so
12421 long as point is not at the end of the buffer and is between
12422 paragraphs. When, finally, point is moved to a paragraph, the
12423 @code{and} expression tests false. Note however, that the
12424 @code{forward-line} command is carried out anyhow. This means that
12425 when point is moved from between paragraphs to a paragraph, it is left
12426 at the beginning of the second line of the paragraph.
12428 @node fwd-para within paragraph, fwd-para no fill prefix, fwd-para between paragraphs, forward-paragraph
12429 @unnumberedsubsec Within paragraphs
12431 The next expression in the outer @code{while} loop is an @code{if}
12432 expression. The Lisp interpreter evaluates the then-part of the
12433 @code{if} when the @code{fill-prefix-regexp} variable has a value other
12434 than @code{nil}, and it evaluates the else-part when the value of
12435 @code{if fill-prefix-regexp} is @code{nil}, that is, when there is no
12438 @node fwd-para no fill prefix, fwd-para with fill prefix, fwd-para within paragraph, forward-paragraph
12439 @unnumberedsubsec No fill prefix
12441 It is simplest to look at the code for the case when there is no fill
12442 prefix first. This code consists of yet another inner @code{if}
12443 expression, and reads as follows:
12447 (if (re-search-forward paragraph-start nil t)
12448 (goto-char (match-beginning 0))
12449 (goto-char (point-max)))
12454 This expression actually does the work that most people think of as
12455 the primary purpose of the @code{forward-paragraph} command: it causes
12456 a regular expression search to occur that searches forward to the
12457 start of the next paragraph and if it is found, moves point there; but
12458 if the start of another paragraph if not found, it moves point to the
12459 end of the accessible region of the buffer.
12461 The only unfamiliar part of this is the use of @code{match-beginning}.
12462 This is another function that is new to us. The
12463 @code{match-beginning} function returns a number specifying the
12464 location of the start of the text that was matched by the last regular
12467 The @code{match-beginning} function is used here because of a
12468 characteristic of a forward search: a successful forward search,
12469 regardless of whether it is a plain search or a regular expression
12470 search, will move point to the end of the text that is found. In this
12471 case, a successful search will move point to the end of the pattern for
12472 @code{paragraph-start}, which will be the beginning of the next
12473 paragraph rather than the end of the current one.
12475 However, we want to put point at the end of the current paragraph, not at
12476 the beginning of the next one. The two positions may be different,
12477 because there may be several blank lines between paragraphs.
12479 @findex match-beginning
12480 When given an argument of 0, @code{match-beginning} returns the position
12481 that is the start of the text that the most recent regular
12482 expression search matched. In this case, the most recent regular
12483 expression search is the one looking for @code{paragraph-start}, so
12484 @code{match-beginning} returns the beginning position of the pattern,
12485 rather than the end of the pattern. The beginning position is the end
12488 (Incidentally, when passed a positive number as an argument, the
12489 @code{match-beginning} function will place point at that parenthesized
12490 expression in the last regular expression. It is a useful function.)
12492 @node fwd-para with fill prefix, fwd-para summary, fwd-para no fill prefix, forward-paragraph
12493 @unnumberedsubsec With a fill prefix
12495 The inner @code{if} expression just discussed is the else-part of an enclosing
12496 @code{if} expression which tests whether there is a fill prefix. If
12497 there is a fill prefix, the then-part of this @code{if} is evaluated.
12498 It looks like this:
12502 (while (and (not (eobp))
12503 (not (looking-at paragraph-separate))
12504 (looking-at fill-prefix-regexp))
12510 What this expression does is move point forward line by line so long
12511 as three conditions are true:
12515 Point is not at the end of the buffer.
12518 The text following point does not separate paragraphs.
12521 The pattern following point is the fill prefix regular expression.
12524 The last condition may be puzzling, until you remember that point was
12525 moved to the beginning of the line early in the @code{forward-paragraph}
12526 function. This means that if the text has a fill prefix, the
12527 @code{looking-at} function will see it.
12529 @node fwd-para summary, , fwd-para with fill prefix, forward-paragraph
12530 @unnumberedsubsec Summary
12532 In summary, when moving forward, the @code{forward-paragraph} function
12533 does the following:
12537 Move point to the beginning of the line.
12540 Skip over lines between paragraphs.
12543 Check whether there is a fill prefix, and if there is:
12548 Go forward line by line so long as the line is not a paragraph
12553 But if there is no fill prefix,
12558 Search for the next paragraph start pattern.
12561 Go to the beginning of the paragraph start pattern, which will be the
12562 end of the previous paragraph.
12565 Or else go to the end of the accessible portion of the buffer.
12570 For review, here is the code we have just been discussing, formatted
12576 (or arg (setq arg 1))
12578 (fill-prefix-regexp
12579 (and fill-prefix (not (equal fill-prefix ""))
12580 (not paragraph-ignore-fill-prefix)
12581 (regexp-quote fill-prefix)))
12585 (paragraph-separate
12586 (if fill-prefix-regexp
12587 (concat paragraph-separate
12591 paragraph-separate)))
12593 @var{omitted-backward-moving-code} @dots{}
12597 (while (> arg 0) ; @r{forward-moving-code}
12598 (beginning-of-line)
12600 (while (prog1 (and (not (eobp))
12601 (looking-at paragraph-separate))
12606 (if fill-prefix-regexp
12607 (while (and (not (eobp)) ; @r{then-part}
12608 (not (looking-at paragraph-separate))
12609 (looking-at fill-prefix-regexp))
12613 ; @r{else-part: the inner-if}
12614 (if (re-search-forward paragraph-start nil t)
12615 (goto-char (match-beginning 0))
12616 (goto-char (point-max))))
12618 (setq arg (1- arg))))) ; @r{decrementer}
12622 The full definition for the @code{forward-paragraph} function not only
12623 includes this code for going forwards, but also code for going backwards.
12625 If you are reading this inside of GNU Emacs and you want to see the
12626 whole function, you can type @kbd{C-h f} (@code{describe-function})
12627 and the name of the function. This gives you the function
12628 documentation and the name of the library containing the function's
12629 source. Place point over the name of the library and press the RET
12630 key; you will be taken directly to the source. (Be sure to install
12631 your sources! Without them, you are like a person who tries to drive
12632 a car with his eyes shut!)
12634 @c !!! again, 21.0.100 tags table location in this paragraph
12635 Or -- a good habit to get into -- you can type @kbd{M-.}
12636 (@code{find-tag}) and the name of the function when prompted for it.
12637 This will take you directly to the source. If the @code{find-tag}
12638 function first asks you for the name of a @file{TAGS} table, give it
12639 the name of the @file{TAGS} file such as
12640 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS}. (The exact path to your
12641 @file{TAGS} file depends on how your copy of Emacs was installed.)
12643 You can also create your own @file{TAGS} file for directories that
12646 @xref{etags, , Create Your Own @file{TAGS} File}.
12649 @node etags, Regexp Review, forward-paragraph, Regexp Search
12650 @section Create Your Own @file{TAGS} File
12652 @cindex @file{TAGS} file, create own
12654 The @kbd{M-.} (@code{find-tag}) command takes you directly to the
12655 source for a function, variable, node, or other source. The function
12656 depends on tags tables to tell it where to go.
12658 You often need to build and install tags tables yourself. They are
12659 not built automatically. A tags table is called a @file{TAGS} file;
12660 the name is in upper case letters.
12662 You can create a @file{TAGS} file by calling the @code{etags} program
12663 that comes as a part of the Emacs distribution. Usually, @code{etags}
12664 is compiled and installed when Emacs is built. (@code{etags} is not
12665 an Emacs Lisp function or a part of Emacs; it is a C program.)
12668 To create a @file{TAGS} file, first switch to the directory in which
12669 you want to create the file. In Emacs you can do this with the
12670 @kbd{M-x cd} command, or by visiting a file in the directory, or by
12671 listing the directory with @kbd{C-x d} (@code{dired}). Then run the
12672 compile command, with @w{@code{etags *.el}} as the command to execute
12675 M-x compile RET etags *.el RET
12679 to create a @file{TAGS} file.
12681 For example, if you have a large number of files in your
12682 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
12683 of which I load 12---you can create a @file{TAGS} file for the Emacs
12684 Lisp files in that directory.
12687 The @code{etags} program takes all the
12688 usual shell `wildcards'. For example, if you have two directories for
12689 which you want a single @file{TAGS file}, type
12690 @w{@code{etags *.el ../elisp/*.el}},
12691 where @file{../elisp/} is the second directory:
12694 M-x compile RET etags *.el ../elisp/*.el RET
12701 M-x compile RET etags --help RET
12705 to see a list of the options accepted by @code{etags} as well as a
12706 list of supported languages.
12708 The @code{etags} program handles more than 20 languages, including
12709 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, Java, LaTeX,
12710 Pascal, Perl, Python, Texinfo, makefiles, and most assemblers. The
12711 program has no switches for specifying the language; it recognizes the
12712 language in an input file according to its file name and contents.
12714 @file{etags} is very helpful when you are writing code yourself and
12715 want to refer back to functions you have already written. Just run
12716 @code{etags} again at intervals as you write new functions, so they
12717 become part of the @file{TAGS} file.
12719 If you think an appropriate @file{TAGS} file already exists for what
12720 you want, but do not know where it is, you can use the @code{locate}
12721 program to attempt to find it.
12723 Type @w{@kbd{M-x locate RET TAGS RET}} and Emacs will list for you the
12724 full path names of all your @file{TAGS} files. On my system, this
12725 command lists 34 @file{TAGS} files. On the other hand, a `plain
12726 vanilla' system I recently installed did not contain any @file{TAGS}
12729 If the tags table you want has been created, you can use the @code{M-x
12730 visit-tags-table} command to specify it. Otherwise, you will need to
12731 create the tag table yourself and then use @code{M-x
12734 @subsubheading Building Tags in the Emacs sources
12735 @cindex Building Tags in the Emacs sources
12736 @cindex Tags in the Emacs sources
12739 The GNU Emacs sources come with a @file{Makefile} that contains a
12740 sophisticated @code{etags} command that creates, collects, and merges
12741 tags tables from all over the Emacs sources and puts the information
12742 into one @file{TAGS} file in the @file{src/} directory below the top
12743 level of your Emacs source directory.
12746 To build this @file{TAGS} file, go to the top level of your Emacs
12747 source directory and run the compile command @code{make tags}:
12750 M-x compile RET make tags RET
12754 (The @code{make tags} command works well with the GNU Emacs sources,
12755 as well as with some other source packages.)
12757 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
12760 @node Regexp Review, re-search Exercises, etags, Regexp Search
12761 @comment node-name, next, previous, up
12764 Here is a brief summary of some recently introduced functions.
12768 Repeatedly evaluate the body of the expression so long as the first
12769 element of the body tests true. Then return @code{nil}. (The
12770 expression is evaluated only for its side effects.)
12779 (insert (format "foo is %d.\n" foo))
12780 (setq foo (1- foo))))
12782 @result{} foo is 2.
12788 (The @code{insert} function inserts its arguments at point; the
12789 @code{format} function returns a string formatted from its arguments
12790 the way @code{message} formats its arguments; @code{\n} produces a new
12793 @item re-search-forward
12794 Search for a pattern, and if the pattern is found, move point to rest
12798 Takes four arguments, like @code{search-forward}:
12802 A regular expression that specifies the pattern to search for.
12805 Optionally, the limit of the search.
12808 Optionally, what to do if the search fails, return @code{nil} or an
12812 Optionally, how many times to repeat the search; if negative, the
12813 search goes backwards.
12817 Bind some variables locally to particular values,
12818 and then evaluate the remaining arguments, returning the value of the
12819 last one. While binding the local variables, use the local values of
12820 variables bound earlier, if any.
12829 (message "`bar' is %d." bar))
12830 @result{} `bar' is 21.
12834 @item match-beginning
12835 Return the position of the start of the text found by the last regular
12839 Return @code{t} for true if the text after point matches the argument,
12840 which should be a regular expression.
12843 Return @code{t} for true if point is at the end of the accessible part
12844 of a buffer. The end of the accessible part is the end of the buffer
12845 if the buffer is not narrowed; it is the end of the narrowed part if
12846 the buffer is narrowed.
12849 Evaluate each argument in sequence and then return the value of the
12864 @node re-search Exercises, , Regexp Review, Regexp Search
12865 @section Exercises with @code{re-search-forward}
12869 Write a function to search for a regular expression that matches two
12870 or more blank lines in sequence.
12873 Write a function to search for duplicated words, such as `the the'.
12874 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
12875 Manual}, for information on how to write a regexp (a regular
12876 expression) to match a string that is composed of two identical
12877 halves. You can devise several regexps; some are better than others.
12878 The function I use is described in an appendix, along with several
12879 regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}.
12882 @node Counting Words, Words in a defun, Regexp Search, Top
12883 @chapter Counting: Repetition and Regexps
12884 @cindex Repetition for word counting
12885 @cindex Regular expressions for word counting
12887 Repetition and regular expression searches are powerful tools that you
12888 often use when you write code in Emacs Lisp. This chapter illustrates
12889 the use of regular expression searches through the construction of
12890 word count commands using @code{while} loops and recursion.
12893 * Why Count Words::
12894 * count-words-region:: Use a regexp, but find a problem.
12895 * recursive-count-words:: Start with case of no words in region.
12896 * Counting Exercise::
12899 @node Why Count Words, count-words-region, Counting Words, Counting Words
12901 @unnumberedsec Counting words
12904 The standard Emacs distribution contains a function for counting the
12905 number of lines within a region. However, there is no corresponding
12906 function for counting words.
12908 Certain types of writing ask you to count words. Thus, if you write
12909 an essay, you may be limited to 800 words; if you write a novel, you
12910 may discipline yourself to write 1000 words a day. It seems odd to me
12911 that Emacs lacks a word count command. Perhaps people use Emacs
12912 mostly for code or types of documentation that do not require word
12913 counts; or perhaps they restrict themselves to the operating system
12914 word count command, @code{wc}. Alternatively, people may follow
12915 the publishers' convention and compute a word count by dividing the
12916 number of characters in a document by five. In any event, here are
12917 commands to count words.
12919 @node count-words-region, recursive-count-words, Why Count Words, Counting Words
12920 @comment node-name, next, previous, up
12921 @section The @code{count-words-region} Function
12922 @findex count-words-region
12924 A word count command could count words in a line, paragraph, region,
12925 or buffer. What should the command cover? You could design the
12926 command to count the number of words in a complete buffer. However,
12927 the Emacs tradition encourages flexibility---you may want to count
12928 words in just a section, rather than all of a buffer. So it makes
12929 more sense to design the command to count the number of words in a
12930 region. Once you have a @code{count-words-region} command, you can,
12931 if you wish, count words in a whole buffer by marking it with @kbd{C-x
12932 h} (@code{mark-whole-buffer}).
12934 Clearly, counting words is a repetitive act: starting from the
12935 beginning of the region, you count the first word, then the second
12936 word, then the third word, and so on, until you reach the end of the
12937 region. This means that word counting is ideally suited to recursion
12938 or to a @code{while} loop.
12941 * Design count-words-region:: The definition using a @code{while} loop.
12942 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
12945 @node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
12947 @unnumberedsubsec Designing @code{count-words-region}
12950 First, we will implement the word count command with a @code{while}
12951 loop, then with recursion. The command will, of course, be
12955 The template for an interactive function definition is, as always:
12959 (defun @var{name-of-function} (@var{argument-list})
12960 "@var{documentation}@dots{}"
12961 (@var{interactive-expression}@dots{})
12966 What we need to do is fill in the slots.
12968 The name of the function should be self-explanatory and similar to the
12969 existing @code{count-lines-region} name. This makes the name easier
12970 to remember. @code{count-words-region} is a good choice.
12972 The function counts words within a region. This means that the
12973 argument list must contain symbols that are bound to the two
12974 positions, the beginning and end of the region. These two positions
12975 can be called @samp{beginning} and @samp{end} respectively. The first
12976 line of the documentation should be a single sentence, since that is
12977 all that is printed as documentation by a command such as
12978 @code{apropos}. The interactive expression will be of the form
12979 @samp{(interactive "r")}, since that will cause Emacs to pass the
12980 beginning and end of the region to the function's argument list. All
12983 The body of the function needs to be written to do three tasks:
12984 first, to set up conditions under which the @code{while} loop can
12985 count words, second, to run the @code{while} loop, and third, to send
12986 a message to the user.
12988 When a user calls @code{count-words-region}, point may be at the
12989 beginning or the end of the region. However, the counting process
12990 must start at the beginning of the region. This means we will want
12991 to put point there if it is not already there. Executing
12992 @code{(goto-char beginning)} ensures this. Of course, we will want to
12993 return point to its expected position when the function finishes its
12994 work. For this reason, the body must be enclosed in a
12995 @code{save-excursion} expression.
12997 The central part of the body of the function consists of a
12998 @code{while} loop in which one expression jumps point forward word by
12999 word, and another expression counts those jumps. The true-or-false-test
13000 of the @code{while} loop should test true so long as point should jump
13001 forward, and false when point is at the end of the region.
13003 We could use @code{(forward-word 1)} as the expression for moving point
13004 forward word by word, but it is easier to see what Emacs identifies as a
13005 `word' if we use a regular expression search.
13007 A regular expression search that finds the pattern for which it is
13008 searching leaves point after the last character matched. This means
13009 that a succession of successful word searches will move point forward
13012 As a practical matter, we want the regular expression search to jump
13013 over whitespace and punctuation between words as well as over the
13014 words themselves. A regexp that refuses to jump over interword
13015 whitespace would never jump more than one word! This means that
13016 the regexp should include the whitespace and punctuation that follows
13017 a word, if any, as well as the word itself. (A word may end a buffer
13018 and not have any following whitespace or punctuation, so that part of
13019 the regexp must be optional.)
13021 Thus, what we want for the regexp is a pattern defining one or more
13022 word constituent characters followed, optionally, by one or more
13023 characters that are not word constituents. The regular expression for
13031 The buffer's syntax table determines which characters are and are not
13032 word constituents. (@xref{Syntax, , What Constitutes a Word or
13033 Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The
13034 Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, ,
13035 Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
13038 The search expression looks like this:
13041 (re-search-forward "\\w+\\W*")
13045 (Note that paired backslashes precede the @samp{w} and @samp{W}. A
13046 single backslash has special meaning to the Emacs Lisp interpreter. It
13047 indicates that the following character is interpreted differently than
13048 usual. For example, the two characters, @samp{\n}, stand for
13049 @samp{newline}, rather than for a backslash followed by @samp{n}. Two
13050 backslashes in a row stand for an ordinary, `unspecial' backslash.)
13052 We need a counter to count how many words there are; this variable
13053 must first be set to 0 and then incremented each time Emacs goes
13054 around the @code{while} loop. The incrementing expression is simply:
13057 (setq count (1+ count))
13060 Finally, we want to tell the user how many words there are in the
13061 region. The @code{message} function is intended for presenting this
13062 kind of information to the user. The message has to be phrased so
13063 that it reads properly regardless of how many words there are in the
13064 region: we don't want to say that ``there are 1 words in the region''.
13065 The conflict between singular and plural is ungrammatical. We can
13066 solve this problem by using a conditional expression that evaluates
13067 different messages depending on the number of words in the region.
13068 There are three possibilities: no words in the region, one word in the
13069 region, and more than one word. This means that the @code{cond}
13070 special form is appropriate.
13073 All this leads to the following function definition:
13077 ;;; @r{First version; has bugs!}
13078 (defun count-words-region (beginning end)
13079 "Print number of words in the region.
13080 Words are defined as at least one word-constituent
13081 character followed by at least one character that
13082 is not a word-constituent. The buffer's syntax
13083 table determines which characters these are."
13085 (message "Counting words in region ... ")
13089 ;;; @r{1. Set up appropriate conditions.}
13091 (goto-char beginning)
13096 ;;; @r{2. Run the} while @r{loop.}
13097 (while (< (point) end)
13098 (re-search-forward "\\w+\\W*")
13099 (setq count (1+ count)))
13103 ;;; @r{3. Send a message to the user.}
13104 (cond ((zerop count)
13106 "The region does NOT have any words."))
13109 "The region has 1 word."))
13112 "The region has %d words." count))))))
13117 As written, the function works, but not in all circumstances.
13119 @node Whitespace Bug, , Design count-words-region, count-words-region
13120 @comment node-name, next, previous, up
13121 @subsection The Whitespace Bug in @code{count-words-region}
13123 The @code{count-words-region} command described in the preceding
13124 section has two bugs, or rather, one bug with two manifestations.
13125 First, if you mark a region containing only whitespace in the middle
13126 of some text, the @code{count-words-region} command tells you that the
13127 region contains one word! Second, if you mark a region containing
13128 only whitespace at the end of the buffer or the accessible portion of
13129 a narrowed buffer, the command displays an error message that looks
13133 Search failed: "\\w+\\W*"
13136 If you are reading this in Info in GNU Emacs, you can test for these
13139 First, evaluate the function in the usual manner to install it.
13141 Here is a copy of the definition. Place your cursor after the closing
13142 parenthesis and type @kbd{C-x C-e} to install it.
13146 ;; @r{First version; has bugs!}
13147 (defun count-words-region (beginning end)
13148 "Print number of words in the region.
13149 Words are defined as at least one word-constituent character followed
13150 by at least one character that is not a word-constituent. The buffer's
13151 syntax table determines which characters these are."
13155 (message "Counting words in region ... ")
13159 ;;; @r{1. Set up appropriate conditions.}
13161 (goto-char beginning)
13166 ;;; @r{2. Run the} while @r{loop.}
13167 (while (< (point) end)
13168 (re-search-forward "\\w+\\W*")
13169 (setq count (1+ count)))
13173 ;;; @r{3. Send a message to the user.}
13174 (cond ((zerop count)
13175 (message "The region does NOT have any words."))
13176 ((= 1 count) (message "The region has 1 word."))
13177 (t (message "The region has %d words." count))))))
13183 If you wish, you can also install this keybinding by evaluating it:
13186 (global-set-key "\C-c=" 'count-words-region)
13189 To conduct the first test, set mark and point to the beginning and end
13190 of the following line and then type @kbd{C-c =} (or @kbd{M-x
13191 count-words-region} if you have not bound @kbd{C-c =}):
13198 Emacs will tell you, correctly, that the region has three words.
13200 Repeat the test, but place mark at the beginning of the line and place
13201 point just @emph{before} the word @samp{one}. Again type the command
13202 @kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you
13203 that the region has no words, since it is composed only of the
13204 whitespace at the beginning of the line. But instead Emacs tells you
13205 that the region has one word!
13207 For the third test, copy the sample line to the end of the
13208 @file{*scratch*} buffer and then type several spaces at the end of the
13209 line. Place mark right after the word @samp{three} and point at the
13210 end of line. (The end of the line will be the end of the buffer.)
13211 Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before.
13212 Again, Emacs should tell you that the region has no words, since it is
13213 composed only of the whitespace at the end of the line. Instead,
13214 Emacs displays an error message saying @samp{Search failed}.
13216 The two bugs stem from the same problem.
13218 Consider the first manifestation of the bug, in which the command
13219 tells you that the whitespace at the beginning of the line contains
13220 one word. What happens is this: The @code{M-x count-words-region}
13221 command moves point to the beginning of the region. The @code{while}
13222 tests whether the value of point is smaller than the value of
13223 @code{end}, which it is. Consequently, the regular expression search
13224 looks for and finds the first word. It leaves point after the word.
13225 @code{count} is set to one. The @code{while} loop repeats; but this
13226 time the value of point is larger than the value of @code{end}, the
13227 loop is exited; and the function displays a message saying the number
13228 of words in the region is one. In brief, the regular expression
13229 search looks for and finds the word even though it is outside
13232 In the second manifestation of the bug, the region is whitespace at
13233 the end of the buffer. Emacs says @samp{Search failed}. What happens
13234 is that the true-or-false-test in the @code{while} loop tests true, so
13235 the search expression is executed. But since there are no more words
13236 in the buffer, the search fails.
13238 In both manifestations of the bug, the search extends or attempts to
13239 extend outside of the region.
13241 The solution is to limit the search to the region---this is a fairly
13242 simple action, but as you may have come to expect, it is not quite as
13243 simple as you might think.
13245 As we have seen, the @code{re-search-forward} function takes a search
13246 pattern as its first argument. But in addition to this first,
13247 mandatory argument, it accepts three optional arguments. The optional
13248 second argument bounds the search. The optional third argument, if
13249 @code{t}, causes the function to return @code{nil} rather than signal
13250 an error if the search fails. The optional fourth argument is a
13251 repeat count. (In Emacs, you can see a function's documentation by
13252 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
13254 In the @code{count-words-region} definition, the value of the end of
13255 the region is held by the variable @code{end} which is passed as an
13256 argument to the function. Thus, we can add @code{end} as an argument
13257 to the regular expression search expression:
13260 (re-search-forward "\\w+\\W*" end)
13263 However, if you make only this change to the @code{count-words-region}
13264 definition and then test the new version of the definition on a
13265 stretch of whitespace, you will receive an error message saying
13266 @samp{Search failed}.
13268 What happens is this: the search is limited to the region, and fails
13269 as you expect because there are no word-constituent characters in the
13270 region. Since it fails, we receive an error message. But we do not
13271 want to receive an error message in this case; we want to receive the
13272 message that "The region does NOT have any words."
13274 The solution to this problem is to provide @code{re-search-forward}
13275 with a third argument of @code{t}, which causes the function to return
13276 @code{nil} rather than signal an error if the search fails.
13278 However, if you make this change and try it, you will see the message
13279 ``Counting words in region ... '' and @dots{} you will keep on seeing
13280 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
13282 Here is what happens: the search is limited to the region, as before,
13283 and it fails because there are no word-constituent characters in the
13284 region, as expected. Consequently, the @code{re-search-forward}
13285 expression returns @code{nil}. It does nothing else. In particular,
13286 it does not move point, which it does as a side effect if it finds the
13287 search target. After the @code{re-search-forward} expression returns
13288 @code{nil}, the next expression in the @code{while} loop is evaluated.
13289 This expression increments the count. Then the loop repeats. The
13290 true-or-false-test tests true because the value of point is still less
13291 than the value of end, since the @code{re-search-forward} expression
13292 did not move point. @dots{} and the cycle repeats @dots{}
13294 The @code{count-words-region} definition requires yet another
13295 modification, to cause the true-or-false-test of the @code{while} loop
13296 to test false if the search fails. Put another way, there are two
13297 conditions that must be satisfied in the true-or-false-test before the
13298 word count variable is incremented: point must still be within the
13299 region and the search expression must have found a word to count.
13301 Since both the first condition and the second condition must be true
13302 together, the two expressions, the region test and the search
13303 expression, can be joined with an @code{and} special form and embedded in
13304 the @code{while} loop as the true-or-false-test, like this:
13307 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
13310 @c colon in printed section title causes problem in Info cross reference
13311 @c also trouble with an overfull hbox
13314 (For information about @code{and}, see
13315 @ref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
13320 (@xref{forward-paragraph}, for information about @code{and}.)
13323 The @code{re-search-forward} expression returns @code{t} if the search
13324 succeeds and as a side effect moves point. Consequently, as words are
13325 found, point is moved through the region. When the search
13326 expression fails to find another word, or when point reaches the end
13327 of the region, the true-or-false-test tests false, the @code{while}
13328 loop exists, and the @code{count-words-region} function displays one
13329 or other of its messages.
13331 After incorporating these final changes, the @code{count-words-region}
13332 works without bugs (or at least, without bugs that I have found!).
13333 Here is what it looks like:
13337 ;;; @r{Final version:} @code{while}
13338 (defun count-words-region (beginning end)
13339 "Print number of words in the region."
13341 (message "Counting words in region ... ")
13345 ;;; @r{1. Set up appropriate conditions.}
13348 (goto-char beginning)
13352 ;;; @r{2. Run the} while @r{loop.}
13353 (while (and (< (point) end)
13354 (re-search-forward "\\w+\\W*" end t))
13355 (setq count (1+ count)))
13359 ;;; @r{3. Send a message to the user.}
13360 (cond ((zerop count)
13362 "The region does NOT have any words."))
13365 "The region has 1 word."))
13368 "The region has %d words." count))))))
13372 @node recursive-count-words, Counting Exercise, count-words-region, Counting Words
13373 @comment node-name, next, previous, up
13374 @section Count Words Recursively
13375 @cindex Count words recursively
13376 @cindex Recursively counting words
13377 @cindex Words, counted recursively
13379 You can write the function for counting words recursively as well as
13380 with a @code{while} loop. Let's see how this is done.
13382 First, we need to recognize that the @code{count-words-region}
13383 function has three jobs: it sets up the appropriate conditions for
13384 counting to occur; it counts the words in the region; and it sends a
13385 message to the user telling how many words there are.
13387 If we write a single recursive function to do everything, we will
13388 receive a message for every recursive call. If the region contains 13
13389 words, we will receive thirteen messages, one right after the other.
13390 We don't want this! Instead, we must write two functions to do the
13391 job, one of which (the recursive function) will be used inside of the
13392 other. One function will set up the conditions and display the
13393 message; the other will return the word count.
13395 Let us start with the function that causes the message to be displayed.
13396 We can continue to call this @code{count-words-region}.
13398 This is the function that the user will call. It will be interactive.
13399 Indeed, it will be similar to our previous versions of this
13400 function, except that it will call @code{recursive-count-words} to
13401 determine how many words are in the region.
13404 We can readily construct a template for this function, based on our
13409 ;; @r{Recursive version; uses regular expression search}
13410 (defun count-words-region (beginning end)
13411 "@var{documentation}@dots{}"
13412 (@var{interactive-expression}@dots{})
13416 ;;; @r{1. Set up appropriate conditions.}
13417 (@var{explanatory message})
13418 (@var{set-up functions}@dots{}
13422 ;;; @r{2. Count the words.}
13423 @var{recursive call}
13427 ;;; @r{3. Send a message to the user.}
13428 @var{message providing word count}))
13432 The definition looks straightforward, except that somehow the count
13433 returned by the recursive call must be passed to the message
13434 displaying the word count. A little thought suggests that this can be
13435 done by making use of a @code{let} expression: we can bind a variable
13436 in the varlist of a @code{let} expression to the number of words in
13437 the region, as returned by the recursive call; and then the
13438 @code{cond} expression, using binding, can display the value to the
13441 Often, one thinks of the binding within a @code{let} expression as
13442 somehow secondary to the `primary' work of a function. But in this
13443 case, what you might consider the `primary' job of the function,
13444 counting words, is done within the @code{let} expression.
13447 Using @code{let}, the function definition looks like this:
13451 (defun count-words-region (beginning end)
13452 "Print number of words in the region."
13457 ;;; @r{1. Set up appropriate conditions.}
13458 (message "Counting words in region ... ")
13460 (goto-char beginning)
13464 ;;; @r{2. Count the words.}
13465 (let ((count (recursive-count-words end)))
13469 ;;; @r{3. Send a message to the user.}
13470 (cond ((zerop count)
13472 "The region does NOT have any words."))
13475 "The region has 1 word."))
13478 "The region has %d words." count))))))
13482 Next, we need to write the recursive counting function.
13484 A recursive function has at least three parts: the `do-again-test', the
13485 `next-step-expression', and the recursive call.
13487 The do-again-test determines whether the function will or will not be
13488 called again. Since we are counting words in a region and can use a
13489 function that moves point forward for every word, the do-again-test
13490 can check whether point is still within the region. The do-again-test
13491 should find the value of point and determine whether point is before,
13492 at, or after the value of the end of the region. We can use the
13493 @code{point} function to locate point. Clearly, we must pass the
13494 value of the end of the region to the recursive counting function as an
13497 In addition, the do-again-test should also test whether the search finds a
13498 word. If it does not, the function should not call itself again.
13500 The next-step-expression changes a value so that when the recursive
13501 function is supposed to stop calling itself, it stops. More
13502 precisely, the next-step-expression changes a value so that at the
13503 right time, the do-again-test stops the recursive function from
13504 calling itself again. In this case, the next-step-expression can be
13505 the expression that moves point forward, word by word.
13507 The third part of a recursive function is the recursive call.
13509 Somewhere, also, we also need a part that does the `work' of the
13510 function, a part that does the counting. A vital part!
13513 But already, we have an outline of the recursive counting function:
13517 (defun recursive-count-words (region-end)
13518 "@var{documentation}@dots{}"
13519 @var{do-again-test}
13520 @var{next-step-expression}
13521 @var{recursive call})
13525 Now we need to fill in the slots. Let's start with the simplest cases
13526 first: if point is at or beyond the end of the region, there cannot
13527 be any words in the region, so the function should return zero.
13528 Likewise, if the search fails, there are no words to count, so the
13529 function should return zero.
13531 On the other hand, if point is within the region and the search
13532 succeeds, the function should call itself again.
13535 Thus, the do-again-test should look like this:
13539 (and (< (point) region-end)
13540 (re-search-forward "\\w+\\W*" region-end t))
13544 Note that the search expression is part of the do-again-test---the
13545 function returns @code{t} if its search succeeds and @code{nil} if it
13546 fails. (@xref{Whitespace Bug, , The Whitespace Bug in
13547 @code{count-words-region}}, for an explanation of how
13548 @code{re-search-forward} works.)
13550 The do-again-test is the true-or-false test of an @code{if} clause.
13551 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
13552 clause should call the function again; but if it fails, the else-part
13553 should return zero since either point is outside the region or the
13554 search failed because there were no words to find.
13556 But before considering the recursive call, we need to consider the
13557 next-step-expression. What is it? Interestingly, it is the search
13558 part of the do-again-test.
13560 In addition to returning @code{t} or @code{nil} for the
13561 do-again-test, @code{re-search-forward} moves point forward as a side
13562 effect of a successful search. This is the action that changes the
13563 value of point so that the recursive function stops calling itself
13564 when point completes its movement through the region. Consequently,
13565 the @code{re-search-forward} expression is the next-step-expression.
13568 In outline, then, the body of the @code{recursive-count-words}
13569 function looks like this:
13573 (if @var{do-again-test-and-next-step-combined}
13575 @var{recursive-call-returning-count}
13581 How to incorporate the mechanism that counts?
13583 If you are not used to writing recursive functions, a question like
13584 this can be troublesome. But it can and should be approached
13587 We know that the counting mechanism should be associated in some way
13588 with the recursive call. Indeed, since the next-step-expression moves
13589 point forward by one word, and since a recursive call is made for
13590 each word, the counting mechanism must be an expression that adds one
13591 to the value returned by a call to @code{recursive-count-words}.
13593 Consider several cases:
13597 If there are two words in the region, the function should return
13598 a value resulting from adding one to the value returned when it counts
13599 the first word, plus the number returned when it counts the remaining
13600 words in the region, which in this case is one.
13603 If there is one word in the region, the function should return
13604 a value resulting from adding one to the value returned when it counts
13605 that word, plus the number returned when it counts the remaining
13606 words in the region, which in this case is zero.
13609 If there are no words in the region, the function should return zero.
13612 From the sketch we can see that the else-part of the @code{if} returns
13613 zero for the case of no words. This means that the then-part of the
13614 @code{if} must return a value resulting from adding one to the value
13615 returned from a count of the remaining words.
13618 The expression will look like this, where @code{1+} is a function that
13619 adds one to its argument.
13622 (1+ (recursive-count-words region-end))
13626 The whole @code{recursive-count-words} function will then look like
13631 (defun recursive-count-words (region-end)
13632 "@var{documentation}@dots{}"
13634 ;;; @r{1. do-again-test}
13635 (if (and (< (point) region-end)
13636 (re-search-forward "\\w+\\W*" region-end t))
13640 ;;; @r{2. then-part: the recursive call}
13641 (1+ (recursive-count-words region-end))
13643 ;;; @r{3. else-part}
13649 Let's examine how this works:
13651 If there are no words in the region, the else part of the @code{if}
13652 expression is evaluated and consequently the function returns zero.
13654 If there is one word in the region, the value of point is less than
13655 the value of @code{region-end} and the search succeeds. In this case,
13656 the true-or-false-test of the @code{if} expression tests true, and the
13657 then-part of the @code{if} expression is evaluated. The counting
13658 expression is evaluated. This expression returns a value (which will
13659 be the value returned by the whole function) that is the sum of one
13660 added to the value returned by a recursive call.
13662 Meanwhile, the next-step-expression has caused point to jump over the
13663 first (and in this case only) word in the region. This means that
13664 when @code{(recursive-count-words region-end)} is evaluated a second
13665 time, as a result of the recursive call, the value of point will be
13666 equal to or greater than the value of region end. So this time,
13667 @code{recursive-count-words} will return zero. The zero will be added
13668 to one, and the original evaluation of @code{recursive-count-words}
13669 will return one plus zero, which is one, which is the correct amount.
13671 Clearly, if there are two words in the region, the first call to
13672 @code{recursive-count-words} returns one added to the value returned
13673 by calling @code{recursive-count-words} on a region containing the
13674 remaining word---that is, it adds one to one, producing two, which is
13675 the correct amount.
13677 Similarly, if there are three words in the region, the first call to
13678 @code{recursive-count-words} returns one added to the value returned
13679 by calling @code{recursive-count-words} on a region containing the
13680 remaining two words---and so on and so on.
13684 With full documentation the two functions look like this:
13688 The recursive function:
13690 @findex recursive-count-words
13693 (defun recursive-count-words (region-end)
13694 "Number of words between point and REGION-END."
13698 ;;; @r{1. do-again-test}
13699 (if (and (< (point) region-end)
13700 (re-search-forward "\\w+\\W*" region-end t))
13704 ;;; @r{2. then-part: the recursive call}
13705 (1+ (recursive-count-words region-end))
13707 ;;; @r{3. else-part}
13718 ;;; @r{Recursive version}
13719 (defun count-words-region (beginning end)
13720 "Print number of words in the region.
13724 Words are defined as at least one word-constituent
13725 character followed by at least one character that is
13726 not a word-constituent. The buffer's syntax table
13727 determines which characters these are."
13731 (message "Counting words in region ... ")
13733 (goto-char beginning)
13734 (let ((count (recursive-count-words end)))
13737 (cond ((zerop count)
13739 "The region does NOT have any words."))
13743 (message "The region has 1 word."))
13746 "The region has %d words." count))))))
13750 @node Counting Exercise, , recursive-count-words, Counting Words
13751 @section Exercise: Counting Punctuation
13753 Using a @code{while} loop, write a function to count the number of
13754 punctuation marks in a region---period, comma, semicolon, colon,
13755 exclamation mark, and question mark. Do the same using recursion.
13757 @node Words in a defun, Readying a Graph, Counting Words, Top
13758 @chapter Counting Words in a @code{defun}
13759 @cindex Counting words in a @code{defun}
13760 @cindex Word counting in a @code{defun}
13762 Our next project is to count the number of words in a function
13763 definition. Clearly, this can be done using some variant of
13764 @code{count-word-region}. @xref{Counting Words, , Counting Words:
13765 Repetition and Regexps}. If we are just going to count the words in
13766 one definition, it is easy enough to mark the definition with the
13767 @kbd{C-M-h} (@code{mark-defun}) command, and then call
13768 @code{count-word-region}.
13770 However, I am more ambitious: I want to count the words and symbols in
13771 every definition in the Emacs sources and then print a graph that
13772 shows how many functions there are of each length: how many contain 40
13773 to 49 words or symbols, how many contain 50 to 59 words or symbols,
13774 and so on. I have often been curious how long a typical function is,
13775 and this will tell.
13778 * Divide and Conquer::
13779 * Words and Symbols:: What to count?
13780 * Syntax:: What constitutes a word or symbol?
13781 * count-words-in-defun:: Very like @code{count-words}.
13782 * Several defuns:: Counting several defuns in a file.
13783 * Find a File:: Do you want to look at a file?
13784 * lengths-list-file:: A list of the lengths of many definitions.
13785 * Several files:: Counting in definitions in different files.
13786 * Several files recursively:: Recursively counting in different files.
13787 * Prepare the data:: Prepare the data for display in a graph.
13790 @node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
13792 @unnumberedsec Divide and Conquer
13795 Described in one phrase, the histogram project is daunting; but
13796 divided into numerous small steps, each of which we can take one at a
13797 time, the project becomes less fearsome. Let us consider what the
13802 First, write a function to count the words in one definition. This
13803 includes the problem of handling symbols as well as words.
13806 Second, write a function to list the numbers of words in each function
13807 in a file. This function can use the @code{count-words-in-defun}
13811 Third, write a function to list the numbers of words in each function
13812 in each of several files. This entails automatically finding the
13813 various files, switching to them, and counting the words in the
13814 definitions within them.
13817 Fourth, write a function to convert the list of numbers that we
13818 created in step three to a form that will be suitable for printing as
13822 Fifth, write a function to print the results as a graph.
13825 This is quite a project! But if we take each step slowly, it will not
13828 @node Words and Symbols, Syntax, Divide and Conquer, Words in a defun
13829 @section What to Count?
13830 @cindex Words and symbols in defun
13832 When we first start thinking about how to count the words in a
13833 function definition, the first question is (or ought to be) what are
13834 we going to count? When we speak of `words' with respect to a Lisp
13835 function definition, we are actually speaking, in large part, of
13836 `symbols'. For example, the following @code{multiply-by-seven}
13837 function contains the five symbols @code{defun},
13838 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In
13839 addition, in the documentation string, it contains the four words
13840 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The
13841 symbol @samp{number} is repeated, so the definition contains a total
13842 of ten words and symbols.
13846 (defun multiply-by-seven (number)
13847 "Multiply NUMBER by seven."
13853 However, if we mark the @code{multiply-by-seven} definition with
13854 @kbd{C-M-h} (@code{mark-defun}), and then call
13855 @code{count-words-region} on it, we will find that
13856 @code{count-words-region} claims the definition has eleven words, not
13857 ten! Something is wrong!
13859 The problem is twofold: @code{count-words-region} does not count the
13860 @samp{*} as a word, and it counts the single symbol,
13861 @code{multiply-by-seven}, as containing three words. The hyphens are
13862 treated as if they were interword spaces rather than intraword
13863 connectors: @samp{multiply-by-seven} is counted as if it were written
13864 @samp{multiply by seven}.
13866 The cause of this confusion is the regular expression search within
13867 the @code{count-words-region} definition that moves point forward word
13868 by word. In the canonical version of @code{count-words-region}, the
13876 This regular expression is a pattern defining one or more word
13877 constituent characters possibly followed by one or more characters
13878 that are not word constituents. What is meant by `word constituent
13879 characters' brings us to the issue of syntax, which is worth a section
13882 @node Syntax, count-words-in-defun, Words and Symbols, Words in a defun
13883 @section What Constitutes a Word or Symbol?
13884 @cindex Syntax categories and tables
13886 Emacs treats different characters as belonging to different
13887 @dfn{syntax categories}. For example, the regular expression,
13888 @samp{\\w+}, is a pattern specifying one or more @emph{word
13889 constituent} characters. Word constituent characters are members of
13890 one syntax category. Other syntax categories include the class of
13891 punctuation characters, such as the period and the comma, and the
13892 class of whitespace characters, such as the blank space and the tab
13893 character. (For more information, see @ref{Syntax, Syntax, The Syntax
13894 Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax
13895 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
13897 Syntax tables specify which characters belong to which categories.
13898 Usually, a hyphen is not specified as a `word constituent character'.
13899 Instead, it is specified as being in the `class of characters that are
13900 part of symbol names but not words.' This means that the
13901 @code{count-words-region} function treats it in the same way it treats
13902 an interword white space, which is why @code{count-words-region}
13903 counts @samp{multiply-by-seven} as three words.
13905 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
13906 one symbol: modify the syntax table or modify the regular expression.
13908 We could redefine a hyphen as a word constituent character by
13909 modifying the syntax table that Emacs keeps for each mode. This
13910 action would serve our purpose, except that a hyphen is merely the
13911 most common character within symbols that is not typically a word
13912 constituent character; there are others, too.
13914 Alternatively, we can redefine the regular expression used in the
13915 @code{count-words} definition so as to include symbols. This
13916 procedure has the merit of clarity, but the task is a little tricky.
13919 The first part is simple enough: the pattern must match ``at least one
13920 character that is a word or symbol constituent''. Thus:
13923 "\\(\\w\\|\\s_\\)+"
13927 The @samp{\\(} is the first part of the grouping construct that
13928 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
13929 by the @samp{\\|}. The @samp{\\w} matches any word-constituent
13930 character and the @samp{\\s_} matches any character that is part of a
13931 symbol name but not a word-constituent character. The @samp{+}
13932 following the group indicates that the word or symbol constituent
13933 characters must be matched at least once.
13935 However, the second part of the regexp is more difficult to design.
13936 What we want is to follow the first part with ``optionally one or more
13937 characters that are not constituents of a word or symbol''. At first,
13938 I thought I could define this with the following:
13941 "\\(\\W\\|\\S_\\)*"
13945 The upper case @samp{W} and @samp{S} match characters that are
13946 @emph{not} word or symbol constituents. Unfortunately, this
13947 expression matches any character that is either not a word constituent
13948 or not a symbol constituent. This matches any character!
13950 I then noticed that every word or symbol in my test region was
13951 followed by white space (blank space, tab, or newline). So I tried
13952 placing a pattern to match one or more blank spaces after the pattern
13953 for one or more word or symbol constituents. This failed, too. Words
13954 and symbols are often separated by whitespace, but in actual code
13955 parentheses may follow symbols and punctuation may follow words. So
13956 finally, I designed a pattern in which the word or symbol constituents
13957 are followed optionally by characters that are not white space and
13958 then followed optionally by white space.
13961 Here is the full regular expression:
13964 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
13967 @node count-words-in-defun, Several defuns, Syntax, Words in a defun
13968 @section The @code{count-words-in-defun} Function
13969 @cindex Counting words in a @code{defun}
13971 We have seen that there are several ways to write a
13972 @code{count-word-region} function. To write a
13973 @code{count-words-in-defun}, we need merely adapt one of these
13976 The version that uses a @code{while} loop is easy to understand, so I
13977 am going to adapt that. Because @code{count-words-in-defun} will be
13978 part of a more complex program, it need not be interactive and it need
13979 not display a message but just return the count. These considerations
13980 simplify the definition a little.
13982 On the other hand, @code{count-words-in-defun} will be used within a
13983 buffer that contains function definitions. Consequently, it is
13984 reasonable to ask that the function determine whether it is called
13985 when point is within a function definition, and if it is, to return
13986 the count for that definition. This adds complexity to the
13987 definition, but saves us from needing to pass arguments to the
13991 These considerations lead us to prepare the following template:
13995 (defun count-words-in-defun ()
13996 "@var{documentation}@dots{}"
13997 (@var{set up}@dots{}
13998 (@var{while loop}@dots{})
13999 @var{return count})
14004 As usual, our job is to fill in the slots.
14008 We are presuming that this function will be called within a buffer
14009 containing function definitions. Point will either be within a
14010 function definition or not. For @code{count-words-in-defun} to work,
14011 point must move to the beginning of the definition, a counter must
14012 start at zero, and the counting loop must stop when point reaches the
14013 end of the definition.
14015 The @code{beginning-of-defun} function searches backwards for an
14016 opening delimiter such as a @samp{(} at the beginning of a line, and
14017 moves point to that position, or else to the limit of the search. In
14018 practice, this means that @code{beginning-of-defun} moves point to the
14019 beginning of an enclosing or preceding function definition, or else to
14020 the beginning of the buffer. We can use @code{beginning-of-defun} to
14021 place point where we wish to start.
14023 The @code{while} loop requires a counter to keep track of the words or
14024 symbols being counted. A @code{let} expression can be used to create
14025 a local variable for this purpose, and bind it to an initial value of zero.
14027 The @code{end-of-defun} function works like @code{beginning-of-defun}
14028 except that it moves point to the end of the definition.
14029 @code{end-of-defun} can be used as part of an expression that
14030 determines the position of the end of the definition.
14032 The set up for @code{count-words-in-defun} takes shape rapidly: first
14033 we move point to the beginning of the definition, then we create a
14034 local variable to hold the count, and finally, we record the position
14035 of the end of the definition so the @code{while} loop will know when to stop
14039 The code looks like this:
14043 (beginning-of-defun)
14045 (end (save-excursion (end-of-defun) (point))))
14050 The code is simple. The only slight complication is likely to concern
14051 @code{end}: it is bound to the position of the end of the definition
14052 by a @code{save-excursion} expression that returns the value of point
14053 after @code{end-of-defun} temporarily moves it to the end of the
14056 The second part of the @code{count-words-in-defun}, after the set up,
14057 is the @code{while} loop.
14059 The loop must contain an expression that jumps point forward word by
14060 word and symbol by symbol, and another expression that counts the
14061 jumps. The true-or-false-test for the @code{while} loop should test
14062 true so long as point should jump forward, and false when point is at
14063 the end of the definition. We have already redefined the regular
14064 expression for this (@pxref{Syntax}), so the loop is straightforward:
14068 (while (and (< (point) end)
14070 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
14071 (setq count (1+ count)))
14075 The third part of the function definition returns the count of words
14076 and symbols. This part is the last expression within the body of the
14077 @code{let} expression, and can be, very simply, the local variable
14078 @code{count}, which when evaluated returns the count.
14081 Put together, the @code{count-words-in-defun} definition looks like this:
14083 @findex count-words-in-defun
14086 (defun count-words-in-defun ()
14087 "Return the number of words and symbols in a defun."
14088 (beginning-of-defun)
14090 (end (save-excursion (end-of-defun) (point))))
14094 (and (< (point) end)
14096 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14098 (setq count (1+ count)))
14103 How to test this? The function is not interactive, but it is easy to
14104 put a wrapper around the function to make it interactive; we can use
14105 almost the same code as for the recursive version of
14106 @code{count-words-region}:
14110 ;;; @r{Interactive version.}
14111 (defun count-words-defun ()
14112 "Number of words and symbols in a function definition."
14115 "Counting words and symbols in function definition ... ")
14118 (let ((count (count-words-in-defun)))
14122 "The definition does NOT have any words or symbols."))
14127 "The definition has 1 word or symbol."))
14130 "The definition has %d words or symbols." count)))))
14136 Let's re-use @kbd{C-c =} as a convenient keybinding:
14139 (global-set-key "\C-c=" 'count-words-defun)
14142 Now we can try out @code{count-words-defun}: install both
14143 @code{count-words-in-defun} and @code{count-words-defun}, and set the
14144 keybinding, and then place the cursor within the following definition:
14148 (defun multiply-by-seven (number)
14149 "Multiply NUMBER by seven."
14156 Success! The definition has 10 words and symbols.
14158 The next problem is to count the numbers of words and symbols in
14159 several definitions within a single file.
14161 @node Several defuns, Find a File, count-words-in-defun, Words in a defun
14162 @section Count Several @code{defuns} Within a File
14164 A file such as @file{simple.el} may have 80 or more function
14165 definitions within it. Our long term goal is to collect statistics on
14166 many files, but as a first step, our immediate goal is to collect
14167 statistics on one file.
14169 The information will be a series of numbers, each number being the
14170 length of a function definition. We can store the numbers in a list.
14172 We know that we will want to incorporate the information regarding one
14173 file with information about many other files; this means that the
14174 function for counting definition lengths within one file need only
14175 return the list of lengths. It need not and should not display any
14178 The word count commands contain one expression to jump point forward
14179 word by word and another expression to count the jumps. The function
14180 to return the lengths of definitions can be designed to work the same
14181 way, with one expression to jump point forward definition by
14182 definition and another expression to construct the lengths' list.
14184 This statement of the problem makes it elementary to write the
14185 function definition. Clearly, we will start the count at the
14186 beginning of the file, so the first command will be @code{(goto-char
14187 (point-min))}. Next, we start the @code{while} loop; and the
14188 true-or-false test of the loop can be a regular expression search for
14189 the next function definition---so long as the search succeeds, point
14190 is moved forward and then the body of the loop is evaluated. The body
14191 needs an expression that constructs the lengths' list. @code{cons},
14192 the list construction command, can be used to create the list. That
14193 is almost all there is to it.
14196 Here is what this fragment of code looks like:
14200 (goto-char (point-min))
14201 (while (re-search-forward "^(defun" nil t)
14203 (cons (count-words-in-defun) lengths-list)))
14207 What we have left out is the mechanism for finding the file that
14208 contains the function definitions.
14210 In previous examples, we either used this, the Info file, or we
14211 switched back and forth to some other buffer, such as the
14212 @file{*scratch*} buffer.
14214 Finding a file is a new process that we have not yet discussed.
14216 @node Find a File, lengths-list-file, Several defuns, Words in a defun
14217 @comment node-name, next, previous, up
14218 @section Find a File
14219 @cindex Find a File
14221 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
14222 command. This command is almost, but not quite right for the lengths
14226 Let's look at the source for @code{find-file} (you can use the
14227 @code{find-tag} command or @kbd{C-h f} (@code{describe-function}) to
14228 find the source of a function):
14232 (defun find-file (filename)
14233 "Edit file FILENAME.
14234 Switch to a buffer visiting file FILENAME,
14235 creating one if none already exists."
14236 (interactive "FFind file: ")
14237 (switch-to-buffer (find-file-noselect filename)))
14241 The definition possesses short but complete documentation and an
14242 interactive specification that prompts you for a file name when you
14243 use the command interactively. The body of the definition contains
14244 two functions, @code{find-file-noselect} and @code{switch-to-buffer}.
14246 According to its documentation as shown by @kbd{C-h f} (the
14247 @code{describe-function} command), the @code{find-file-noselect}
14248 function reads the named file into a buffer and returns the buffer.
14249 However, the buffer is not selected. Emacs does not switch its
14250 attention (or yours if you are using @code{find-file-noselect}) to the
14251 named buffer. That is what @code{switch-to-buffer} does: it switches
14252 the buffer to which Emacs attention is directed; and it switches the
14253 buffer displayed in the window to the new buffer. We have discussed
14254 buffer switching elsewhere. (@xref{Switching Buffers}.)
14256 In this histogram project, we do not need to display each file on the
14257 screen as the program determines the length of each definition within
14258 it. Instead of employing @code{switch-to-buffer}, we can work with
14259 @code{set-buffer}, which redirects the attention of the computer
14260 program to a different buffer but does not redisplay it on the screen.
14261 So instead of calling on @code{find-file} to do the job, we must write
14262 our own expression.
14264 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
14266 @node lengths-list-file, Several files, Find a File, Words in a defun
14267 @section @code{lengths-list-file} in Detail
14269 The core of the @code{lengths-list-file} function is a @code{while}
14270 loop containing a function to move point forward `defun by defun' and
14271 a function to count the number of words and symbols in each defun.
14272 This core must be surrounded by functions that do various other tasks,
14273 including finding the file, and ensuring that point starts out at the
14274 beginning of the file. The function definition looks like this:
14275 @findex lengths-list-file
14279 (defun lengths-list-file (filename)
14280 "Return list of definitions' lengths within FILE.
14281 The returned list is a list of numbers.
14282 Each number is the number of words or
14283 symbols in one function definition."
14286 (message "Working on `%s' ... " filename)
14288 (let ((buffer (find-file-noselect filename))
14290 (set-buffer buffer)
14291 (setq buffer-read-only t)
14293 (goto-char (point-min))
14294 (while (re-search-forward "^(defun" nil t)
14296 (cons (count-words-in-defun) lengths-list)))
14297 (kill-buffer buffer)
14303 The function is passed one argument, the name of the file on which it
14304 will work. It has four lines of documentation, but no interactive
14305 specification. Since people worry that a computer is broken if they
14306 don't see anything going on, the first line of the body is a
14309 The next line contains a @code{save-excursion} that returns Emacs'
14310 attention to the current buffer when the function completes. This is
14311 useful in case you embed this function in another function that
14312 presumes point is restored to the original buffer.
14314 In the varlist of the @code{let} expression, Emacs finds the file and
14315 binds the local variable @code{buffer} to the buffer containing the
14316 file. At the same time, Emacs creates @code{lengths-list} as a local
14319 Next, Emacs switches its attention to the buffer.
14321 In the following line, Emacs makes the buffer read-only. Ideally,
14322 this line is not necessary. None of the functions for counting words
14323 and symbols in a function definition should change the buffer.
14324 Besides, the buffer is not going to be saved, even if it were changed.
14325 This line is entirely the consequence of great, perhaps excessive,
14326 caution. The reason for the caution is that this function and those
14327 it calls work on the sources for Emacs and it is very inconvenient if
14328 they are inadvertently modified. It goes without saying that I did
14329 not realize a need for this line until an experiment went awry and
14330 started to modify my Emacs source files @dots{}
14332 Next comes a call to widen the buffer if it is narrowed. This
14333 function is usually not needed---Emacs creates a fresh buffer if none
14334 already exists; but if a buffer visiting the file already exists Emacs
14335 returns that one. In this case, the buffer may be narrowed and must
14336 be widened. If we wanted to be fully `user-friendly', we would
14337 arrange to save the restriction and the location of point, but we
14340 The @code{(goto-char (point-min))} expression moves point to the
14341 beginning of the buffer.
14343 Then comes a @code{while} loop in which the `work' of the function is
14344 carried out. In the loop, Emacs determines the length of each
14345 definition and constructs a lengths' list containing the information.
14347 Emacs kills the buffer after working through it. This is to save
14348 space inside of Emacs. My version of Emacs 19 contained over 300
14349 source files of interest; Emacs 21 contains over 800 source files.
14350 Another function will apply @code{lengths-list-file} to each of the
14353 Finally, the last expression within the @code{let} expression is the
14354 @code{lengths-list} variable; its value is returned as the value of
14355 the whole function.
14357 You can try this function by installing it in the usual fashion. Then
14358 place your cursor after the following expression and type @kbd{C-x
14359 C-e} (@code{eval-last-sexp}).
14361 @c !!! 21.0.100 lisp sources location here
14364 "/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el")
14367 @c was: (lengths-list-file "../lisp/debug.el")
14368 @c !!! as of 21, Info file is in
14369 @c /usr/share/info/emacs-lisp-intro.info.gz
14370 @c but debug.el is in /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
14373 (You may need to change the pathname of the file; the one here worked
14374 with GNU Emacs version 21.0.100. To change the expression, copy it to
14375 the @file{*scratch*} buffer and edit it.
14379 (Also, to see the full length of the list, rather than a truncated
14380 version, you may have to evaluate the following:
14383 (custom-set-variables '(eval-expression-print-length nil))
14387 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.)
14388 Then evaluate the @code{lengths-list-file} expression.)
14391 The lengths' list for @file{debug.el} takes less than a second to
14392 produce and looks like this:
14395 (77 95 85 87 131 89 50 25 44 44 68 35 64 45 17 34 167 457)
14399 (Using my old machine, the version 19 lengths' list for @file{debug.el}
14400 took seven seconds to produce and looked like this:
14403 (75 41 80 62 20 45 44 68 45 12 34 235)
14406 (The newer version of @file{debug.el} contains more defuns than the
14407 earlier one; and my new machine is much faster than the old one.)
14409 Note that the length of the last definition in the file is first in
14412 @node Several files, Several files recursively, lengths-list-file, Words in a defun
14413 @section Count Words in @code{defuns} in Different Files
14415 In the previous section, we created a function that returns a list of
14416 the lengths of each definition in a file. Now, we want to define a
14417 function to return a master list of the lengths of the definitions in
14420 Working on each of a list of files is a repetitious act, so we can use
14421 either a @code{while} loop or recursion.
14424 * lengths-list-many-files:: Return a list of the lengths of defuns.
14425 * append:: Attach one list to another.
14428 @node lengths-list-many-files, append, Several files, Several files
14430 @unnumberedsubsec Determine the lengths of @code{defuns}
14433 The design using a @code{while} loop is routine. The argument passed
14434 the function is a list of files. As we saw earlier (@pxref{Loop
14435 Example}), you can write a @code{while} loop so that the body of the
14436 loop is evaluated if such a list contains elements, but to exit the
14437 loop if the list is empty. For this design to work, the body of the
14438 loop must contain an expression that shortens the list each time the
14439 body is evaluated, so that eventually the list is empty. The usual
14440 technique is to set the value of the list to the value of the @sc{cdr}
14441 of the list each time the body is evaluated.
14444 The template looks like this:
14448 (while @var{test-whether-list-is-empty}
14450 @var{set-list-to-cdr-of-list})
14454 Also, we remember that a @code{while} loop returns @code{nil} (the
14455 result of evaluating the true-or-false-test), not the result of any
14456 evaluation within its body. (The evaluations within the body of the
14457 loop are done for their side effects.) However, the expression that
14458 sets the lengths' list is part of the body---and that is the value
14459 that we want returned by the function as a whole. To do this, we
14460 enclose the @code{while} loop within a @code{let} expression, and
14461 arrange that the last element of the @code{let} expression contains
14462 the value of the lengths' list. (@xref{Incrementing Example, , Loop
14463 Example with an Incrementing Counter}.)
14465 @findex lengths-list-many-files
14467 These considerations lead us directly to the function itself:
14471 ;;; @r{Use @code{while} loop.}
14472 (defun lengths-list-many-files (list-of-files)
14473 "Return list of lengths of defuns in LIST-OF-FILES."
14476 (let (lengths-list)
14478 ;;; @r{true-or-false-test}
14479 (while list-of-files
14484 ;;; @r{Generate a lengths' list.}
14486 (expand-file-name (car list-of-files)))))
14490 ;;; @r{Make files' list shorter.}
14491 (setq list-of-files (cdr list-of-files)))
14493 ;;; @r{Return final value of lengths' list.}
14498 @code{expand-file-name} is a built-in function that converts a file
14499 name to the absolute, long, path name form of the directory in which
14500 the function is called.
14502 @c !!! 21.0.100 lisp sources location here
14504 Thus, if @code{expand-file-name} is called on @code{debug.el} when
14505 Emacs is visiting the
14506 @file{/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/} directory,
14516 @c !!! 21.0.100 lisp sources location here
14518 /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
14521 The only other new element of this function definition is the as yet
14522 unstudied function @code{append}, which merits a short section for
14525 @node append, , lengths-list-many-files, Several files
14526 @subsection The @code{append} Function
14529 The @code{append} function attaches one list to another. Thus,
14532 (append '(1 2 3 4) '(5 6 7 8))
14543 This is exactly how we want to attach two lengths' lists produced by
14544 @code{lengths-list-file} to each other. The results contrast with
14548 (cons '(1 2 3 4) '(5 6 7 8))
14553 which constructs a new list in which the first argument to @code{cons}
14554 becomes the first element of the new list:
14557 ((1 2 3 4) 5 6 7 8)
14560 @node Several files recursively, Prepare the data, Several files, Words in a defun
14561 @section Recursively Count Words in Different Files
14563 Besides a @code{while} loop, you can work on each of a list of files
14564 with recursion. A recursive version of @code{lengths-list-many-files}
14565 is short and simple.
14567 The recursive function has the usual parts: the `do-again-test', the
14568 `next-step-expression', and the recursive call. The `do-again-test'
14569 determines whether the function should call itself again, which it
14570 will do if the @code{list-of-files} contains any remaining elements;
14571 the `next-step-expression' resets the @code{list-of-files} to the
14572 @sc{cdr} of itself, so eventually the list will be empty; and the
14573 recursive call calls itself on the shorter list. The complete
14574 function is shorter than this description!
14575 @findex recursive-lengths-list-many-files
14579 (defun recursive-lengths-list-many-files (list-of-files)
14580 "Return list of lengths of each defun in LIST-OF-FILES."
14581 (if list-of-files ; @r{do-again-test}
14584 (expand-file-name (car list-of-files)))
14585 (recursive-lengths-list-many-files
14586 (cdr list-of-files)))))
14591 In a sentence, the function returns the lengths' list for the first of
14592 the @code{list-of-files} appended to the result of calling itself on
14593 the rest of the @code{list-of-files}.
14595 Here is a test of @code{recursive-lengths-list-many-files}, along with
14596 the results of running @code{lengths-list-file} on each of the files
14599 Install @code{recursive-lengths-list-many-files} and
14600 @code{lengths-list-file}, if necessary, and then evaluate the
14601 following expressions. You may need to change the files' pathnames;
14602 those here work when this Info file and the Emacs sources are located
14603 in their customary places. To change the expressions, copy them to
14604 the @file{*scratch*} buffer, edit them, and then evaluate them.
14606 The results are shown after the @samp{@result{}}. (These results are
14607 for files from Emacs Version 21.0.100; files from other versions of
14608 Emacs may produce different results.)
14610 @c !!! 21.0.100 lisp sources location here
14613 (cd "/usr/local/share/emacs/21.0.100/")
14615 (lengths-list-file "./lisp/macros.el")
14616 @result{} (273 263 456 90)
14620 (lengths-list-file "./lisp/mail/mailalias.el")
14621 @result{} (38 32 26 77 174 180 321 198 324)
14625 (lengths-list-file "./lisp/makesum.el")
14630 (recursive-lengths-list-many-files
14631 '("./lisp/macros.el"
14632 "./lisp/mail/mailalias.el"
14633 "./lisp/makesum.el"))
14634 @result{} (273 263 456 90 38 32 26 77 174 180 321 198 324 85 181)
14638 The @code{recursive-lengths-list-many-files} function produces the
14641 The next step is to prepare the data in the list for display in a graph.
14643 @node Prepare the data, , Several files recursively, Words in a defun
14644 @section Prepare the Data for Display in a Graph
14646 The @code{recursive-lengths-list-many-files} function returns a list
14647 of numbers. Each number records the length of a function definition.
14648 What we need to do now is transform this data into a list of numbers
14649 suitable for generating a graph. The new list will tell how many
14650 functions definitions contain less than 10 words and
14651 symbols, how many contain between 10 and 19 words and symbols, how
14652 many contain between 20 and 29 words and symbols, and so on.
14654 In brief, we need to go through the lengths' list produced by the
14655 @code{recursive-lengths-list-many-files} function and count the number
14656 of defuns within each range of lengths, and produce a list of those
14659 Based on what we have done before, we can readily foresee that it
14660 should not be too hard to write a function that `@sc{cdr}s' down the
14661 lengths' list, looks at each element, determines which length range it
14662 is in, and increments a counter for that range.
14664 However, before beginning to write such a function, we should consider
14665 the advantages of sorting the lengths' list first, so the numbers are
14666 ordered from smallest to largest. First, sorting will make it easier
14667 to count the numbers in each range, since two adjacent numbers will
14668 either be in the same length range or in adjacent ranges. Second, by
14669 inspecting a sorted list, we can discover the highest and lowest
14670 number, and thereby determine the largest and smallest length range
14674 * Sorting:: Sorting lists.
14675 * Files List:: Making a list of files.
14676 * Counting function definitions::
14679 @node Sorting, Files List, Prepare the data, Prepare the data
14680 @subsection Sorting Lists
14683 Emacs contains a function to sort lists, called (as you might guess)
14684 @code{sort}. The @code{sort} function takes two arguments, the list
14685 to be sorted, and a predicate that determines whether the first of
14686 two list elements is ``less'' than the second.
14688 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
14689 Type Object as an Argument}), a predicate is a function that
14690 determines whether some property is true or false. The @code{sort}
14691 function will reorder a list according to whatever property the
14692 predicate uses; this means that @code{sort} can be used to sort
14693 non-numeric lists by non-numeric criteria---it can, for example,
14694 alphabetize a list.
14697 The @code{<} function is used when sorting a numeric list. For example,
14700 (sort '(4 8 21 17 33 7 21 7) '<)
14708 (4 7 7 8 17 21 21 33)
14712 (Note that in this example, both the arguments are quoted so that the
14713 symbols are not evaluated before being passed to @code{sort} as
14716 Sorting the list returned by the
14717 @code{recursive-lengths-list-many-files} function is straightforward;
14718 it uses the @code{<} function:
14723 (recursive-lengths-list-many-files
14724 '("../lisp/macros.el"
14725 "../lisp/mailalias.el"
14726 "../lisp/makesum.el"))
14736 (85 86 116 122 154 176 179 265)
14740 (Note that in this example, the first argument to @code{sort} is not
14741 quoted, since the expression must be evaluated so as to produce the
14742 list that is passed to @code{sort}.)
14744 @node Files List, Counting function definitions, Sorting, Prepare the data
14745 @subsection Making a List of Files
14747 The @code{recursive-lengths-list-many-files} function requires a list
14748 of files as its argument. For our test examples, we constructed such
14749 a list by hand; but the Emacs Lisp source directory is too large for
14750 us to do for that. Instead, we will write a function to do the job
14751 for us. In this function, we will use both a @code{while} loop and a
14754 @findex directory-files
14755 We did not have to write a function like this for older versions of
14756 GNU Emacs, since they placed all the @samp{.el} files in one
14757 directory. Instead, we were able to use the @code{directory-files}
14758 function, which lists the names of files that match a specified
14759 pattern within a single directory.
14761 However, recent versions of Emacs place Emacs Lisp files in
14762 sub-directories of the top level @file{lisp} directory. This
14763 re-arrangement eases navigation. For example, all the mail related
14764 files are in a @file{lisp} sub-directory called @file{mail}. But at
14765 the same time, this arrangement forces us to create a file listing
14766 function that descends into the sub-directories.
14768 @findex files-in-below-directory
14769 We can create this function, called @code{files-in-below-directory},
14770 using familiar functions such as @code{car}, @code{nthcdr}, and
14771 @code{substring} in conjunction with an existing function called
14772 @code{directory-files-and-attributes}. This latter function not only
14773 lists all the filenames in a directory, including the names
14774 of sub-directories, but also their attributes.
14776 To restate our goal: to create a function that will enable us
14777 to feed filenames to @code{recursive-lengths-list-many-files}
14778 as a list that looks like this (but with more elements):
14782 ("../lisp/macros.el"
14783 "../lisp/mail/rmail.el"
14784 "../lisp/makesum.el")
14788 The @code{directory-files-and-attributes} function returns a list of
14789 lists. Each of the lists within the main list consists of 13
14790 elements. The first element is a string that contains the name of the
14791 file -- which, in GNU/Linux, may be a `directory file', that is to
14792 say, a file with the special attributes of a directory. The second
14793 element of the list is @code{t} for a directory, a string
14794 for symbolic link (the string is the name linked to), or @code{nil}.
14796 For example, the first @samp{.el} file in the @file{lisp/} directory
14797 is @file{abbrev.el}. Its name is
14798 @file{/usr/local/share/emacs/21.0.100/lisp/abbrev.el} and it is not a
14799 directory or a symbolic link.
14802 This is how @code{directory-files-and-attributes} lists that file and
14807 ("/usr/local/share/emacs/21.0.100/lisp/abbrev.el"
14828 On the other hand, @file{mail/} is a directory within the @file{lisp/}
14829 directory. The beginning of its listing looks like this:
14833 ("/usr/local/share/emacs/21.0.100/lisp/mail"
14840 (Look at the documentation of @code{file-attributes} to learn about
14841 the different attributes. Bear in mind that the
14842 @code{file-attributes} function does not list the filename, so its
14843 first element is @code{directory-files-and-attributes}'s second
14846 We will want our new function, @code{files-in-below-directory}, to
14847 list the @samp{.el} files in the directory it is told to check, and in
14848 any directories below that directory.
14850 This gives us a hint on how to construct
14851 @code{files-in-below-directory}: within a directory, the function
14852 should add @samp{.el} filenames to a list; and if, within a directory,
14853 the function comes upon a sub-directory, it should go into that
14854 sub-directory and repeat its actions.
14856 However, we should note that every directory contains a name that
14857 refers to itself, called @file{.}, (``dot'') and a name that refers to
14858 its parent directory, called @file{..} (``double dot''). (In
14859 @file{/}, the root directory, @file{..} refers to itself, since
14860 @file{/} has no parent.) Clearly, we do not want our
14861 @code{files-in-below-directory} function to enter those directories,
14862 since they always lead us, directly or indirectly, to the current
14865 Consequently, our @code{files-in-below-directory} function must do
14870 Check to see whether it is looking at a filename that ends in
14871 @samp{.el}; and if so, add its name to a list.
14874 Check to see whether it is looking at a filename that is the name of a
14875 directory; and if so,
14879 Check to see whether it is looking at @file{.} or @file{..}; and if
14883 Or else, go into that directory and repeat the process.
14887 Let's write a function definition to do these tasks. We will use a
14888 @code{while} loop to move from one filename to another within a
14889 directory, checking what needs to be done; and we will use a recursive
14890 call to repeat the actions on each sub-directory. The recursive
14891 pattern is `accumulate'
14892 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
14893 using @code{append} as the combiner.
14896 (directory-files "/usr/local/share/emacs/21.0.100/lisp/" t "\\.el$")
14897 (shell-command "find /usr/local/share/emacs/21.0.100/lisp/ -name '*.el'")
14900 @c /usr/local/share/emacs/21.0.100/lisp/
14903 Here is the function:
14907 (defun files-in-below-directory (directory)
14908 "List the .el files in DIRECTORY and in its sub-directories."
14909 ;; Although the function will be used non-interactively,
14910 ;; it will be easier to test if we make it interactive.
14911 ;; The directory will have a name such as
14912 ;; "/usr/local/share/emacs/21.0.100/lisp/"
14913 (interactive "DDirectory name: ")
14916 (let (el-files-list
14917 (current-directory-list
14918 (directory-files-and-attributes directory t)))
14919 ;; while we are in the current directory
14920 (while current-directory-list
14924 ;; check to see whether filename ends in `.el'
14925 ;; and if so, append its name to a list.
14926 ((equal ".el" (substring (car (car current-directory-list)) -3))
14927 (setq el-files-list
14928 (cons (car (car current-directory-list)) el-files-list)))
14931 ;; check whether filename is that of a directory
14932 ((eq t (car (cdr (car current-directory-list))))
14933 ;; decide whether to skip or recurse
14936 (substring (car (car current-directory-list)) -1))
14937 ;; then do nothing since filename is that of
14938 ;; current directory or parent, "." or ".."
14942 ;; else descend into the directory and repeat the process
14943 (setq el-files-list
14945 (files-in-below-directory
14946 (car (car current-directory-list)))
14948 ;; move to the next filename in the list; this also
14949 ;; shortens the list so the while loop eventually comes to an end
14950 (setq current-directory-list (cdr current-directory-list)))
14951 ;; return the filenames
14956 @c (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
14958 The @code{files-in-below-directory} @code{directory-files} function
14959 takes one argument, the name of a directory.
14962 Thus, on my system,
14964 @c !!! 21.0.100 lisp sources location here
14968 (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/"))
14973 tells me that my version 21.0.100 Lisp sources directory contains 754
14976 @code{files-in-below-directory} returns a list in reverse alphabetical
14977 order. An expression to sort the list in alphabetical order looks
14983 (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
14990 "Test how long it takes to find lengths of all elisp defuns."
14991 (insert "\n" (current-time-string) "\n")
14994 (recursive-lengths-list-many-files
14995 '("../lisp/macros.el"
14996 "../lisp/mailalias.el"
14997 "../lisp/makesum.el"))
14999 (insert (format "%s" (current-time-string))))
15003 @node Counting function definitions, , Files List, Prepare the data
15004 @subsection Counting function definitions
15006 Our immediate goal is to generate a list that tells us how many
15007 function definitions contain fewer than 10 words and symbols, how many
15008 contain between 10 and 19 words and symbols, how many contain between
15009 20 and 29 words and symbols, and so on.
15011 With a sorted list of numbers, this is easy: count how many elements
15012 of the list are smaller than 10, then, after moving past the numbers
15013 just counted, count how many are smaller than 20, then, after moving
15014 past the numbers just counted, count how many are smaller than 30, and
15015 so on. Each of the numbers, 10, 20, 30, 40, and the like, is one
15016 larger than the top of that range. We can call the list of such
15017 numbers the @code{top-of-ranges} list.
15020 If we wished, we could generate this list automatically, but it is
15021 simpler to write a list manually. Here it is:
15022 @vindex top-of-ranges
15026 (defvar top-of-ranges
15029 110 120 130 140 150
15030 160 170 180 190 200
15031 210 220 230 240 250
15032 260 270 280 290 300)
15033 "List specifying ranges for `defuns-per-range'.")
15037 To change the ranges, we edit this list.
15039 Next, we need to write the function that creates the list of the
15040 number of definitions within each range. Clearly, this function must
15041 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
15044 The @code{defuns-per-range} function must do two things again and
15045 again: it must count the number of definitions within a range
15046 specified by the current top-of-range value; and it must shift to the
15047 next higher value in the @code{top-of-ranges} list after counting the
15048 number of definitions in the current range. Since each of these
15049 actions is repetitive, we can use @code{while} loops for the job.
15050 One loop counts the number of definitions in the range defined by the
15051 current top-of-range value, and the other loop selects each of the
15052 top-of-range values in turn.
15054 Several entries of the @code{sorted-lengths} list are counted for each
15055 range; this means that the loop for the @code{sorted-lengths} list
15056 will be inside the loop for the @code{top-of-ranges} list, like a
15057 small gear inside a big gear.
15059 The inner loop counts the number of definitions within the range. It
15060 is a simple counting loop of the type we have seen before.
15061 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
15062 The true-or-false test of the loop tests whether the value from the
15063 @code{sorted-lengths} list is smaller than the current value of the
15064 top of the range. If it is, the function increments the counter and
15065 tests the next value from the @code{sorted-lengths} list.
15068 The inner loop looks like this:
15072 (while @var{length-element-smaller-than-top-of-range}
15073 (setq number-within-range (1+ number-within-range))
15074 (setq sorted-lengths (cdr sorted-lengths)))
15078 The outer loop must start with the lowest value of the
15079 @code{top-of-ranges} list, and then be set to each of the succeeding
15080 higher values in turn. This can be done with a loop like this:
15084 (while top-of-ranges
15085 @var{body-of-loop}@dots{}
15086 (setq top-of-ranges (cdr top-of-ranges)))
15091 Put together, the two loops look like this:
15095 (while top-of-ranges
15097 ;; @r{Count the number of elements within the current range.}
15098 (while @var{length-element-smaller-than-top-of-range}
15099 (setq number-within-range (1+ number-within-range))
15100 (setq sorted-lengths (cdr sorted-lengths)))
15102 ;; @r{Move to next range.}
15103 (setq top-of-ranges (cdr top-of-ranges)))
15107 In addition, in each circuit of the outer loop, Emacs should record
15108 the number of definitions within that range (the value of
15109 @code{number-within-range}) in a list. We can use @code{cons} for
15110 this purpose. (@xref{cons, , @code{cons}}.)
15112 The @code{cons} function works fine, except that the list it
15113 constructs will contain the number of definitions for the highest
15114 range at its beginning and the number of definitions for the lowest
15115 range at its end. This is because @code{cons} attaches new elements
15116 of the list to the beginning of the list, and since the two loops are
15117 working their way through the lengths' list from the lower end first,
15118 the @code{defuns-per-range-list} will end up largest number first.
15119 But we will want to print our graph with smallest values first and the
15120 larger later. The solution is to reverse the order of the
15121 @code{defuns-per-range-list}. We can do this using the
15122 @code{nreverse} function, which reverses the order of a list.
15129 (nreverse '(1 2 3 4))
15140 Note that the @code{nreverse} function is ``destructive''---that is,
15141 it changes the list to which it is applied; this contrasts with the
15142 @code{car} and @code{cdr} functions, which are non-destructive. In
15143 this case, we do not want the original @code{defuns-per-range-list},
15144 so it does not matter that it is destroyed. (The @code{reverse}
15145 function provides a reversed copy of a list, leaving the original list
15150 Put all together, the @code{defuns-per-range} looks like this:
15154 (defun defuns-per-range (sorted-lengths top-of-ranges)
15155 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
15156 (let ((top-of-range (car top-of-ranges))
15157 (number-within-range 0)
15158 defuns-per-range-list)
15163 (while top-of-ranges
15169 ;; @r{Need number for numeric test.}
15170 (car sorted-lengths)
15171 (< (car sorted-lengths) top-of-range))
15175 ;; @r{Count number of definitions within current range.}
15176 (setq number-within-range (1+ number-within-range))
15177 (setq sorted-lengths (cdr sorted-lengths)))
15179 ;; @r{Exit inner loop but remain within outer loop.}
15183 (setq defuns-per-range-list
15184 (cons number-within-range defuns-per-range-list))
15185 (setq number-within-range 0) ; @r{Reset count to zero.}
15189 ;; @r{Move to next range.}
15190 (setq top-of-ranges (cdr top-of-ranges))
15191 ;; @r{Specify next top of range value.}
15192 (setq top-of-range (car top-of-ranges)))
15196 ;; @r{Exit outer loop and count the number of defuns larger than}
15197 ;; @r{ the largest top-of-range value.}
15198 (setq defuns-per-range-list
15200 (length sorted-lengths)
15201 defuns-per-range-list))
15205 ;; @r{Return a list of the number of definitions within each range,}
15206 ;; @r{ smallest to largest.}
15207 (nreverse defuns-per-range-list)))
15213 The function is straightforward except for one subtle feature. The
15214 true-or-false test of the inner loop looks like this:
15218 (and (car sorted-lengths)
15219 (< (car sorted-lengths) top-of-range))
15225 instead of like this:
15228 (< (car sorted-lengths) top-of-range)
15231 The purpose of the test is to determine whether the first item in the
15232 @code{sorted-lengths} list is less than the value of the top of the
15235 The simple version of the test works fine unless the
15236 @code{sorted-lengths} list has a @code{nil} value. In that case, the
15237 @code{(car sorted-lengths)} expression function returns
15238 @code{nil}. The @code{<} function cannot compare a number to
15239 @code{nil}, which is an empty list, so Emacs signals an error and
15240 stops the function from attempting to continue to execute.
15242 The @code{sorted-lengths} list always becomes @code{nil} when the
15243 counter reaches the end of the list. This means that any attempt to
15244 use the @code{defuns-per-range} function with the simple version of
15245 the test will fail.
15247 We solve the problem by using the @code{(car sorted-lengths)}
15248 expression in conjunction with the @code{and} expression. The
15249 @code{(car sorted-lengths)} expression returns a non-@code{nil}
15250 value so long as the list has at least one number within it, but
15251 returns @code{nil} if the list is empty. The @code{and} expression
15252 first evaluates the @code{(car sorted-lengths)} expression, and
15253 if it is @code{nil}, returns false @emph{without} evaluating the
15254 @code{<} expression. But if the @code{(car sorted-lengths)}
15255 expression returns a non-@code{nil} value, the @code{and} expression
15256 evaluates the @code{<} expression, and returns that value as the value
15257 of the @code{and} expression.
15259 @c colon in printed section title causes problem in Info cross reference
15260 This way, we avoid an error.
15262 @xref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
15263 Functions}, for more information about @code{and}.
15266 @xref{forward-paragraph}, for more information about @code{and}.
15269 Here is a short test of the @code{defuns-per-range} function. First,
15270 evaluate the expression that binds (a shortened)
15271 @code{top-of-ranges} list to the list of values, then evaluate the
15272 expression for binding the @code{sorted-lengths} list, and then
15273 evaluate the @code{defuns-per-range} function.
15277 ;; @r{(Shorter list than we will use later.)}
15278 (setq top-of-ranges
15279 '(110 120 130 140 150
15280 160 170 180 190 200))
15282 (setq sorted-lengths
15283 '(85 86 110 116 122 129 154 176 179 200 265 300 300))
15285 (defuns-per-range sorted-lengths top-of-ranges)
15291 The list returned looks like this:
15294 (2 2 2 0 0 1 0 2 0 0 4)
15298 Indeed, there are two elements of the @code{sorted-lengths} list
15299 smaller than 110, two elements between 110 and 119, two elements
15300 between 120 and 129, and so on. There are four elements with a value
15303 @c The next step is to turn this numbers' list into a graph.
15305 @node Readying a Graph, Emacs Initialization, Words in a defun, Top
15306 @chapter Readying a Graph
15307 @cindex Readying a graph
15308 @cindex Graph prototype
15309 @cindex Prototype graph
15310 @cindex Body of graph
15312 Our goal is to construct a graph showing the numbers of function
15313 definitions of various lengths in the Emacs lisp sources.
15315 As a practical matter, if you were creating a graph, you would
15316 probably use a program such as @code{gnuplot} to do the job.
15317 (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case,
15318 however, we create one from scratch, and in the process we will
15319 re-acquaint ourselves with some of what we learned before and learn
15322 In this chapter, we will first write a simple graph printing function.
15323 This first definition will be a @dfn{prototype}, a rapidly written
15324 function that enables us to reconnoiter this unknown graph-making
15325 territory. We will discover dragons, or find that they are myth.
15326 After scouting the terrain, we will feel more confident and enhance
15327 the function to label the axes automatically.
15330 * Columns of a graph::
15331 * graph-body-print:: How to print the body of a graph.
15332 * recursive-graph-body-print::
15334 * Line Graph Exercise::
15337 @node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph
15339 @unnumberedsec Printing the Columns of a Graph
15342 Since Emacs is designed to be flexible and work with all kinds of
15343 terminals, including character-only terminals, the graph will need to
15344 be made from one of the `typewriter' symbols. An asterisk will do; as
15345 we enhance the graph-printing function, we can make the choice of
15346 symbol a user option.
15348 We can call this function @code{graph-body-print}; it will take a
15349 @code{numbers-list} as its only argument. At this stage, we will not
15350 label the graph, but only print its body.
15352 The @code{graph-body-print} function inserts a vertical column of
15353 asterisks for each element in the @code{numbers-list}. The height of
15354 each line is determined by the value of that element of the
15355 @code{numbers-list}.
15357 Inserting columns is a repetitive act; that means that this function can
15358 be written either with a @code{while} loop or recursively.
15360 Our first challenge is to discover how to print a column of asterisks.
15361 Usually, in Emacs, we print characters onto a screen horizontally,
15362 line by line, by typing. We have two routes we can follow: write our
15363 own column-insertion function or discover whether one exists in Emacs.
15365 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
15366 command. This command is like the @kbd{C-h a} (command-apropos)
15367 command, except that the latter finds only those functions that are
15368 commands. The @kbd{M-x apropos} command lists all symbols that match
15369 a regular expression, including functions that are not interactive.
15372 What we want to look for is some command that prints or inserts
15373 columns. Very likely, the name of the function will contain either
15374 the word `print' or the word `insert' or the word `column'.
15375 Therefore, we can simply type @kbd{M-x apropos RET
15376 print\|insert\|column RET} and look at the result. On my system, this
15377 command takes quite some time, and then produces a list of 79
15378 functions and variables. Scanning down the list, the only function
15379 that looks as if it might do the job is @code{insert-rectangle}.
15382 Indeed, this is the function we want; its documentation says:
15387 Insert text of RECTANGLE with upper left corner at point.
15388 RECTANGLE's first line is inserted at point,
15389 its second line is inserted at a point vertically under point, etc.
15390 RECTANGLE should be a list of strings.
15394 We can run a quick test, to make sure it does what we expect of it.
15396 Here is the result of placing the cursor after the
15397 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
15398 (@code{eval-last-sexp}). The function inserts the strings
15399 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
15400 point. Also the function returns @code{nil}.
15404 (insert-rectangle '("first" "second" "third"))first
15412 Of course, we won't be inserting the text of the
15413 @code{insert-rectangle} expression itself into the buffer in which we
15414 are making the graph, but will call the function from our program. We
15415 shall, however, have to make sure that point is in the buffer at the
15416 place where the @code{insert-rectangle} function will insert its
15419 If you are reading this in Info, you can see how this works by
15420 switching to another buffer, such as the @file{*scratch*} buffer,
15421 placing point somewhere in the buffer, typing @kbd{M-:},
15422 typing the @code{insert-rectangle} expression into the minibuffer at
15423 the prompt, and then typing @key{RET}. This causes Emacs to evaluate
15424 the expression in the minibuffer, but to use as the value of point the
15425 position of point in the @file{*scratch*} buffer. (@kbd{M-:}
15426 is the keybinding for @code{eval-expression}.)
15428 We find when we do this that point ends up at the end of the last
15429 inserted line---that is to say, this function moves point as a
15430 side-effect. If we were to repeat the command, with point at this
15431 position, the next insertion would be below and to the right of the
15432 previous insertion. We don't want this! If we are going to make a
15433 bar graph, the columns need to be beside each other.
15435 So we discover that each cycle of the column-inserting @code{while}
15436 loop must reposition point to the place we want it, and that place
15437 will be at the top, not the bottom, of the column. Moreover, we
15438 remember that when we print a graph, we do not expect all the columns
15439 to be the same height. This means that the top of each column may be
15440 at a different height from the previous one. We cannot simply
15441 reposition point to the same line each time, but moved over to the
15442 right---or perhaps we can@dots{}
15444 We are planning to make the columns of the bar graph out of asterisks.
15445 The number of asterisks in the column is the number specified by the
15446 current element of the @code{numbers-list}. We need to construct a
15447 list of asterisks of the right length for each call to
15448 @code{insert-rectangle}. If this list consists solely of the requisite
15449 number of asterisks, then we will have position point the right number
15450 of lines above the base for the graph to print correctly. This could
15453 Alternatively, if we can figure out some way to pass
15454 @code{insert-rectangle} a list of the same length each time, then we
15455 can place point on the same line each time, but move it over one
15456 column to the right for each new column. If we do this, however, some
15457 of the entries in the list passed to @code{insert-rectangle} must be
15458 blanks rather than asterisks. For example, if the maximum height of
15459 the graph is 5, but the height of the column is 3, then
15460 @code{insert-rectangle} requires an argument that looks like this:
15463 (" " " " "*" "*" "*")
15466 This last proposal is not so difficult, so long as we can determine
15467 the column height. There are two ways for us to specify the column
15468 height: we can arbitrarily state what it will be, which would work
15469 fine for graphs of that height; or we can search through the list of
15470 numbers and use the maximum height of the list as the maximum height
15471 of the graph. If the latter operation were difficult, then the former
15472 procedure would be easiest, but there is a function built into Emacs
15473 that determines the maximum of its arguments. We can use that
15474 function. The function is called @code{max} and it returns the
15475 largest of all its arguments, which must be numbers. Thus, for
15483 returns 7. (A corresponding function called @code{min} returns the
15484 smallest of all its arguments.)
15488 However, we cannot simply call @code{max} on the @code{numbers-list};
15489 the @code{max} function expects numbers as its argument, not a list of
15490 numbers. Thus, the following expression,
15493 (max '(3 4 6 5 7 3))
15498 produces the following error message;
15501 Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3)
15505 We need a function that passes a list of arguments to a function.
15506 This function is @code{apply}. This function `applies' its first
15507 argument (a function) to its remaining arguments, the last of which
15514 (apply 'max 3 4 7 3 '(4 8 5))
15520 (Incidentally, I don't know how you would learn of this function
15521 without a book such as this. It is possible to discover other
15522 functions, like @code{search-forward} or @code{insert-rectangle}, by
15523 guessing at a part of their names and then using @code{apropos}. Even
15524 though its base in metaphor is clear---`apply' its first argument to
15525 the rest---I doubt a novice would come up with that particular word
15526 when using @code{apropos} or other aid. Of course, I could be wrong;
15527 after all, the function was first named by someone who had to invent
15530 The second and subsequent arguments to @code{apply} are optional, so
15531 we can use @code{apply} to call a function and pass the elements of a
15532 list to it, like this, which also returns 8:
15535 (apply 'max '(4 8 5))
15538 This latter way is how we will use @code{apply}. The
15539 @code{recursive-lengths-list-many-files} function returns a numbers'
15540 list to which we can apply @code{max} (we could also apply @code{max} to
15541 the sorted numbers' list; it does not matter whether the list is
15545 Hence, the operation for finding the maximum height of the graph is this:
15548 (setq max-graph-height (apply 'max numbers-list))
15551 Now we can return to the question of how to create a list of strings
15552 for a column of the graph. Told the maximum height of the graph
15553 and the number of asterisks that should appear in the column, the
15554 function should return a list of strings for the
15555 @code{insert-rectangle} command to insert.
15557 Each column is made up of asterisks or blanks. Since the function is
15558 passed the value of the height of the column and the number of
15559 asterisks in the column, the number of blanks can be found by
15560 subtracting the number of asterisks from the height of the column.
15561 Given the number of blanks and the number of asterisks, two
15562 @code{while} loops can be used to construct the list:
15566 ;;; @r{First version.}
15567 (defun column-of-graph (max-graph-height actual-height)
15568 "Return list of strings that is one column of a graph."
15569 (let ((insert-list nil)
15570 (number-of-top-blanks
15571 (- max-graph-height actual-height)))
15575 ;; @r{Fill in asterisks.}
15576 (while (> actual-height 0)
15577 (setq insert-list (cons "*" insert-list))
15578 (setq actual-height (1- actual-height)))
15582 ;; @r{Fill in blanks.}
15583 (while (> number-of-top-blanks 0)
15584 (setq insert-list (cons " " insert-list))
15585 (setq number-of-top-blanks
15586 (1- number-of-top-blanks)))
15590 ;; @r{Return whole list.}
15595 If you install this function and then evaluate the following
15596 expression you will see that it returns the list as desired:
15599 (column-of-graph 5 3)
15607 (" " " " "*" "*" "*")
15610 As written, @code{column-of-graph} contains a major flaw: the symbols
15611 used for the blank and for the marked entries in the column are
15612 `hard-coded' as a space and asterisk. This is fine for a prototype,
15613 but you, or another user, may wish to use other symbols. For example,
15614 in testing the graph function, you many want to use a period in place
15615 of the space, to make sure the point is being repositioned properly
15616 each time the @code{insert-rectangle} function is called; or you might
15617 want to substitute a @samp{+} sign or other symbol for the asterisk.
15618 You might even want to make a graph-column that is more than one
15619 display column wide. The program should be more flexible. The way to
15620 do that is to replace the blank and the asterisk with two variables
15621 that we can call @code{graph-blank} and @code{graph-symbol} and define
15622 those variables separately.
15624 Also, the documentation is not well written. These considerations
15625 lead us to the second version of the function:
15629 (defvar graph-symbol "*"
15630 "String used as symbol in graph, usually an asterisk.")
15634 (defvar graph-blank " "
15635 "String used as blank in graph, usually a blank space.
15636 graph-blank must be the same number of columns wide
15642 (For an explanation of @code{defvar}, see
15643 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
15647 ;;; @r{Second version.}
15648 (defun column-of-graph (max-graph-height actual-height)
15649 "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
15653 The graph-symbols are contiguous entries at the end
15655 The list will be inserted as one column of a graph.
15656 The strings are either graph-blank or graph-symbol."
15660 (let ((insert-list nil)
15661 (number-of-top-blanks
15662 (- max-graph-height actual-height)))
15666 ;; @r{Fill in @code{graph-symbols}.}
15667 (while (> actual-height 0)
15668 (setq insert-list (cons graph-symbol insert-list))
15669 (setq actual-height (1- actual-height)))
15673 ;; @r{Fill in @code{graph-blanks}.}
15674 (while (> number-of-top-blanks 0)
15675 (setq insert-list (cons graph-blank insert-list))
15676 (setq number-of-top-blanks
15677 (1- number-of-top-blanks)))
15679 ;; @r{Return whole list.}
15684 If we wished, we could rewrite @code{column-of-graph} a third time to
15685 provide optionally for a line graph as well as for a bar graph. This
15686 would not be hard to do. One way to think of a line graph is that it
15687 is no more than a bar graph in which the part of each bar that is
15688 below the top is blank. To construct a column for a line graph, the
15689 function first constructs a list of blanks that is one shorter than
15690 the value, then it uses @code{cons} to attach a graph symbol to the
15691 list; then it uses @code{cons} again to attach the `top blanks' to
15694 It is easy to see how to write such a function, but since we don't
15695 need it, we will not do it. But the job could be done, and if it were
15696 done, it would be done with @code{column-of-graph}. Even more
15697 important, it is worth noting that few changes would have to be made
15698 anywhere else. The enhancement, if we ever wish to make it, is
15701 Now, finally, we come to our first actual graph printing function.
15702 This prints the body of a graph, not the labels for the vertical and
15703 horizontal axes, so we can call this @code{graph-body-print}.
15705 @node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph
15706 @section The @code{graph-body-print} Function
15707 @findex graph-body-print
15709 After our preparation in the preceding section, the
15710 @code{graph-body-print} function is straightforward. The function
15711 will print column after column of asterisks and blanks, using the
15712 elements of a numbers' list to specify the number of asterisks in each
15713 column. This is a repetitive act, which means we can use a
15714 decrementing @code{while} loop or recursive function for the job. In
15715 this section, we will write the definition using a @code{while} loop.
15717 The @code{column-of-graph} function requires the height of the graph
15718 as an argument, so we should determine and record that as a local variable.
15720 This leads us to the following template for the @code{while} loop
15721 version of this function:
15725 (defun graph-body-print (numbers-list)
15726 "@var{documentation}@dots{}"
15727 (let ((height @dots{}
15732 (while numbers-list
15733 @var{insert-columns-and-reposition-point}
15734 (setq numbers-list (cdr numbers-list)))))
15739 We need to fill in the slots of the template.
15741 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
15742 determine the height of the graph.
15744 The @code{while} loop will cycle through the @code{numbers-list} one
15745 element at a time. As it is shortened by the @code{(setq numbers-list
15746 (cdr numbers-list))} expression, the @sc{car} of each instance of the
15747 list is the value of the argument for @code{column-of-graph}.
15749 At each cycle of the @code{while} loop, the @code{insert-rectangle}
15750 function inserts the list returned by @code{column-of-graph}. Since
15751 the @code{insert-rectangle} function moves point to the lower right of
15752 the inserted rectangle, we need to save the location of point at the
15753 time the rectangle is inserted, move back to that position after the
15754 rectangle is inserted, and then move horizontally to the next place
15755 from which @code{insert-rectangle} is called.
15757 If the inserted columns are one character wide, as they will be if
15758 single blanks and asterisks are used, the repositioning command is
15759 simply @code{(forward-char 1)}; however, the width of a column may be
15760 greater than one. This means that the repositioning command should be
15761 written @code{(forward-char symbol-width)}. The @code{symbol-width}
15762 itself is the length of a @code{graph-blank} and can be found using
15763 the expression @code{(length graph-blank)}. The best place to bind
15764 the @code{symbol-width} variable to the value of the width of graph
15765 column is in the varlist of the @code{let} expression.
15768 These considerations lead to the following function definition:
15772 (defun graph-body-print (numbers-list)
15773 "Print a bar graph of the NUMBERS-LIST.
15774 The numbers-list consists of the Y-axis values."
15776 (let ((height (apply 'max numbers-list))
15777 (symbol-width (length graph-blank))
15782 (while numbers-list
15783 (setq from-position (point))
15785 (column-of-graph height (car numbers-list)))
15786 (goto-char from-position)
15787 (forward-char symbol-width)
15790 ;; @r{Draw graph column by column.}
15792 (setq numbers-list (cdr numbers-list)))
15795 ;; @r{Place point for X axis labels.}
15796 (forward-line height)
15803 The one unexpected expression in this function is the
15804 @w{@code{(sit-for 0)}} expression in the @code{while} loop. This
15805 expression makes the graph printing operation more interesting to
15806 watch than it would be otherwise. The expression causes Emacs to
15807 `sit' or do nothing for a zero length of time and then redraw the
15808 screen. Placed here, it causes Emacs to redraw the screen column by
15809 column. Without it, Emacs would not redraw the screen until the
15812 We can test @code{graph-body-print} with a short list of numbers.
15816 Install @code{graph-symbol}, @code{graph-blank},
15817 @code{column-of-graph}, which are in
15819 @ref{Readying a Graph, , Readying a Graph},
15822 @ref{Columns of a graph},
15824 and @code{graph-body-print}.
15828 Copy the following expression:
15831 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
15835 Switch to the @file{*scratch*} buffer and place the cursor where you
15836 want the graph to start.
15839 Type @kbd{M-:} (@code{eval-expression}).
15842 Yank the @code{graph-body-print} expression into the minibuffer
15843 with @kbd{C-y} (@code{yank)}.
15846 Press @key{RET} to evaluate the @code{graph-body-print} expression.
15850 Emacs will print a graph like this:
15864 @node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph
15865 @section The @code{recursive-graph-body-print} Function
15866 @findex recursive-graph-body-print
15868 The @code{graph-body-print} function may also be written recursively.
15869 The recursive solution is divided into two parts: an outside `wrapper'
15870 that uses a @code{let} expression to determine the values of several
15871 variables that need only be found once, such as the maximum height of
15872 the graph, and an inside function that is called recursively to print
15876 The `wrapper' is uncomplicated:
15880 (defun recursive-graph-body-print (numbers-list)
15881 "Print a bar graph of the NUMBERS-LIST.
15882 The numbers-list consists of the Y-axis values."
15883 (let ((height (apply 'max numbers-list))
15884 (symbol-width (length graph-blank))
15886 (recursive-graph-body-print-internal
15893 The recursive function is a little more difficult. It has four parts:
15894 the `do-again-test', the printing code, the recursive call, and the
15895 `next-step-expression'. The `do-again-test' is an @code{if}
15896 expression that determines whether the @code{numbers-list} contains
15897 any remaining elements; if it does, the function prints one column of
15898 the graph using the printing code and calls itself again. The
15899 function calls itself again according to the value produced by the
15900 `next-step-expression' which causes the call to act on a shorter
15901 version of the @code{numbers-list}.
15905 (defun recursive-graph-body-print-internal
15906 (numbers-list height symbol-width)
15907 "Print a bar graph.
15908 Used within recursive-graph-body-print function."
15914 (setq from-position (point))
15916 (column-of-graph height (car numbers-list)))
15919 (goto-char from-position)
15920 (forward-char symbol-width)
15921 (sit-for 0) ; @r{Draw graph column by column.}
15922 (recursive-graph-body-print-internal
15923 (cdr numbers-list) height symbol-width))))
15928 After installation, this expression can be tested; here is a sample:
15931 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
15935 Here is what @code{recursive-graph-body-print} produces:
15949 Either of these two functions, @code{graph-body-print} or
15950 @code{recursive-graph-body-print}, create the body of a graph.
15952 @node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph
15953 @section Need for Printed Axes
15955 A graph needs printed axes, so you can orient yourself. For a do-once
15956 project, it may be reasonable to draw the axes by hand using Emacs'
15957 Picture mode; but a graph drawing function may be used more than once.
15959 For this reason, I have written enhancements to the basic
15960 @code{print-graph-body} function that automatically print labels for
15961 the horizontal and vertical axes. Since the label printing functions
15962 do not contain much new material, I have placed their description in
15963 an appendix. @xref{Full Graph, , A Graph with Labelled Axes}.
15965 @node Line Graph Exercise, , Printed Axes, Readying a Graph
15968 Write a line graph version of the graph printing functions.
15970 @node Emacs Initialization, Debugging, Readying a Graph, Top
15971 @chapter Your @file{.emacs} File
15972 @cindex @file{.emacs} file
15973 @cindex Customizing your @file{.emacs} file
15974 @cindex Initialization file
15976 ``You don't have to like Emacs to like it'' -- this seemingly
15977 paradoxical statement is the secret of GNU Emacs. The plain, `out of
15978 the box' Emacs is a generic tool. Most people who use it, customize
15979 it to suit themselves.
15981 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
15982 expressions in Emacs Lisp you can change or extend Emacs.
15985 * Default Configuration::
15986 * Site-wide Init:: You can write site-wide init files.
15987 * defcustom:: Emacs will write code for you.
15988 * Beginning a .emacs File:: How to write a @code{.emacs file}.
15989 * Text and Auto-fill:: Automatically wrap lines.
15990 * Mail Aliases:: Use abbreviations for email addresses.
15991 * Indent Tabs Mode:: Don't use tabs with @TeX{}
15992 * Keybindings:: Create some personal keybindings.
15993 * Keymaps:: More about key binding.
15994 * Loading Files:: Load (i.e., evaluate) files automatically.
15995 * Autoload:: Make functions available.
15996 * Simple Extension:: Define a function; bind it to a key.
15997 * X11 Colors:: Colors in version 19 in X.
15999 * Mode Line:: How to customize your mode line.
16002 @node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
16004 @unnumberedsec Emacs' Default Configuration
16007 There are those who appreciate Emacs' default configuration. After
16008 all, Emacs starts you in C mode when you edit a C file, starts you in
16009 Fortran mode when you edit a Fortran file, and starts you in
16010 Fundamental mode when you edit an unadorned file. This all makes
16011 sense, if you do not know who is going to use Emacs. Who knows what a
16012 person hopes to do with an unadorned file? Fundamental mode is the
16013 right default for such a file, just as C mode is the right default for
16014 editing C code. But when you do know who is going to use Emacs---you,
16015 yourself---then it makes sense to customize Emacs.
16017 For example, I seldom want Fundamental mode when I edit an
16018 otherwise undistinguished file; I want Text mode. This is why I
16019 customize Emacs: so it suits me.
16021 You can customize and extend Emacs by writing or adapting a
16022 @file{~/.emacs} file. This is your personal initialization file; its
16023 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
16024 may also add @file{.el} to @file{~/.emacs} and call it a
16025 @file{~/.emacs.el} file. In the past, you were forbidden to type the
16026 extra keystrokes that the name @file{~/.emacs.el} requires, but now
16027 you may. The new format is consistent with the Emacs Lisp file
16028 naming conventions; the old format saves typing.}
16030 A @file{~/.emacs} file contains Emacs Lisp code. You can write this
16031 code yourself; or you can use Emacs' @code{customize} feature to write
16032 the code for you. You can combine your own expressions and
16033 auto-written Customize expressions in your @file{.emacs} file.
16035 (I myself prefer to write my own expressions, except for those,
16036 particularly fonts, that I find easier to manipulate using the
16037 @code{customize} command. I combine the two methods.)
16039 Most of this chapter is about writing expressions yourself. It
16040 describes a simple @file{.emacs} file; for more information, see
16041 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
16042 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
16045 @node Site-wide Init, defcustom, Default Configuration, Emacs Initialization
16046 @section Site-wide Initialization Files
16048 @cindex @file{default.el} init file
16049 @cindex @file{site-init.el} init file
16050 @cindex @file{site-load.el} init file
16051 In addition to your personal initialization file, Emacs automatically
16052 loads various site-wide initialization files, if they exist. These
16053 have the same form as your @file{.emacs} file, but are loaded by
16056 Two site-wide initialization files, @file{site-load.el} and
16057 @file{site-init.el}, are loaded into Emacs and then `dumped' if a
16058 `dumped' version of Emacs is created, as is most common. (Dumped
16059 copies of Emacs load more quickly. However, once a file is loaded and
16060 dumped, a change to it does not lead to a change in Emacs unless you
16061 load it yourself or re-dump Emacs. @xref{Building Emacs, , Building
16062 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
16063 @file{INSTALL} file.)
16065 Three other site-wide initialization files are loaded automatically
16066 each time you start Emacs, if they exist. These are
16067 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
16068 file, and @file{default.el}, and the terminal type file, which are both
16069 loaded @emph{after} your @file{.emacs} file.
16071 Settings and definitions in your @file{.emacs} file will overwrite
16072 conflicting settings and definitions in a @file{site-start.el} file,
16073 if it exists; but the settings and definitions in a @file{default.el}
16074 or terminal type file will overwrite those in your @file{.emacs} file.
16075 (You can prevent interference from a terminal type file by setting
16076 @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A
16077 Simple Extension}.)
16079 @c Rewritten to avoid overfull hbox.
16080 The @file{INSTALL} file that comes in the distribution contains
16081 descriptions of the @file{site-init.el} and @file{site-load.el} files.
16083 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
16084 control loading. These files are in the @file{lisp} directory of the
16085 Emacs distribution and are worth perusing.
16087 The @file{loaddefs.el} file contains a good many suggestions as to
16088 what to put into your own @file{.emacs} file, or into a site-wide
16089 initialization file.
16091 @node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization
16092 @section Specifying Variables using @code{defcustom}
16095 You can specify variables using @code{defcustom} so that you and
16096 others can then use Emacs' @code{customize} feature to set their
16097 values. (You cannot use @code{customize} to write function
16098 definitions; but you can write @code{defuns} in your @file{.emacs}
16099 file. Indeed, you can write any Lisp expression in your @file{.emacs}
16102 The @code{customize} feature depends on the @code{defcustom} special
16103 form. Although you can use @code{defvar} or @code{setq} for variables
16104 that users set, the @code{defcustom} special form is designed for the
16107 You can use your knowledge of @code{defvar} for writing the
16108 first three arguments for @code{defcustom}. The first argument to
16109 @code{defcustom} is the name of the variable. The second argument is
16110 the variable's initial value, if any; and this value is set only if
16111 the value has not already been set. The third argument is the
16114 The fourth and subsequent arguments to @code{defcustom} specify types
16115 and options; these are not featured in @code{defvar}. (These
16116 arguments are optional.)
16118 Each of these arguments consists of a keyword followed by a value.
16119 Each keyword starts with the colon character @samp{:}.
16122 For example, the customizable user option variable
16123 @code{text-mode-hook} looks like this:
16127 (defcustom text-mode-hook nil
16128 "Normal hook run when entering Text mode and many related modes."
16130 :options '(turn-on-auto-fill flyspell-mode)
16136 The name of the variable is @code{text-mode-hook}; it has no default
16137 value; and its documentation string tells you what it does.
16139 The @code{:type} keyword tells Emacs the kind of data to which
16140 @code{text-mode-hook} should be set and how to display the value in a
16141 Customization buffer.
16143 The @code{:options} keyword specifies a suggested list of values for
16144 the variable. Currently, you can use @code{:options} only for a hook.
16145 The list is only a suggestion; it is not exclusive; a person who sets
16146 the variable may set it to other values; the list shown following the
16147 @code{:options} keyword is intended to offer convenient choices to a
16150 Finally, the @code{:group} keyword tells the Emacs Customization
16151 command in which group the variable is located. This tells where to
16154 For more information, see @ref{Customization, , Writing Customization
16155 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
16157 Consider @code{text-mode-hook} as an example.
16159 There are two ways to customize this variable. You can use the
16160 customization command or write the appropriate expressions yourself.
16163 Using the customization command, you can type:
16170 and find that the group for editing files of data is called `data'.
16171 Enter that group. Text Mode Hook is the first member. You can click
16172 on its various options to set the values. After you click on the
16176 Save for Future Sessions
16180 Emacs will write an expression into your @file{.emacs} file.
16181 It will look like this:
16185 (custom-set-variables
16186 ;; custom-set-variables was added by Custom --
16187 ;; don't edit or cut/paste it!
16188 ;; Your init file should contain only one such instance.
16189 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
16194 (The @code{text-mode-hook-identify} function tells
16195 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.)
16197 In spite of the warning, you certainly may edit, cut, and paste the
16198 expression! I do all time. The purpose of the warning is to scare
16199 those who do not know what they are doing, so they do not
16200 inadvertently generate an error.
16202 The @code{custom-set-variables} function works somewhat differently
16203 than a @code{setq}. While I have never learned the differences, I do
16204 modify the @code{custom-set-variables} expressions in my @file{.emacs}
16205 file by hand: I make the changes in what appears to me to be a
16206 reasonable manner and have not had any problems. Others prefer to use
16207 the Customization command and let Emacs do the work for them.
16209 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
16210 This function sets the various font faces. Over time, I have set a
16211 considerable number of faces. Some of the time, I re-set them using
16212 @code{customize}; other times, I simply edit the
16213 @code{custom-set-faces} expression in my @file{.emacs} file itself.
16215 The second way to customize your @code{text-mode-hook} is to set it
16216 yourself in your @file{.emacs} file using code that has nothing to do
16217 with the @code{custom-set-@dots{}} functions.
16220 When you do this, and later use @code{customize}, you will see a
16224 this option has been changed outside the customize buffer.
16228 This message is only a warning. If you click on the button to
16231 Save for Future Sessions
16235 Emacs will write a @code{custom-set-@dots{}} expression near the end
16236 of your @file{.emacs} file that will be evaluated after your
16237 hand-written expression. It will, therefore, overrule your
16238 hand-written expression. No harm will be done. When you do this,
16239 however, be careful to remember which expression is active; if you
16240 forget, you may confuse yourself.
16242 So long as you remember where the values are set, you will have no
16243 trouble. In any event, the values are always set in your
16244 initialization file, which is usually called @file{.emacs}.
16246 I myself use @code{customize} for hardly anything. Mostly, I write
16247 expressions myself.
16249 @node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization
16250 @section Beginning a @file{.emacs} File
16251 @cindex @file{.emacs} file, beginning of
16253 When you start Emacs, it loads your @file{.emacs} file unless you tell
16254 it not to by specifying @samp{-q} on the command line. (The
16255 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
16257 A @file{.emacs} file contains Lisp expressions. Often, these are no
16258 more than expressions to set values; sometimes they are function
16261 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
16262 Manual}, for a short description of initialization files.
16264 This chapter goes over some of the same ground, but is a walk among
16265 extracts from a complete, long-used @file{.emacs} file---my own.
16267 The first part of the file consists of comments: reminders to myself.
16268 By now, of course, I remember these things, but when I started, I did
16274 ;;;; Bob's .emacs file
16275 ; Robert J. Chassell
16276 ; 26 September 1985
16281 Look at that date! I started this file a long time ago. I have been
16282 adding to it ever since.
16286 ; Each section in this file is introduced by a
16287 ; line beginning with four semicolons; and each
16288 ; entry is introduced by a line beginning with
16289 ; three semicolons.
16294 This describes the usual conventions for comments in Emacs Lisp.
16295 Everything on a line that follows a semicolon is a comment. Two,
16296 three, and four semicolons are used as section and subsection
16297 markers. (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference
16298 Manual}, for more about comments.)
16303 ; Control-h is the help key;
16304 ; after typing control-h, type a letter to
16305 ; indicate the subject about which you want help.
16306 ; For an explanation of the help facility,
16307 ; type control-h two times in a row.
16312 Just remember: type @kbd{C-h} two times for help.
16316 ; To find out about any mode, type control-h m
16317 ; while in that mode. For example, to find out
16318 ; about mail mode, enter mail mode and then type
16324 `Mode help', as I call this, is very helpful. Usually, it tells you
16325 all you need to know.
16327 Of course, you don't need to include comments like these in your
16328 @file{.emacs} file. I included them in mine because I kept forgetting
16329 about Mode help or the conventions for comments---but I was able to
16330 remember to look here to remind myself.
16332 @node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization
16333 @section Text and Auto Fill Mode
16335 Now we come to the part that `turns on' Text mode and
16340 ;;; Text mode and Auto Fill mode
16341 ; The next three lines put Emacs into Text mode
16342 ; and Auto Fill mode, and are for writers who
16343 ; want to start writing prose rather than code.
16345 (setq default-major-mode 'text-mode)
16346 (add-hook 'text-mode-hook 'text-mode-hook-identify)
16347 (add-hook 'text-mode-hook 'turn-on-auto-fill)
16351 Here is the first part of this @file{.emacs} file that does something
16352 besides remind a forgetful human!
16354 The first of the two lines in parentheses tells Emacs to turn on Text
16355 mode when you find a file, @emph{unless} that file should go into some
16356 other mode, such as C mode.
16358 @cindex Per-buffer, local variables list
16359 @cindex Local variables list, per-buffer,
16360 @cindex Automatic mode selection
16361 @cindex Mode selection, automatic
16362 When Emacs reads a file, it looks at the extension to the file name,
16363 if any. (The extension is the part that comes after a @samp{.}.) If
16364 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
16365 on C mode. Also, Emacs looks at first nonblank line of the file; if
16366 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs
16367 possesses a list of extensions and specifications that it uses
16368 automatically. In addition, Emacs looks near the last page for a
16369 per-buffer, ``local variables list'', if any.
16372 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
16375 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
16379 See sections ``How Major Modes are Chosen'' and ``Local Variables in
16380 Files'' in @cite{The GNU Emacs Manual}.
16383 Now, back to the @file{.emacs} file.
16386 Here is the line again; how does it work?
16388 @cindex Text Mode turned on
16390 (setq default-major-mode 'text-mode)
16394 This line is a short, but complete Emacs Lisp expression.
16396 We are already familiar with @code{setq}. It sets the following variable,
16397 @code{default-major-mode}, to the subsequent value, which is
16398 @code{text-mode}. The single quote mark before @code{text-mode} tells
16399 Emacs to deal directly with the @code{text-mode} variable, not with
16400 whatever it might stand for. @xref{set & setq, , Setting the Value of
16401 a Variable}, for a reminder of how @code{setq} works. The main point
16402 is that there is no difference between the procedure you use to set
16403 a value in your @file{.emacs} file and the procedure you use anywhere
16407 Here are the next two lines:
16409 @cindex Auto Fill mode turned on
16412 (add-hook 'text-mode-hook 'text-mode-hook-identify)
16413 (add-hook 'text-mode-hook 'turn-on-auto-fill)
16417 In these two lines, the @code{add-hook} command first adds
16418 @code{text-mode-hook-identify} to the variable called
16419 @code{text-mode-hook} and then adds @code{turn-on-auto-fill} to the
16422 @code{turn-on-auto-fill} is the name of a program, that, you guessed
16423 it!, turns on Auto Fill mode. @code{text-mode-hook-identify} is a
16424 function that tells @code{toggle-text-mode-auto-fill} which buffers
16427 Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
16428 onto Text mode. So every time Emacs turns on Text mode, Emacs also
16429 turns on Auto Fill mode.
16431 In brief, the first line causes Emacs to enter Text mode when you edit
16432 a file, unless the file name extension, first non-blank line, or local
16433 variables tell Emacs otherwise.
16435 Text mode among other actions, sets the syntax table to work
16436 conveniently for writers. In Text mode, Emacs considers an apostrophe
16437 as part of a word like a letter; but Emacs does not consider a period
16438 or a space as part of a word. Thus, @kbd{M-f} moves you over
16439 @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
16440 the @samp{t} of @samp{it's}.
16442 The second and third lines causes Emacs to turn on Auto Fill mode when
16443 it turns on Text mode. In Auto Fill mode, Emacs automatically breaks
16444 a line that is too wide and brings the excessively wide part of the
16445 line down to the next line. Emacs breaks lines between words, not
16448 When Auto Fill mode is turned off, lines continue to the right as you
16449 type them. Depending on how you set the value of
16450 @code{truncate-lines}, the words you type either disappear off the
16451 right side of the screen, or else are shown, in a rather ugly and
16452 unreadable manner, as a continuation line on the screen.
16455 In addition, in this part of my @file{.emacs} file, I tell the Emacs
16456 fill commands to insert two spaces after a colon:
16459 (setq colon-double-space t)
16462 @node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization
16463 @section Mail Aliases
16465 Here is a @code{setq} that `turns on' mail aliases, along with more
16471 ; To enter mail mode, type `C-x m'
16472 ; To enter RMAIL (for reading mail),
16475 (setq mail-aliases t)
16479 @cindex Mail aliases
16481 This @code{setq} command sets the value of the variable
16482 @code{mail-aliases} to @code{t}. Since @code{t} means true, the line
16483 says, in effect, ``Yes, use mail aliases.''
16485 Mail aliases are convenient short names for long email addresses or
16486 for lists of email addresses. The file where you keep your `aliases'
16487 is @file{~/.mailrc}. You write an alias like this:
16490 alias geo george@@foobar.wiz.edu
16494 When you write a message to George, address it to @samp{geo}; the
16495 mailer will automatically expand @samp{geo} to the full address.
16497 @node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization
16498 @section Indent Tabs Mode
16499 @cindex Tabs, preventing
16500 @findex indent-tabs-mode
16502 By default, Emacs inserts tabs in place of multiple spaces when it
16503 formats a region. (For example, you might indent many lines of text
16504 all at once with the @code{indent-region} command.) Tabs look fine on
16505 a terminal or with ordinary printing, but they produce badly indented
16506 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
16509 The following turns off Indent Tabs mode:
16513 ;;; Prevent Extraneous Tabs
16514 (setq-default indent-tabs-mode nil)
16518 Note that this line uses @code{setq-default} rather than the
16519 @code{setq} command that we have seen before. The @code{setq-default}
16520 command sets values only in buffers that do not have their own local
16521 values for the variable.
16524 @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}.
16526 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
16530 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
16531 Files'' in @cite{The GNU Emacs Manual}.
16534 @node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization
16535 @section Some Keybindings
16537 Now for some personal keybindings:
16541 ;;; Compare windows
16542 (global-set-key "\C-cw" 'compare-windows)
16546 @findex compare-windows
16547 @code{compare-windows} is a nifty command that compares the text in
16548 your current window with text in the next window. It makes the
16549 comparison by starting at point in each window, moving over text in
16550 each window as far as they match. I use this command all the time.
16552 This also shows how to set a key globally, for all modes.
16554 @cindex Setting a key globally
16555 @cindex Global set key
16556 @cindex Key setting globally
16557 @findex global-set-key
16558 The command is @code{global-set-key}. It is followed by the
16559 keybinding. In a @file{.emacs} file, the keybinding is written as
16560 shown: @code{\C-c} stands for `control-c', which means `press the
16561 control key and the @kbd{c} key at the same time'. The @code{w} means
16562 `press the @kbd{w} key'. The keybinding is surrounded by double
16563 quotation marks. In documentation, you would write this as @kbd{C-c
16564 w}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather
16565 than a @key{CTL} key, you would write @code{\M-c}. @xref{Init
16566 Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU Emacs
16567 Manual}, for details.)
16569 The command invoked by the keys is @code{compare-windows}. Note that
16570 @code{compare-windows} is preceded by a single quote; otherwise, Emacs
16571 would first try to evaluate the symbol to determine its value.
16573 These three things, the double quotation marks, the backslash before
16574 the @samp{C}, and the single quote mark are necessary parts of
16575 keybinding that I tend to forget. Fortunately, I have come to
16576 remember that I should look at my existing @file{.emacs} file, and
16577 adapt what is there.
16579 As for the keybinding itself: @kbd{C-c w}. This combines the prefix
16580 key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This
16581 set of keys, @kbd{C-c} followed by a single character, is strictly
16582 reserved for individuals' own use. (I call these `own' keys, since
16583 these are for my own use.) You should always be able to create such a
16584 keybinding for your own use without stomping on someone else's
16585 keybinding. If you ever write an extension to Emacs, please avoid
16586 taking any of these keys for public use. Create a key like @kbd{C-c
16587 C-w} instead. Otherwise, we will run out of `own' keys.
16590 Here is another keybinding, with a comment:
16594 ;;; Keybinding for `occur'
16595 ; I use occur a lot, so let's bind it to a key:
16596 (global-set-key "\C-co" 'occur)
16601 The @code{occur} command shows all the lines in the current buffer
16602 that contain a match for a regular expression. Matching lines are
16603 shown in a buffer called @file{*Occur*}. That buffer serves as a menu
16604 to jump to occurrences.
16606 @findex global-unset-key
16607 @cindex Unbinding key
16608 @cindex Key unbinding
16610 Here is how to unbind a key, so it does not
16616 (global-unset-key "\C-xf")
16620 There is a reason for this unbinding: I found I inadvertently typed
16621 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a
16622 file, as I intended, I accidentally set the width for filled text,
16623 almost always to a width I did not want. Since I hardly ever reset my
16624 default width, I simply unbound the key.
16626 @findex list-buffers, @r{rebound}
16627 @findex buffer-menu, @r{bound to key}
16629 The following rebinds an existing key:
16633 ;;; Rebind `C-x C-b' for `buffer-menu'
16634 (global-set-key "\C-x\C-b" 'buffer-menu)
16638 By default, @kbd{C-x C-b} runs the
16639 @code{list-buffers} command. This command lists
16640 your buffers in @emph{another} window. Since I
16641 almost always want to do something in that
16642 window, I prefer the @code{buffer-menu}
16643 command, which not only lists the buffers,
16644 but moves point into that window.
16646 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
16649 @cindex Rebinding keys
16651 Emacs uses @dfn{keymaps} to record which keys call which commands.
16652 When you use @code{global-set-key} to set the keybinding for a single
16653 command in all parts of Emacs, you are specifying the keybinding in
16654 @code{current-global-map}.
16656 Specific modes, such as C mode or Text mode, have their own keymaps;
16657 the mode-specific keymaps override the global map that is shared by
16660 The @code{global-set-key} function binds, or rebinds, the global
16661 keymap. For example, the following binds the key @kbd{C-x C-b} to the
16662 function @code{buffer-menu}:
16665 (global-set-key "\C-x\C-b" 'buffer-menu)
16668 Mode-specific keymaps are bound using the @code{define-key} function,
16669 which takes a specific keymap as an argument, as well as the key and
16670 the command. For example, my @file{.emacs} file contains the
16671 following expression to bind the @code{texinfo-insert-@@group} command
16672 to @kbd{C-c C-c g}:
16676 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
16681 The @code{texinfo-insert-@@group} function itself is a little extension
16682 to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I
16683 use this command all the time and prefer to type the three strokes
16684 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
16685 (@samp{@@group} and its matching @samp{@@end group} are commands that
16686 keep all enclosed text together on one page; many multi-line examples
16687 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
16690 Here is the @code{texinfo-insert-@@group} function definition:
16694 (defun texinfo-insert-@@group ()
16695 "Insert the string @@group in a Texinfo buffer."
16697 (beginning-of-line)
16698 (insert "@@group\n"))
16702 (Of course, I could have used Abbrev mode to save typing, rather than
16703 write a function to insert a word; but I prefer key strokes consistent
16704 with other Texinfo mode key bindings.)
16706 You will see numerous @code{define-key} expressions in
16707 @file{loaddefs.el} as well as in the various mode libraries, such as
16708 @file{cc-mode.el} and @file{lisp-mode.el}.
16710 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
16711 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
16712 Reference Manual}, for more information about keymaps.
16714 @node Loading Files, Autoload, Keymaps, Emacs Initialization
16715 @section Loading Files
16716 @cindex Loading files
16719 Many people in the GNU Emacs community have written extensions to
16720 Emacs. As time goes by, these extensions are often included in new
16721 releases. For example, the Calendar and Diary packages are now part
16722 of the standard GNU Emacs, as is Calc.
16724 You can use a @code{load} command to evaluate a complete file and
16725 thereby install all the functions and variables in the file into Emacs.
16728 @c (auto-compression-mode t)
16731 (load "~/emacs/slowsplit")
16734 This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it
16735 exists, the faster, byte compiled @file{slowsplit.elc} file from the
16736 @file{emacs} sub-directory of your home directory. The file contains
16737 the function @code{split-window-quietly}, which John Robinson wrote in
16740 The @code{split-window-quietly} function splits a window with the
16741 minimum of redisplay. I installed it in 1989 because it worked well
16742 with the slow 1200 baud terminals I was then using. Nowadays, I only
16743 occasionally come across such a slow connection, but I continue to use
16744 the function because I like the way it leaves the bottom half of a
16745 buffer in the lower of the new windows and the top half in the upper
16749 To replace the key binding for the default
16750 @code{split-window-vertically}, you must also unset that key and bind
16751 the keys to @code{split-window-quietly}, like this:
16755 (global-unset-key "\C-x2")
16756 (global-set-key "\C-x2" 'split-window-quietly)
16761 If you load many extensions, as I do, then instead of specifying the
16762 exact location of the extension file, as shown above, you can specify
16763 that directory as part of Emacs' @code{load-path}. Then, when Emacs
16764 loads a file, it will search that directory as well as its default
16765 list of directories. (The default list is specified in @file{paths.h}
16766 when Emacs is built.)
16769 The following command adds your @file{~/emacs} directory to the
16770 existing load path:
16774 ;;; Emacs Load Path
16775 (setq load-path (cons "~/emacs" load-path))
16779 Incidentally, @code{load-library} is an interactive interface to the
16780 @code{load} function. The complete function looks like this:
16782 @findex load-library
16785 (defun load-library (library)
16786 "Load the library named LIBRARY.
16787 This is an interface to the function `load'."
16788 (interactive "sLoad library: ")
16793 The name of the function, @code{load-library}, comes from the use of
16794 `library' as a conventional synonym for `file'. The source for the
16795 @code{load-library} command is in the @file{files.el} library.
16797 Another interactive command that does a slightly different job is
16798 @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for
16799 Emacs, emacs, The GNU Emacs Manual}, for information on the
16800 distinction between @code{load-library} and this command.
16802 @node Autoload, Simple Extension, Loading Files, Emacs Initialization
16803 @section Autoloading
16806 Instead of installing a function by loading the file that contains it,
16807 or by evaluating the function definition, you can make the function
16808 available but not actually install it until it is first called. This
16809 is called @dfn{autoloading}.
16811 When you execute an autoloaded function, Emacs automatically evaluates
16812 the file that contains the definition, and then calls the function.
16814 Emacs starts quicker with autoloaded functions, since their libraries
16815 are not loaded right away; but you need to wait a moment when you
16816 first use such a function, while its containing file is evaluated.
16818 Rarely used functions are frequently autoloaded. The
16819 @file{loaddefs.el} library contains hundreds of autoloaded functions,
16820 from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may
16821 come to use a `rare' function frequently. When you do, you should
16822 load that function's file with a @code{load} expression in your
16823 @file{.emacs} file.
16825 In my @file{.emacs} file for Emacs version 21, I load 12 libraries
16826 that contain functions that would otherwise be autoloaded. (Actually,
16827 it would have been better to include these files in my `dumped' Emacs
16828 when I built it, but I forgot. @xref{Building Emacs, , Building
16829 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the @file{INSTALL}
16830 file for more about dumping.)
16832 You may also want to include autoloaded expressions in your @file{.emacs}
16833 file. @code{autoload} is a built-in function that takes up to five
16834 arguments, the final three of which are optional. The first argument
16835 is the name of the function to be autoloaded; the second is the name
16836 of the file to be loaded. The third argument is documentation for the
16837 function, and the fourth tells whether the function can be called
16838 interactively. The fifth argument tells what type of
16839 object---@code{autoload} can handle a keymap or macro as well as a
16840 function (the default is a function).
16843 Here is a typical example:
16847 (autoload 'html-helper-mode
16848 "html-helper-mode" "Edit HTML documents" t)
16853 (@code{html-helper-mode} is an alternative to @code{html-mode}, which
16854 is a standard part of the distribution).
16857 This expression autoloads the @code{html-helper-mode} function. It
16858 takes it from the @file{html-helper-mode.el} file (or from the byte
16859 compiled file @file{html-helper-mode.elc}, if it exists.) The file
16860 must be located in a directory specified by @code{load-path}. The
16861 documentation says that this is a mode to help you edit documents
16862 written in the HyperText Markup Language. You can call this mode
16863 interactively by typing @kbd{M-x html-helper-mode}. (You need to
16864 duplicate the function's regular documentation in the autoload
16865 expression because the regular function is not yet loaded, so its
16866 documentation is not available.)
16868 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
16869 Manual}, for more information.
16871 @node Simple Extension, X11 Colors, Autoload, Emacs Initialization
16872 @section A Simple Extension: @code{line-to-top-of-window}
16873 @findex line-to-top-of-window
16874 @cindex Simple extension in @file{.emacs} file
16876 Here is a simple extension to Emacs that moves the line point is on to
16877 the top of the window. I use this all the time, to make text easier
16880 You can put the following code into a separate file and then load it
16881 from your @file{.emacs} file, or you can include it within your
16882 @file{.emacs} file.
16885 Here is the definition:
16889 ;;; Line to top of window;
16890 ;;; replace three keystroke sequence C-u 0 C-l
16891 (defun line-to-top-of-window ()
16892 "Move the line point is on to top of window."
16899 Now for the keybinding.
16901 Nowadays, function keys as well as mouse button events and
16902 non-@sc{ascii} characters are written within square brackets, without
16903 quotation marks. (In Emacs version 18 and before, you had to write
16904 different function key bindings for each different make of terminal.)
16906 I bind @code{line-to-top-of-window} to my @key{F6} function key like
16910 (global-set-key [f6] 'line-to-top-of-window)
16913 For more information, see @ref{Init Rebinding, , Rebinding Keys in
16914 Your Init File, emacs, The GNU Emacs Manual}.
16916 @cindex Conditional 'twixt two versions of Emacs
16917 @cindex Version of Emacs, choosing
16918 @cindex Emacs version, choosing
16919 If you run two versions of GNU Emacs, such as versions 20 and 21, and
16920 use one @file{.emacs} file, you can select which code to evaluate with
16921 the following conditional:
16926 ((string-equal (number-to-string 20) (substring (emacs-version) 10 12))
16927 ;; evaluate version 20 code
16929 ((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
16930 ;; evaluate version 21 code
16935 For example, in contrast to version 20, version 21 blinks its cursor
16936 by default. I hate such blinking, as well as some other features in
16937 version 21, so I placed the following in my @file{.emacs}
16938 file@footnote{When I start instances of Emacs that do not load my
16939 @file{.emacs} file or any site file, I also turn off blinking:
16942 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
16948 (if (string-equal "21" (substring (emacs-version) 10 12))
16950 (blink-cursor-mode 0)
16951 ;; Insert newline when you press `C-n' (next-line)
16952 ;; at the end of the buffer
16953 (setq next-line-add-newlines t)
16956 ;; Turn on image viewing
16957 (auto-image-file-mode t)
16960 ;; Turn on menu bar (this bar has text)
16961 ;; (Use numeric argument to turn on)
16965 ;; Turn off tool bar (this bar has icons)
16966 ;; (Use numeric argument to turn on)
16967 (tool-bar-mode nil)
16970 ;; Turn off tooltip mode for tool bar
16971 ;; (This mode causes icon explanations to pop up)
16972 ;; (Use numeric argument to turn on)
16974 ;; If tooltips turned on, make tips appear promptly
16975 (setq tooltip-delay 0.1) ; default is one second
16981 (You will note that instead of typing @code{(number-to-string 21)}, I
16982 decided to save typing and wrote `21' as a string, @code{"21"}, rather
16983 than convert it from an integer to a string. In this instance, this
16984 expression is better than the longer, but more general
16985 @code{(number-to-string 21)}. However, if you do not know ahead of
16986 time what type of information will be returned, then the
16987 @code{number-to-string} function will be needed.)
16989 @node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
16990 @section X11 Colors
16992 You can specify colors when you use Emacs with the MIT X Windowing
16995 I dislike the default colors and specify my own.
16998 Here are the expressions in my @file{.emacs}
16999 file that set values:
17003 ;; Set cursor color
17004 (set-cursor-color "white")
17007 (set-mouse-color "white")
17009 ;; Set foreground and background
17010 (set-foreground-color "white")
17011 (set-background-color "darkblue")
17015 ;;; Set highlighting colors for isearch and drag
17016 (set-face-foreground 'highlight "white")
17017 (set-face-background 'highlight "blue")
17021 (set-face-foreground 'region "cyan")
17022 (set-face-background 'region "blue")
17026 (set-face-foreground 'secondary-selection "skyblue")
17027 (set-face-background 'secondary-selection "darkblue")
17031 ;; Set calendar highlighting colors
17032 (setq calendar-load-hook
17034 (set-face-foreground 'diary-face "skyblue")
17035 (set-face-background 'holiday-face "slate blue")
17036 (set-face-foreground 'holiday-face "white")))
17040 The various shades of blue soothe my eye and prevent me from seeing
17041 the screen flicker.
17043 Alternatively, I could have set my specifications in various X
17044 initialization files. For example, I could set the foreground,
17045 background, cursor, and pointer (i.e., mouse) colors in my
17046 @file{~/.Xresources} file like this:
17050 Emacs*foreground: white
17051 Emacs*background: darkblue
17052 Emacs*cursorColor: white
17053 Emacs*pointerColor: white
17057 In any event, since it is not part of Emacs, I set the root color of
17058 my X window in my @file{~/.xinitrc} file, like this@footnote{I
17059 occasionally run more modern window managers, such as Sawfish with
17060 GNOME, Enlightenment, SCWM, or KDE; in those cases, I often specify an
17061 image rather than a plain color.}:
17065 # I use TWM for window manager.
17066 xsetroot -solid Navy -fg white &
17070 @node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
17071 @section Miscellaneous Settings for a @file{.emacs} File
17073 Here are a few miscellaneous settings:
17078 Set the shape and color of the mouse cursor:
17081 ; Cursor shapes are defined in
17082 ; `/usr/include/X11/cursorfont.h';
17083 ; for example, the `target' cursor is number 128;
17084 ; the `top_left_arrow' cursor is number 132.
17088 (let ((mpointer (x-get-resource "*mpointer"
17089 "*emacs*mpointer")))
17090 ;; If you have not set your mouse pointer
17091 ;; then set it, otherwise leave as is:
17092 (if (eq mpointer nil)
17093 (setq mpointer "132")) ; top_left_arrow
17096 (setq x-pointer-shape (string-to-int mpointer))
17097 (set-mouse-color "white"))
17102 Convert @kbd{@key{CTL}-h} into @key{DEL} and @key{DEL}
17103 into @kbd{@key{CTL}-h}.@*
17104 (Some older keyboards needed this, although I have not seen the
17109 ;; Translate `C-h' to <DEL>.
17110 ; (keyboard-translate ?\C-h ?\C-?)
17112 ;; Translate <DEL> to `C-h'.
17113 (keyboard-translate ?\C-? ?\C-h)
17117 @item Turn off a blinking cursor!
17121 (if (fboundp 'blink-cursor-mode)
17122 (blink-cursor-mode -1))
17126 @item Ignore case when using `grep'@*
17127 @samp{-n}@w{ } Prefix each line of output with line number@*
17128 @samp{-i}@w{ } Ignore case distinctions@*
17129 @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-}
17132 (setq grep-command "grep -n -i -e ")
17135 @item Automatically uncompress compressed files when visiting them
17138 (load "uncompress")
17141 @item Find an existing buffer, even if it has a different name@*
17142 This avoids problems with symbolic links.
17145 (setq find-file-existing-other-name t)
17148 @item Set your language environment and default input method
17152 (set-language-environment "latin-1")
17153 ;; Remember you can enable or disable multilingual text input
17154 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
17155 (setq default-input-method "latin-1-prefix")
17159 If you want to write with Chinese `GB' characters, set this instead:
17163 (set-language-environment "Chinese-GB")
17164 (setq default-input-method "chinese-tonepy")
17169 @subsubheading Fixing Unpleasant Key Bindings
17170 @cindex Key bindings, fixing
17171 @cindex Bindings, key, fixing unpleasant
17173 Some systems bind keys unpleasantly. Sometimes, for example, the
17174 @key{CTL} key appears in an awkward spot rather than at the far left
17177 Usually, when people fix these sorts of keybindings, they do not
17178 change their @file{~/.emacs} file. Instead, they bind the proper keys
17179 on their consoles with the @code{loadkeys} or @code{install-keymap}
17180 commands in their boot script and then include @code{xmodmap} commands
17181 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
17189 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
17193 install-keymap emacs2
17199 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
17200 Lock} key is at the far left of the home row:
17204 # Bind the key labeled `Caps Lock' to `Control'
17205 # (Such a broken user interface suggests that keyboard manufacturers
17206 # think that computers are typewriters from 1885.)
17208 xmodmap -e "clear Lock"
17209 xmodmap -e "add Control = Caps_Lock"
17215 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
17216 key to a @key{META} key:
17220 # Some ill designed keyboards have a key labeled ALT and no Meta
17221 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
17225 @node Mode Line, , Miscellaneous, Emacs Initialization
17226 @section A Modified Mode Line
17227 @vindex default-mode-line-format
17228 @cindex Mode line format
17230 Finally, a feature I really like: a modified mode line.
17232 When I work over a network, I forget which machine I am using. Also,
17233 I tend to I lose track of where I am, and which line point is on.
17235 So I reset my mode line to look like this:
17238 -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top
17241 I am visiting a file called @file{foo.texi}, on my machine
17242 @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in
17243 Texinfo mode, and am at the top of the buffer.
17246 My @file{.emacs} file has a section that looks like this:
17250 ;; Set a Mode Line that tells me which machine, which directory,
17251 ;; and which line I am on, plus the other customary information.
17252 (setq default-mode-line-format
17256 "mouse-1: select window, mouse-2: delete others ..."))
17257 mode-line-mule-info
17259 mode-line-frame-identification
17263 mode-line-buffer-identification
17266 (system-name) 0 (string-match "\\..+" (system-name))))
17271 "mouse-1: select window, mouse-2: delete others ..."))
17272 (line-number-mode " Line %l ")
17278 "mouse-1: select window, mouse-2: delete others ..."))
17279 (:eval (mode-line-mode-name))
17282 #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
17291 Here, I redefine the default mode line. Most of the parts are from
17292 the original; but I make a few changes. I set the @emph{default} mode
17293 line format so as to permit various modes, such as Info, to override
17296 Many elements in the list are self-explanatory:
17297 @code{mode-line-modified} is a variable that tells whether the buffer
17298 has been modified, @code{mode-name} tells the name of the mode, and so
17299 on. However, the format looks complicated because of two features we
17300 have not discussed.
17302 @cindex Properties, in mode line example
17303 The first string in the mode line is a dash or hyphen, @samp{-}. In
17304 the old days, it would have been specified simply as @code{"-"}. But
17305 nowadays, Emacs can add properties to a string, such as highlighting
17306 or, as in this case, a help feature. If you place your mouse cursor
17307 over the hyphen, some help information appears (By default, you must
17308 wait one second before the information appears. You can change that
17309 timing by changing the value of @code{tooltip-delay}.)
17312 The new string format has a special syntax:
17315 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
17319 The @code{#(} begins a list. The first element of the list is the
17320 string itself, just one @samp{-}. The second and third
17321 elements specify the range over which the fourth element applies. A
17322 range starts @emph{after} a character, so a zero means the range
17323 starts just before the first character; a 1 means that the range ends
17324 just after the first character. The third element is the property for
17325 the range. It consists of a property list, a
17326 property name, in this case, @samp{help-echo}, followed by a value, in this
17327 case, a string. The second, third, and fourth elements of this new
17328 string format can be repeated.
17330 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
17331 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
17332 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
17334 @code{mode-line-buffer-identification}
17335 displays the current buffer name. It is a list
17336 beginning @code{(#("%12b" 0 4 @dots{}}.
17337 The @code{#(} begins the list.
17339 The @samp{"%12b"} displays the current buffer name, using the
17340 @code{buffer-name} function with which we are familiar; the `12'
17341 specifies the maximum number of characters that will be displayed.
17342 When a name has fewer characters, whitespace is added to fill out to
17343 this number. (Buffer names can and often should be longer than 12
17344 characters; this length works well in a typical 80 column wide
17347 @code{:eval} is a new feature in GNU Emacs version 21. It says to
17348 evaluate the following form and use the result as a string to display.
17349 In this case, the expression displays the first component of the full
17350 system name. The end of the first component is a @samp{.} (`period'),
17351 so I use the @code{string-match} function to tell me the length of the
17352 first component. The substring from the zeroth character to that
17353 length is the name of the machine.
17356 This is the expression:
17361 (system-name) 0 (string-match "\\..+" (system-name))))
17365 @samp{%[} and @samp{%]} cause a pair of square brackets
17366 to appear for each recursive editing level. @samp{%n} says `Narrow'
17367 when narrowing is in effect. @samp{%P} tells you the percentage of
17368 the buffer that is above the bottom of the window, or `Top', `Bottom',
17369 or `All'. (A lower case @samp{p} tell you the percentage above the
17370 @emph{top} of the window.) @samp{%-} inserts enough dashes to fill
17373 Remember, ``You don't have to like Emacs to like it'' --- your own
17374 Emacs can have different colors, different commands, and different
17375 keys than a default Emacs.
17377 On the other hand, if you want to bring up a plain `out of the box'
17378 Emacs, with no customization, type:
17385 This will start an Emacs that does @emph{not} load your
17386 @file{~/.emacs} initialization file. A plain, default Emacs. Nothing
17389 @node Debugging, Conclusion, Emacs Initialization, Top
17393 GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The
17394 first is built into the internals of Emacs and is always with you;
17395 the second requires that you instrument a function before you can use it.
17397 Both debuggers are described extensively in @ref{Debugging, ,
17398 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
17399 In this chapter, I will walk through a short example of each.
17402 * debug:: How to use the built-in debugger.
17403 * debug-on-entry:: Start debugging when you call a function.
17404 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
17405 * edebug:: How to use Edebug, a source level debugger.
17406 * Debugging Exercises::
17409 @node debug, debug-on-entry, Debugging, Debugging
17410 @section @code{debug}
17413 Suppose you have written a function definition that is intended to
17414 return the sum of the numbers 1 through a given number. (This is the
17415 @code{triangle} function discussed earlier. @xref{Decrementing
17416 Example, , Example with Decrementing Counter}, for a discussion.)
17417 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
17419 However, your function definition has a bug. You have mistyped
17420 @samp{1=} for @samp{1-}. Here is the broken definition:
17422 @findex triangle-bugged
17425 (defun triangle-bugged (number)
17426 "Return sum of numbers 1 through NUMBER inclusive."
17428 (while (> number 0)
17429 (setq total (+ total number))
17430 (setq number (1= number))) ; @r{Error here.}
17435 If you are reading this in Info, you can evaluate this definition in
17436 the normal fashion. You will see @code{triangle-bugged} appear in the
17440 Now evaluate the @code{triangle-bugged} function with an
17444 (triangle-bugged 4)
17448 In GNU Emacs version 21, you will create and enter a
17449 @file{*Backtrace*} buffer that says:
17454 ---------- Buffer: *Backtrace* ----------
17455 Debugger entered--Lisp error: (void-function 1=)
17457 (setq number (1= number))
17458 (while (> number 0) (setq total (+ total number))
17459 (setq number (1= number)))
17460 (let ((total 0)) (while (> number 0) (setq total ...)
17461 (setq number ...)) total)
17465 eval((triangle-bugged 4))
17466 eval-last-sexp-1(nil)
17467 eval-last-sexp(nil)
17468 call-interactively(eval-last-sexp)
17469 ---------- Buffer: *Backtrace* ----------
17474 (I have reformatted this example slightly; the debugger does not fold
17475 long lines. As usual, you can quit the debugger by typing @kbd{q} in
17476 the @file{*Backtrace*} buffer.)
17478 In practice, for a bug as simple as this, the `Lisp error' line will
17479 tell you what you need to know to correct the definition. The
17480 function @code{1=} is `void'.
17483 In GNU Emacs 20 and before, you will see:
17486 Symbol's function definition is void:@: 1=
17490 which has the same meaning as the @file{*Backtrace*} buffer line in
17493 However, suppose you are not quite certain what is going on?
17494 You can read the complete backtrace.
17496 In this case, you need to run GNU Emacs 21, which automatically starts
17497 the debugger that puts you in the @file{*Backtrace*} buffer; or else,
17498 you need to start the debugger manually as described below.
17500 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
17501 what Emacs did that led to the error. Emacs made an interactive call
17502 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
17503 of the @code{triangle-bugged} expression. Each line above tells you
17504 what the Lisp interpreter evaluated next.
17507 The third line from the top of the buffer is
17510 (setq number (1= number))
17514 Emacs tried to evaluate this expression; in order to do so, it tried
17515 to evaluate the inner expression shown on the second line from the
17524 This is where the error occurred; as the top line says:
17527 Debugger entered--Lisp error: (void-function 1=)
17531 You can correct the mistake, re-evaluate the function definition, and
17532 then run your test again.
17534 @node debug-on-entry, debug-on-quit, debug, Debugging
17535 @section @code{debug-on-entry}
17536 @findex debug-on-entry
17538 GNU Emacs 21 starts the debugger automatically when your function has
17539 an error. GNU Emacs version 20 and before did not; it simply
17540 presented you with an error message. You had to start the debugger
17543 You can start the debugger manually for all versions of Emacs; the
17544 advantage is that the debugger runs even if you do not have a bug in
17545 your code. Sometimes your code will be free of bugs!
17547 You can enter the debugger when you call the function by calling
17548 @code{debug-on-entry}.
17555 M-x debug-on-entry RET triangle-bugged RET
17560 Now, evaluate the following:
17563 (triangle-bugged 5)
17567 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
17568 you that it is beginning to evaluate the @code{triangle-bugged}
17573 ---------- Buffer: *Backtrace* ----------
17574 Debugger entered--entering a function:
17575 * triangle-bugged(5)
17576 eval((triangle-bugged 5))
17579 eval-last-sexp-1(nil)
17580 eval-last-sexp(nil)
17581 call-interactively(eval-last-sexp)
17582 ---------- Buffer: *Backtrace* ----------
17586 In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate
17587 the first expression in @code{triangle-bugged}; the buffer will look
17592 ---------- Buffer: *Backtrace* ----------
17593 Debugger entered--beginning evaluation of function call form:
17594 * (let ((total 0)) (while (> number 0) (setq total ...)
17595 (setq number ...)) total)
17596 * triangle-bugged(5)
17597 eval((triangle-bugged 5))
17600 eval-last-sexp-1(nil)
17601 eval-last-sexp(nil)
17602 call-interactively(eval-last-sexp)
17603 ---------- Buffer: *Backtrace* ----------
17608 Now, type @kbd{d} again, eight times, slowly. Each time you type
17609 @kbd{d}, Emacs will evaluate another expression in the function
17613 Eventually, the buffer will look like this:
17617 ---------- Buffer: *Backtrace* ----------
17618 Debugger entered--beginning evaluation of function call form:
17619 * (setq number (1= number))
17620 * (while (> number 0) (setq total (+ total number))
17621 (setq number (1= number)))
17624 * (let ((total 0)) (while (> number 0) (setq total ...)
17625 (setq number ...)) total)
17626 * triangle-bugged(5)
17627 eval((triangle-bugged 5))
17630 eval-last-sexp-1(nil)
17631 eval-last-sexp(nil)
17632 call-interactively(eval-last-sexp)
17633 ---------- Buffer: *Backtrace* ----------
17639 Finally, after you type @kbd{d} two more times, Emacs will reach the
17640 error, and the top two lines of the @file{*Backtrace*} buffer will look
17645 ---------- Buffer: *Backtrace* ----------
17646 Debugger entered--Lisp error: (void-function 1=)
17649 ---------- Buffer: *Backtrace* ----------
17653 By typing @kbd{d}, you were able to step through the function.
17655 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
17656 quits the trace, but does not cancel @code{debug-on-entry}.
17658 @findex cancel-debug-on-entry
17659 To cancel the effect of @code{debug-on-entry}, call
17660 @code{cancel-debug-on-entry} and the name of the function, like this:
17663 M-x cancel-debug-on-entry RET triangle-bugged RET
17667 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
17669 @node debug-on-quit, edebug, debug-on-entry, Debugging
17670 @section @code{debug-on-quit} and @code{(debug)}
17672 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
17673 there are two other ways to start @code{debug}.
17675 @findex debug-on-quit
17676 You can start @code{debug} whenever you type @kbd{C-g}
17677 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
17678 @code{t}. This is useful for debugging infinite loops.
17681 @cindex @code{(debug)} in code
17682 Or, you can insert a line that says @code{(debug)} into your code
17683 where you want the debugger to start, like this:
17687 (defun triangle-bugged (number)
17688 "Return sum of numbers 1 through NUMBER inclusive."
17690 (while (> number 0)
17691 (setq total (+ total number))
17692 (debug) ; @r{Start debugger.}
17693 (setq number (1= number))) ; @r{Error here.}
17698 The @code{debug} function is described in detail in @ref{Debugger, ,
17699 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
17701 @node edebug, Debugging Exercises, debug-on-quit, Debugging
17702 @section The @code{edebug} Source Level Debugger
17703 @cindex Source level debugger
17706 Edebug is a source level debugger. Edebug normally displays the
17707 source of the code you are debugging, with an arrow at the left that
17708 shows which line you are currently executing.
17710 You can walk through the execution of a function, line by line, or run
17711 quickly until reaching a @dfn{breakpoint} where execution stops.
17713 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
17714 Lisp Reference Manual}.
17717 Here is a bugged function definition for @code{triangle-recursively}.
17718 @xref{Recursive triangle function, , Recursion in place of a counter},
17719 for a review of it.
17723 (defun triangle-recursively-bugged (number)
17724 "Return sum of numbers 1 through NUMBER inclusive.
17729 (triangle-recursively-bugged
17730 (1= number))))) ; @r{Error here.}
17735 Normally, you would install this definition by positioning your cursor
17736 after the function's closing parenthesis and typing @kbd{C-x C-e}
17737 (@code{eval-last-sexp}) or else by positioning your cursor within the
17738 definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default,
17739 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
17743 However, to prepare this function definition for Edebug, you must
17744 first @dfn{instrument} the code using a different command. You can do
17745 this by positioning your cursor within the definition and typing
17748 M-x edebug-defun RET
17752 This will cause Emacs to load Edebug automatically if it is not
17753 already loaded, and properly instrument the function.
17755 After instrumenting the function, place your cursor after the
17756 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
17759 (triangle-recursively-bugged 3)
17763 You will be jumped back to the source for
17764 @code{triangle-recursively-bugged} and the cursor positioned at the
17765 beginning of the @code{if} line of the function. Also, you will see
17766 an arrowhead at the left hand side of that line. The arrowhead marks
17767 the line where the function is executing. (In the following examples,
17768 we show the arrowhead with @samp{=>}; in a windowing system, you may
17769 see the arrowhead as a solid triangle in the window `fringe'.)
17772 =>@point{}(if (= number 1)
17777 In the example, the location of point is displayed with a star,
17778 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
17781 In the example, the location of point is displayed as @samp{@point{}}
17782 (in a printed book, it is displayed with a five pointed star).
17785 If you now press @key{SPC}, point will move to the next expression to
17786 be executed; the line will look like this:
17789 =>(if @point{}(= number 1)
17793 As you continue to press @key{SPC}, point will move from expression to
17794 expression. At the same time, whenever an expression returns a value,
17795 that value will be displayed in the echo area. For example, after you
17796 move point past @code{number}, you will see the following:
17803 This means the value of @code{number} is 3, which is @sc{ascii}
17804 `control-c' (the third letter of the alphabet, in case you need to
17805 know this information).
17807 You can continue moving through the code until you reach the line with
17808 the error. Before evaluation, that line looks like this:
17811 => @point{}(1= number))))) ; @r{Error here.}
17816 When you press @key{SPC} once again, you will produce an error message
17820 Symbol's function definition is void:@: 1=
17826 Press @kbd{q} to quit Edebug.
17828 To remove instrumentation from a function definition, simply
17829 re-evaluate it with a command that does not instrument it.
17830 For example, you could place your cursor after the definition's
17831 closing parenthesis and type @kbd{C-x C-e}.
17833 Edebug does a great deal more than walk with you through a function.
17834 You can set it so it races through on its own, stopping only at an
17835 error or at specified stopping points; you can cause it to display the
17836 changing values of various expressions; you can find out how many
17837 times a function is called, and more.
17839 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
17840 Lisp Reference Manual}.
17843 @node Debugging Exercises, , edebug, Debugging
17844 @section Debugging Exercises
17848 Install the @code{count-words-region} function and then cause it to
17849 enter the built-in debugger when you call it. Run the command on a
17850 region containing two words. You will need to press @kbd{d} a
17851 remarkable number of times. On your system, is a `hook' called after
17852 the command finishes? (For information on hooks, see @ref{Command
17853 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
17857 Copy @code{count-words-region} into the @file{*scratch*} buffer,
17858 instrument the function for Edebug, and walk through its execution.
17859 The function does not need to have a bug, although you can introduce
17860 one if you wish. If the function lacks a bug, the walk-through
17861 completes without problems.
17864 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
17865 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
17866 @kbd{@key{CTL}-x} followed by an upper case @kbd{X}; use this prefix
17867 for commands made outside of the Edebug debugging buffer.)
17870 In the Edebug debugging buffer, use the @kbd{p}
17871 (@code{edebug-bounce-point}) command to see where in the region the
17872 @code{count-words-region} is working.
17875 Move point to some spot further down function and then type the
17876 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
17879 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
17880 walk through the function on its own; use an upper case @kbd{T} for
17881 @code{edebug-Trace-fast-mode}.
17884 Set a breakpoint, then run Edebug in Trace mode until it reaches the
17888 @node Conclusion, the-the, Debugging, Top
17889 @chapter Conclusion
17891 We have now reached the end of this Introduction. You have now
17892 learned enough about programming in Emacs Lisp to set values, to write
17893 simple @file{.emacs} files for yourself and your friends, and write
17894 simple customizations and extensions to Emacs.
17896 This is a place to stop. Or, if you wish, you can now go onward, and
17899 You have learned some of the basic nuts and bolts of programming. But
17900 only some. There are a great many more brackets and hinges that are
17901 easy to use that we have not touched.
17903 A path you can follow right now lies among the sources to GNU Emacs
17906 @cite{The GNU Emacs Lisp Reference Manual}.
17909 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
17910 Emacs Lisp Reference Manual}.
17913 The Emacs Lisp sources are an adventure. When you read the sources and
17914 come across a function or expression that is unfamiliar, you need to
17915 figure out or find out what it does.
17917 Go to the Reference Manual. It is a thorough, complete, and fairly
17918 easy-to-read description of Emacs Lisp. It is written not only for
17919 experts, but for people who know what you know. (The @cite{Reference
17920 Manual} comes with the standard GNU Emacs distribution. Like this
17921 introduction, it comes as a Texinfo source file, so you can read it
17922 on-line and as a typeset, printed book.)
17924 Go to the other on-line help that is part of GNU Emacs: the on-line
17925 documentation for all functions, and @code{find-tags}, the program
17926 that takes you to sources.
17928 Here is an example of how I explore the sources. Because of its name,
17929 @file{simple.el} is the file I looked at first, a long time ago. As
17930 it happens some of the functions in @file{simple.el} are complicated,
17931 or at least look complicated at first sight. The @code{open-line}
17932 function, for example, looks complicated.
17934 You may want to walk through this function slowly, as we did with the
17935 @code{forward-sentence} function.
17937 (@xref{forward-sentence}.)
17940 (@xref{forward-sentence, , @code{forward-sentence}}.)
17942 Or you may want to skip that function and look at another, such as
17943 @code{split-line}. You don't need to read all the functions.
17944 According to @code{count-words-in-defun}, the @code{split-line}
17945 function contains 27 words and symbols.
17947 Even though it is short, @code{split-line} contains four expressions
17948 we have not studied: @code{skip-chars-forward}, @code{indent-to},
17949 @code{current-column} and @samp{?\n}.
17951 Consider the @code{skip-chars-forward} function. (It is part of the
17952 function definition for @code{back-to-indentation}, which is shown in
17953 @ref{Review, , Review}.)
17955 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
17956 typing @kbd{C-h f} (@code{describe-function}) and the name of the
17957 function. This gives you the function documentation.
17959 You may be able to guess what is done by a well named function such as
17960 @code{indent-to}; or you can look it up, too. Incidentally, the
17961 @code{describe-function} function itself is in @file{help.el}; it is
17962 one of those long, but decipherable functions. You can look up
17963 @code{describe-function} using the @kbd{C-h f} command!
17965 In this instance, since the code is Lisp, the @file{*Help*} buffer
17966 contains the name of the library containing the function's source.
17967 You can put point over the name of the library and press the RET key,
17968 which in this situation is bound to @code{help-follow}, and be taken
17969 directly to the source, in the same way as @kbd{M-.}
17972 The definition for @code{describe-function} illustrates how to
17973 customize the @code{interactive} expression without using the standard
17974 character codes; and it shows how to create a temporary buffer.
17976 (The @code{indent-to} function is written in C rather than Emacs Lisp;
17977 it is a `built-in' function. @code{help-follow} only provides you
17978 with the documentation of a built-in function; it does not take you to
17979 the source. But @code{find-tag} will take you to the source, if
17982 You can look at a function's source using @code{find-tag}, which is
17983 bound to @kbd{M-.} Finally, you can find out what the Reference
17984 Manual has to say by visiting the manual in Info, and typing @kbd{i}
17985 (@code{Info-index}) and the name of the function, or by looking up
17986 @code{skip-chars-forward} in the index to a printed copy of the
17989 Similarly, you can find out what is meant by @samp{?\n}. You can try
17990 using @code{Info-index} with @samp{?\n}. It turns out that this
17991 action won't help; but don't give up. If you search the index for
17992 @samp{\n} without the @samp{?}, you will be taken directly to the
17993 relevant section of the manual. (@xref{Character Type, , Character
17994 Type, elisp, The GNU Emacs Lisp Reference Manual}. @samp{?\n} stands
17995 for the newline character.)
17997 Other interesting source files include @file{paragraphs.el},
17998 @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
17999 file includes short, easily understood functions as well as longer
18000 ones. The @file{loaddefs.el} file contains the many standard
18001 autoloads and many keymaps. I have never looked at it all; only at
18002 parts. @file{loadup.el} is the file that loads the standard parts of
18003 Emacs; it tells you a great deal about how Emacs is built.
18004 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
18005 Reference Manual}, for more about building.)
18007 As I said, you have learned some nuts and bolts; however, and very
18008 importantly, we have hardly touched major aspects of programming; I
18009 have said nothing about how to sort information, except to use the
18010 predefined @code{sort} function; I have said nothing about how to store
18011 information, except to use variables and lists; I have said nothing
18012 about how to write programs that write programs. These are topics for
18013 another, and different kind of book, a different kind of learning.
18015 What you have done is learn enough for much practical work with GNU
18016 Emacs. What you have done is get started. This is the end of a
18019 @c ================ Appendix ================
18021 @node the-the, Kill Ring, Conclusion, Top
18022 @appendix The @code{the-the} Function
18024 @cindex Duplicated words function
18025 @cindex Words, duplicated
18027 Sometimes when you you write text, you duplicate words---as with ``you
18028 you'' near the beginning of this sentence. I find that most
18029 frequently, I duplicate ``the''; hence, I call the function for
18030 detecting duplicated words, @code{the-the}.
18033 As a first step, you could use the following regular expression to
18034 search for duplicates:
18037 \\(\\w+[ \t\n]+\\)\\1
18041 This regexp matches one or more word-constituent characters followed
18042 by one or more spaces, tabs, or newlines. However, it does not detect
18043 duplicated words on different lines, since the ending of the first
18044 word, the end of the line, is different from the ending of the second
18045 word, a space. (For more information about regular expressions, see
18046 @ref{Regexp Search, , Regular Expression Searches}, as well as
18047 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
18048 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
18049 The GNU Emacs Lisp Reference Manual}.)
18051 You might try searching just for duplicated word-constituent
18052 characters but that does not work since the pattern detects doubles
18053 such as the two occurrences of `th' in `with the'.
18055 Another possible regexp searches for word-constituent characters
18056 followed by non-word-constituent characters, reduplicated. Here,
18057 @w{@samp{\\w+}} matches one or more word-constituent characters and
18058 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
18061 \\(\\(\\w+\\)\\W*\\)\\1
18067 Here is the pattern that I use. It is not perfect, but good enough.
18068 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
18069 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
18070 any characters that are @emph{not} an @@-sign, space, newline, or tab.
18073 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
18076 One can write more complicated expressions, but I found that this
18077 expression is good enough, so I use it.
18079 Here is the @code{the-the} function, as I include it in my
18080 @file{.emacs} file, along with a handy global key binding:
18085 "Search forward for for a duplicated word."
18087 (message "Searching for for duplicated words ...")
18091 ;; This regexp is not perfect
18092 ;; but is fairly good over all:
18093 (if (re-search-forward
18094 "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
18095 (message "Found duplicated word.")
18096 (message "End of buffer")))
18100 ;; Bind `the-the' to C-c \
18101 (global-set-key "\C-c\\" 'the-the)
18110 one two two three four five
18115 You can substitute the other regular expressions shown above in the
18116 function definition and try each of them on this list.
18118 @node Kill Ring, Full Graph, the-the, Top
18119 @appendix Handling the Kill Ring
18120 @cindex Kill ring handling
18121 @cindex Handling the kill ring
18122 @cindex Ring, making a list like a
18124 The kill ring is a list that is transformed into a ring by the
18125 workings of the @code{rotate-yank-pointer} function. The @code{yank}
18126 and @code{yank-pop} commands use the @code{rotate-yank-pointer}
18127 function. This appendix describes the @code{rotate-yank-pointer}
18128 function as well as both the @code{yank} and the @code{yank-pop}
18132 * rotate-yank-pointer:: Move a pointer along a list and around.
18133 * yank:: Paste a copy of a clipped element.
18134 * yank-pop:: Insert first element pointed to.
18138 @node rotate-yank-pointer, yank, Kill Ring, Kill Ring
18139 @comment node-name, next, previous, up
18140 @appendixsec The @code{rotate-yank-pointer} Function
18141 @findex rotate-yank-pointer
18143 The @code{rotate-yank-pointer} function changes the element in the kill
18144 ring to which @code{kill-ring-yank-pointer} points. For example, it can
18145 change @code{kill-ring-yank-pointer} from pointing to the second
18146 element to point to the third element.
18149 Here is the code for @code{rotate-yank-pointer}:
18153 (defun rotate-yank-pointer (arg)
18154 "Rotate the yanking point in the kill ring."
18156 (let ((length (length kill-ring)))
18161 (error "Kill ring is empty")
18165 (setq kill-ring-yank-pointer
18169 kill-ring-yank-pointer)))
18176 * Understanding rotate-yk-ptr::
18177 * rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
18180 @node Understanding rotate-yk-ptr, rotate-yk-ptr body, rotate-yank-pointer, rotate-yank-pointer
18182 @unnumberedsubsec @code{rotate-yank-pointer} in Outline
18185 The @code{rotate-yank-pointer} function looks complex, but as usual,
18186 it can be understood by taking it apart piece by piece. First look at
18187 it in skeletal form:
18191 (defun rotate-yank-pointer (arg)
18192 "Rotate the yanking point in the kill ring."
18199 This function takes one argument, called @code{arg}. It has a brief
18200 documentation string; and it is interactive with a small @samp{p}, which
18201 means that the argument must be a processed prefix passed to the
18202 function as a number.
18204 The body of the function definition is a @code{let} expression, which
18205 itself has a body as well as a @var{varlist}.
18207 The @code{let} expression declares a variable that will be only usable
18208 within the bounds of this function. This variable is called
18209 @code{length} and is bound to a value that is equal to the number of
18210 items in the kill ring. This is done by using the function called
18211 @code{length}. (Note that this function has the same name as the
18212 variable called @code{length}; but one use of the word is to name the
18213 function and the other is to name the variable. The two are quite
18214 distinct. Similarly, an English speaker will distinguish between the
18215 meanings of the word @samp{ship} when he says: "I must ship this package
18216 immediately." and "I must get aboard the ship immediately.")
18218 The function @code{length} tells the number of items there are in a list,
18219 so @code{(length kill-ring)} returns the number of items there are in the
18222 @node rotate-yk-ptr body, , Understanding rotate-yk-ptr, rotate-yank-pointer
18223 @comment node-name, next, previous, up
18224 @appendixsubsec The Body of @code{rotate-yank-pointer}
18226 The body of @code{rotate-yank-pointer} is a @code{let} expression and
18227 the body of the @code{let} expression is an @code{if} expression.
18229 The purpose of the @code{if} expression is to find out whether there is
18230 anything in the kill ring. If the kill ring is empty, the @code{error}
18231 function stops evaluation of the function and prints a message in the
18232 echo area. On the other hand, if the kill ring has something in it, the
18233 work of the function is done.
18235 Here is the if-part and then-part of the @code{if} expression:
18241 (if (zerop length) ; @r{if-part}
18242 (error "Kill ring is empty") ; @r{then-part}
18248 If there is not anything in the kill ring, its length must be zero and
18249 an error message sent to the user: @samp{Kill ring is empty}. The
18250 @code{if} expression uses the function @code{zerop} which returns true
18251 if the value it is testing is zero. When @code{zerop} tests true, the
18252 then-part of the @code{if} is evaluated. The then-part is a list
18253 starting with the function @code{error}, which is a function that is
18254 similar to the @code{message} function (@pxref{message}), in that it
18255 prints a one-line message in the echo area. However, in addition to
18256 printing a message, @code{error} also stops evaluation of the function
18257 within which it is embedded. This means that the rest of the function
18258 will not be evaluated if the length of the kill ring is zero.
18261 * Digression concerning error:: How to mislead humans, but not computers.
18262 * rotate-yk-ptr else-part:: The else-part of the @code{if} expression.
18263 * Remainder Function:: The remainder, @code{%}, function.
18264 * rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}.
18265 * kill-rng-yk-ptr last elt:: Pointing to the last element.
18268 @node Digression concerning error, rotate-yk-ptr else-part, rotate-yk-ptr body, rotate-yk-ptr body
18270 @unnumberedsubsubsec Digression about the word `error'
18273 (In my opinion, it is slightly misleading, at least to humans, to use
18274 the term `error' as the name of the @code{error} function. A better
18275 term would be `cancel'. Strictly speaking, of course, you cannot
18276 point to, much less rotate a pointer to a list that has no length, so
18277 from the point of view of the computer, the word `error' is correct.
18278 But a human expects to attempt this sort of thing, if only to find out
18279 whether the kill ring is full or empty. This is an act of
18282 From the human point of view, the act of exploration and discovery is
18283 not necessarily an error, and therefore should not be labelled as one,
18284 even in the bowels of a computer. As it is, the code in Emacs implies
18285 that a human who is acting virtuously, by exploring his or her
18286 environment, is making an error. This is bad. Even though the computer
18287 takes the same steps as it does when there is an `error', a term such as
18288 `cancel' would have a clearer connotation.)
18290 @node rotate-yk-ptr else-part, Remainder Function, Digression concerning error, rotate-yk-ptr body
18291 @unnumberedsubsubsec The else-part of the @code{if} expression
18293 The else-part of the @code{if} expression is dedicated to setting the
18294 value of @code{kill-ring-yank-pointer} when the kill ring has something
18295 in it. The code looks like this:
18299 (setq kill-ring-yank-pointer
18302 (length kill-ring-yank-pointer)))
18308 This needs some examination. Clearly, @code{kill-ring-yank-pointer}
18309 is being set to be equal to some @sc{cdr} of the kill ring, using the
18310 @code{nthcdr} function that is described in an earlier section.
18311 (@xref{copy-region-as-kill}.) But exactly how does it do this?
18313 Before looking at the details of the code let's first consider the
18314 purpose of the @code{rotate-yank-pointer} function.
18316 The @code{rotate-yank-pointer} function changes what
18317 @code{kill-ring-yank-pointer} points to. If
18318 @code{kill-ring-yank-pointer} starts by pointing to the first element
18319 of a list, a call to @code{rotate-yank-pointer} causes it to point to
18320 the second element; and if @code{kill-ring-yank-pointer} points to the
18321 second element, a call to @code{rotate-yank-pointer} causes it to
18322 point to the third element. (And if @code{rotate-yank-pointer} is
18323 given an argument greater than 1, it jumps the pointer that many
18326 The @code{rotate-yank-pointer} function uses @code{setq} to reset what
18327 the @code{kill-ring-yank-pointer} points to. If
18328 @code{kill-ring-yank-pointer} points to the first element of the kill
18329 ring, then, in the simplest case, the @code{rotate-yank-pointer}
18330 function must cause it to point to the second element. Put another
18331 way, @code{kill-ring-yank-pointer} must be reset to have a value equal
18332 to the @sc{cdr} of the kill ring.
18335 That is, under these circumstances,
18339 (setq kill-ring-yank-pointer
18340 ("some text" "a different piece of text" "yet more text"))
18343 ("some text" "a different piece of text" "yet more text"))
18349 the code should do this:
18352 (setq kill-ring-yank-pointer (cdr kill-ring))
18357 As a result, the @code{kill-ring-yank-pointer} will look like this:
18361 kill-ring-yank-pointer
18362 @result{} ("a different piece of text" "yet more text"))
18366 The actual @code{setq} expression uses the @code{nthcdr} function to do
18369 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
18370 works by repeatedly taking the @sc{cdr} of a list---it takes the
18371 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
18374 The two following expressions produce the same result:
18378 (setq kill-ring-yank-pointer (cdr kill-ring))
18380 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
18384 In the @code{rotate-yank-pointer} function, however, the first
18385 argument to @code{nthcdr} is a rather complex looking expression with
18386 lots of arithmetic inside of it:
18392 (length kill-ring-yank-pointer)))
18397 As usual, we need to look at the most deeply embedded expression first
18398 and then work our way towards the light.
18400 The most deeply embedded expression is @code{(length
18401 kill-ring-yank-pointer)}. This finds the length of the current value of
18402 the @code{kill-ring-yank-pointer}. (Remember that the
18403 @code{kill-ring-yank-pointer} is the name of a variable whose value is a
18407 The measurement of the length is inside the expression:
18410 (- length (length kill-ring-yank-pointer))
18414 In this expression, the first @code{length} is the variable that was
18415 assigned the length of the kill ring in the @code{let} statement at the
18416 beginning of the function. (One might think this function would be
18417 clearer if the variable @code{length} were named
18418 @code{length-of-kill-ring} instead; but if you look at the text of the
18419 whole function, you will see that it is so short that naming this
18420 variable @code{length} is not a bother, unless you are pulling the
18421 function apart into very tiny pieces as we are doing here.)
18423 So the line @code{(- length (length kill-ring-yank-pointer))} tells the
18424 difference between the length of the kill ring and the length of the list
18425 whose name is @code{kill-ring-yank-pointer}.
18427 To see how all this fits into the @code{rotate-yank-pointer}
18428 function, let's begin by analyzing the case where
18429 @code{kill-ring-yank-pointer} points to the first element of the kill
18430 ring, just as @code{kill-ring} does, and see what happens when
18431 @code{rotate-yank-pointer} is called with an argument of 1.
18433 The variable @code{length} and the value of the expression
18434 @code{(length kill-ring-yank-pointer)} will be the same since the
18435 variable @code{length} is the length of the kill ring and the
18436 @code{kill-ring-yank-pointer} is pointing to the whole kill ring.
18437 Consequently, the value of
18440 (- length (length kill-ring-yank-pointer))
18444 will be zero. Since the value of @code{arg} will be 1, this will mean
18445 that the value of the whole expression
18448 (+ arg (- length (length kill-ring-yank-pointer)))
18455 Consequently, the argument to @code{nthcdr} will be found as the result of
18462 @node Remainder Function, rotate-yk-ptr remainder, rotate-yk-ptr else-part, rotate-yk-ptr body
18463 @unnumberedsubsubsec The @code{%} remainder function
18465 To understand @code{(% 1 length)}, we need to understand @code{%}.
18466 According to its documentation (which I just found by typing @kbd{C-h
18467 f @kbd{%} @key{RET}}), the @code{%} function returns the remainder of
18468 its first argument divided by its second argument. For example, the
18469 remainder of 5 divided by 2 is 1. (2 goes into 5 twice with a
18472 What surprises people who don't often do arithmetic is that a smaller
18473 number can be divided by a larger number and have a remainder. In the
18474 example we just used, 5 was divided by 2. We can reverse that and ask,
18475 what is the result of dividing 2 by 5? If you can use fractions, the
18476 answer is obviously 2/5 or .4; but if, as here, you can only use whole
18477 numbers, the result has to be something different. Clearly, 5 can go into
18478 2 zero times, but what of the remainder? To see what the answer is,
18479 consider a case that has to be familiar from childhood:
18483 5 divided by 5 is 1 with a remainder of 0;
18486 6 divided by 5 is 1 with a remainder of 1;
18489 7 divided by 5 is 1 with a remainder of 2.
18492 Similarly, 10 divided by 5 is 2 with a remainder of 0;
18495 11 divided by 5 is 2 with a remainder of 1;
18498 12 divided by 5 is 1 with a remainder of 2.
18503 By considering the cases as parallel, we can see that
18507 zero divided by 5 must be zero with a remainder of zero;
18510 1 divided by 5 must be zero with a remainder of 1;
18513 2 divided by 5 must be zero with a remainder of 2;
18520 So, in this code, if the value of @code{length} is 5, then the result of
18528 is 1. (I just checked this by placing the cursor after the expression
18529 and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.)
18532 @node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body
18533 @unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer}
18535 When the @code{kill-ring-yank-pointer} points to the
18536 beginning of the kill ring, and the argument passed to
18537 @code{rotate-yank-pointer} is 1, the @code{%} expression returns 1:
18541 (- length (length kill-ring-yank-pointer))
18552 (+ arg (- length (length kill-ring-yank-pointer)))
18563 (% (+ arg (- length (length kill-ring-yank-pointer)))
18570 regardless of the value of @code{length}.
18574 As a result of this, the @code{setq kill-ring-yank-pointer} expression
18578 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
18582 What it does is now easy to understand. Instead of pointing as it did
18583 to the first element of the kill ring, the
18584 @code{kill-ring-yank-pointer} is set to point to the second element.
18586 Clearly, if the argument passed to @code{rotate-yank-pointer} is two, then
18587 the @code{kill-ring-yank-pointer} is set to @code{(nthcdr 2 kill-ring)};
18588 and so on for different values of the argument.
18590 Similarly, if the @code{kill-ring-yank-pointer} starts out pointing to
18591 the second element of the kill ring, its length is shorter than the
18592 length of the kill ring by 1, so the computation of the remainder is
18593 based on the expression @code{(% (+ arg 1) length)}. This means that
18594 the @code{kill-ring-yank-pointer} is moved from the second element of
18595 the kill ring to the third element if the argument passed to
18596 @code{rotate-yank-pointer} is 1.
18598 @node kill-rng-yk-ptr last elt, , rotate-yk-ptr remainder, rotate-yk-ptr body
18599 @unnumberedsubsubsec Pointing to the last element
18601 The final question is, what happens if the @code{kill-ring-yank-pointer}
18602 is set to the @emph{last} element of the kill ring? Will a call to
18603 @code{rotate-yank-pointer} mean that nothing more can be taken from the
18604 kill ring? The answer is no. What happens is different and useful.
18605 The @code{kill-ring-yank-pointer} is set to point to the beginning of
18606 the kill ring instead.
18608 Let's see how this works by looking at the code, assuming the length of the
18609 kill ring is 5 and the argument passed to @code{rotate-yank-pointer} is 1.
18610 When the @code{kill-ring-yank-pointer} points to the last element of
18611 the kill ring, its length is 1. The code looks like this:
18614 (% (+ arg (- length (length kill-ring-yank-pointer))) length)
18618 When the variables are replaced by their numeric values, the expression
18622 (% (+ 1 (- 5 1)) 5)
18626 This expression can be evaluated by looking at the most embedded inner
18627 expression first and working outwards: The value of @code{(- 5 1)} is 4;
18628 the sum of @code{(+ 1 4)} is 5; and the remainder of dividing 5 by 5 is
18629 zero. So what @code{rotate-yank-pointer} will do is
18632 (setq kill-ring-yank-pointer (nthcdr 0 kill-ring))
18636 which will set the @code{kill-ring-yank-pointer} to point to the beginning
18639 So what happens with successive calls to @code{rotate-yank-pointer} is that
18640 it moves the @code{kill-ring-yank-pointer} from element to element in the
18641 kill ring until it reaches the end; then it jumps back to the beginning.
18642 And this is why the kill ring is called a ring, since by jumping back to
18643 the beginning, it is as if the list has no end! (And what is a ring, but
18644 an entity with no end?)
18646 @node yank, yank-pop, rotate-yank-pointer, Kill Ring
18647 @comment node-name, next, previous, up
18648 @appendixsec @code{yank}
18651 After learning about @code{rotate-yank-pointer}, the code for the
18652 @code{yank} function is almost easy. It has only one tricky part, which is
18653 the computation of the argument to be passed to @code{rotate-yank-pointer}.
18656 The code looks like this:
18660 (defun yank (&optional arg)
18661 "Reinsert the last stretch of killed text.
18662 More precisely, reinsert the stretch of killed text most
18663 recently killed OR yanked.
18664 With just C-U as argument, same but put point in front
18665 (and mark at end). With argument n, reinsert the nth
18666 most recently killed stretch of killed text.
18667 See also the command \\[yank-pop]."
18672 (rotate-yank-pointer (if (listp arg) 0
18675 (push-mark (point))
18676 (insert (car kill-ring-yank-pointer))
18678 (exchange-point-and-mark)))
18682 Glancing over this code, we can understand the last few lines readily
18683 enough. The mark is pushed, that is, remembered; then the first element
18684 (the @sc{car}) of what the @code{kill-ring-yank-pointer} points to is
18685 inserted; and then, if the argument passed the function is a
18686 @code{cons}, point and mark are exchanged so the point is put in the
18687 front of the inserted text rather than at the end. This option is
18688 explained in the documentation. The function itself is interactive with
18689 @code{"*P"}. This means it will not work on a read-only buffer, and that
18690 the unprocessed prefix argument is passed to the function.
18693 * rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}.
18694 * rotate-yk-ptr negative arg:: Pass a negative argument.
18697 @node rotate-yk-ptr arg, rotate-yk-ptr negative arg, yank, yank
18698 @unnumberedsubsubsec Passing the argument
18700 The hard part of @code{yank} is understanding the computation that
18701 determines the value of the argument passed to
18702 @code{rotate-yank-pointer}. Fortunately, it is not so difficult as it
18703 looks at first sight.
18705 What happens is that the result of evaluating one or both of the
18706 @code{if} expressions will be a number and that number will be the
18707 argument passed to @code{rotate-yank-pointer}.
18710 Laid out with comments, the code looks like this:
18714 (if (listp arg) ; @r{if-part}
18716 (if (eq arg '-) ; @r{else-part, inner if}
18717 -1 ; @r{inner if's then-part}
18718 (1- arg)))) ; @r{inner if's else-part}
18723 This code consists of two @code{if} expression, one the else-part of
18726 The first or outer @code{if} expression tests whether the argument
18727 passed to @code{yank} is a list. Oddly enough, this will be true if
18728 @code{yank} is called without an argument---because then it will be
18729 passed the value of @code{nil} for the optional argument and an
18730 evaluation of @code{(listp nil)} returns true! So, if no argument is
18731 passed to @code{yank}, the argument passed to
18732 @code{rotate-yank-pointer} inside of @code{yank} is zero. This means
18733 the pointer is not moved and the first element to which
18734 @code{kill-ring-yank-pointer} points is inserted, as we expect.
18735 Similarly, if the argument for @code{yank} is @kbd{C-u}, this will be
18736 read as a list, so again, a zero will be passed to
18737 @code{rotate-yank-pointer}. (@kbd{C-u} produces an unprocessed prefix
18738 argument of @code{(4)}, which is a list of one element.) At the same
18739 time, later in the function, this argument will be read as a
18740 @code{cons} so point will be put in the front and mark at the end of
18741 the insertion. (The @code{P} argument to @code{interactive} is
18742 designed to provide these values for the case when an optional
18743 argument is not provided or when it is @kbd{C-u}.)
18745 The then-part of the outer @code{if} expression handles the case when
18746 there is no argument or when it is @kbd{C-u}. The else-part handles the
18747 other situations. The else-part is itself another @code{if} expression.
18749 The inner @code{if} expression tests whether the argument is a minus
18750 sign. (This is done by pressing the @key{META} and @kbd{-} keys at the
18751 same time, or the @key{ESC} key and then the @kbd{-} key). In this
18752 case, the @code{rotate-yank-pointer} function is passed @kbd{-1} as an
18753 argument. This moves the @code{kill-ring-yank-pointer} backwards, which
18754 is what is desired.
18756 If the true-or-false-test of the inner @code{if} expression is false
18757 (that is, if the argument is not a minus sign), the else-part of the
18758 expression is evaluated. This is the expression @code{(1- arg)}.
18759 Because of the two @code{if} expressions, it will only occur when the
18760 argument is a positive number or when it is a negative number (not
18761 just a minus sign on its own). What @code{(1- arg)} does is decrement
18762 the number and return it. (The @code{1-} function subtracts one from
18763 its argument.) This means that if the argument to
18764 @code{rotate-yank-pointer} is 1, it is reduced to zero, which means
18765 the first element to which @code{kill-ring-yank-pointer} points is
18766 yanked back, as you would expect.
18768 @node rotate-yk-ptr negative arg, , rotate-yk-ptr arg, yank
18769 @unnumberedsubsubsec Passing a negative argument
18771 Finally, the question arises, what happens if either the remainder
18772 function, @code{%}, or the @code{nthcdr} function is passed a negative
18773 argument, as they quite well may?
18775 The answers can be found by a quick test. When @code{(% -1 5)} is
18776 evaluated, a negative number is returned; and if @code{nthcdr} is
18777 called with a negative number, it returns the same value as if it were
18778 called with a first argument of zero. This can be seen by evaluating
18779 the following code.
18781 Here the @samp{@result{}} points to the result of evaluating the code
18782 preceding it. This was done by positioning the cursor after the code
18783 and typing @kbd{C-x C-e} (@code{eval-last-sexp}) in the usual fashion.
18784 You can do this if you are reading this in Info inside of GNU Emacs.
18793 (setq animals '(cats dogs elephants))
18794 @result{} (cats dogs elephants)
18799 @result{} (dogs elephants)
18804 @result{} (cats dogs elephants)
18808 (nthcdr -1 animals)
18809 @result{} (cats dogs elephants)
18813 So, if a minus sign or a negative number is passed to @code{yank}, the
18814 @code{kill-ring-yank-point} is rotated backwards until it reaches the
18815 beginning of the list. Then it stays there. Unlike the other case,
18816 when it jumps from the end of the list to the beginning of the list,
18817 making a ring, it stops. This makes sense. You often want to get back
18818 to the most recently clipped out piece of text, but you don't usually
18819 want to insert text from as many as thirty kill commands ago. So you
18820 need to work through the ring to get to the end, but won't cycle around
18821 it inadvertently if you are trying to come back to the beginning.
18823 Incidentally, any number passed to @code{yank} with a minus sign
18824 preceding it will be treated as @minus{}1. This is evidently a
18825 simplification for writing the program. You don't need to jump back
18826 towards the beginning of the kill ring more than one place at a time
18827 and doing this is easier than writing a function to determine the
18828 magnitude of the number that follows the minus sign.
18830 @node yank-pop, ring file, yank, Kill Ring
18831 @comment node-name, next, previous, up
18832 @appendixsec @code{yank-pop}
18835 After understanding @code{yank}, the @code{yank-pop} function is easy.
18836 Leaving out the documentation to save space, it looks like this:
18840 (defun yank-pop (arg)
18842 (if (not (eq last-command 'yank))
18843 (error "Previous command was not a yank"))
18846 (setq this-command 'yank)
18847 (let ((before (< (point) (mark))))
18848 (delete-region (point) (mark))
18849 (rotate-yank-pointer arg)
18853 (insert (car kill-ring-yank-pointer))
18854 (if before (exchange-point-and-mark))))
18858 The function is interactive with a small @samp{p} so the prefix
18859 argument is processed and passed to the function. The command can
18860 only be used after a previous yank; otherwise an error message is
18861 sent. This check uses the variable @code{last-command} which is
18862 discussed elsewhere. (@xref{copy-region-as-kill}.)
18864 The @code{let} clause sets the variable @code{before} to true or false
18865 depending whether point is before or after mark and then the region
18866 between point and mark is deleted. This is the region that was just
18867 inserted by the previous yank and it is this text that will be
18868 replaced. Next the @code{kill-ring-yank-pointer} is rotated so that
18869 the previously inserted text is not reinserted yet again. Mark is set
18870 at the beginning of the place the new text will be inserted and then
18871 the first element to which @code{kill-ring-yank-pointer} points is
18872 inserted. This leaves point after the new text. If in the previous
18873 yank, point was left before the inserted text, point and mark are now
18874 exchanged so point is again left in front of the newly inserted text.
18875 That is all there is to it!
18877 @node ring file, , yank-pop, Kill Ring
18878 @comment node-name, next, previous, up
18879 @appendixsec The @file{ring.el} File
18880 @cindex @file{ring.el} file
18882 Interestingly, GNU Emacs posses a file called @file{ring.el} that
18883 provides many of the features we just discussed. But functions such
18884 as @code{kill-ring-yank-pointer} do not use this library, possibly
18885 because they were written earlier.
18887 @node Full Graph, Free Software and Free Manuals, Kill Ring, Top
18888 @appendix A Graph with Labelled Axes
18890 Printed axes help you understand a graph. They convey scale. In an
18891 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we
18892 wrote the code to print the body of a graph. Here we write the code
18893 for printing and labelling vertical and horizontal axes, along with the
18897 * Labelled Example::
18898 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
18899 * print-Y-axis:: Print a label for the vertical axis.
18900 * print-X-axis:: Print a horizontal label.
18901 * Print Whole Graph:: The function to print a complete graph.
18904 @node Labelled Example, print-graph Varlist, Full Graph, Full Graph
18906 @unnumberedsec Labelled Example Graph
18909 Since insertions fill a buffer to the right and below point, the new
18910 graph printing function should first print the Y or vertical axis,
18911 then the body of the graph, and finally the X or horizontal axis.
18912 This sequence lays out for us the contents of the function:
18922 Print body of graph.
18929 Here is an example of how a finished graph should look:
18942 1 - ****************
18949 In this graph, both the vertical and the horizontal axes are labelled
18950 with numbers. However, in some graphs, the horizontal axis is time
18951 and would be better labelled with months, like this:
18965 Indeed, with a little thought, we can easily come up with a variety of
18966 vertical and horizontal labelling schemes. Our task could become
18967 complicated. But complications breed confusion. Rather than permit
18968 this, it is better choose a simple labelling scheme for our first
18969 effort, and to modify or replace it later.
18972 These considerations suggest the following outline for the
18973 @code{print-graph} function:
18977 (defun print-graph (numbers-list)
18978 "@var{documentation}@dots{}"
18979 (let ((height @dots{}
18983 (print-Y-axis height @dots{} )
18984 (graph-body-print numbers-list)
18985 (print-X-axis @dots{} )))
18989 We can work on each part of the @code{print-graph} function definition
18992 @node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph
18993 @comment node-name, next, previous, up
18994 @appendixsec The @code{print-graph} Varlist
18995 @cindex @code{print-graph} varlist
18997 In writing the @code{print-graph} function, the first task is to write
18998 the varlist in the @code{let} expression. (We will leave aside for the
18999 moment any thoughts about making the function interactive or about the
19000 contents of its documentation string.)
19002 The varlist should set several values. Clearly, the top of the label
19003 for the vertical axis must be at least the height of the graph, which
19004 means that we must obtain this information here. Note that the
19005 @code{print-graph-body} function also requires this information. There
19006 is no reason to calculate the height of the graph in two different
19007 places, so we should change @code{print-graph-body} from the way we
19008 defined it earlier to take advantage of the calculation.
19010 Similarly, both the function for printing the X axis labels and the
19011 @code{print-graph-body} function need to learn the value of the width of
19012 each symbol. We can perform the calculation here and change the
19013 definition for @code{print-graph-body} from the way we defined it in the
19016 The length of the label for the horizontal axis must be at least as long
19017 as the graph. However, this information is used only in the function
19018 that prints the horizontal axis, so it does not need to be calculated here.
19020 These thoughts lead us directly to the following form for the varlist
19021 in the @code{let} for @code{print-graph}:
19025 (let ((height (apply 'max numbers-list)) ; @r{First version.}
19026 (symbol-width (length graph-blank)))
19031 As we shall see, this expression is not quite right.
19034 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph
19035 @comment node-name, next, previous, up
19036 @appendixsec The @code{print-Y-axis} Function
19037 @cindex Axis, print vertical
19038 @cindex Y axis printing
19039 @cindex Vertical axis printing
19040 @cindex Print vertical axis
19042 The job of the @code{print-Y-axis} function is to print a label for
19043 the vertical axis that looks like this:
19061 The function should be passed the height of the graph, and then should
19062 construct and insert the appropriate numbers and marks.
19064 It is easy enough to see in the figure what the Y axis label should
19065 look like; but to say in words, and then to write a function
19066 definition to do the job is another matter. It is not quite true to
19067 say that we want a number and a tic every five lines: there are only
19068 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
19069 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
19070 and 9). It is better to say that we want a number and a tic mark on
19071 the base line (number 1) and then that we want a number and a tic on
19072 the fifth line from the bottom and on every line that is a multiple of
19076 * Height of label:: What height for the Y axis?
19077 * Compute a Remainder:: How to compute the remainder of a division.
19078 * Y Axis Element:: Construct a line for the Y axis.
19079 * Y-axis-column:: Generate a list of Y axis labels.
19080 * print-Y-axis Penultimate:: A not quite final version.
19083 @node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis
19085 @unnumberedsubsec What height should the label be?
19088 The next issue is what height the label should be? Suppose the maximum
19089 height of tallest column of the graph is seven. Should the highest
19090 label on the Y axis be @samp{5 -}, and should the graph stick up above
19091 the label? Or should the highest label be @samp{7 -}, and mark the peak
19092 of the graph? Or should the highest label be @code{10 -}, which is a
19093 multiple of five, and be higher than the topmost value of the graph?
19095 The latter form is preferred. Most graphs are drawn within rectangles
19096 whose sides are an integral number of steps long---5, 10, 15, and so
19097 on for a step distance of five. But as soon as we decide to use a
19098 step height for the vertical axis, we discover that the simple
19099 expression in the varlist for computing the height is wrong. The
19100 expression is @code{(apply 'max numbers-list)}. This returns the
19101 precise height, not the maximum height plus whatever is necessary to
19102 round up to the nearest multiple of five. A more complex expression
19105 As usual in cases like this, a complex problem becomes simpler if it is
19106 divided into several smaller problems.
19108 First, consider the case when the highest value of the graph is an
19109 integral multiple of five---when it is 5, 10, 15, or some higher
19110 multiple of five. We can use this value as the Y axis height.
19112 A fairly simply way to determine whether a number is a multiple of
19113 five is to divide it by five and see if the division results in a
19114 remainder. If there is no remainder, the number is a multiple of
19115 five. Thus, seven divided by five has a remainder of two, and seven
19116 is not an integral multiple of five. Put in slightly different
19117 language, more reminiscent of the classroom, five goes into seven
19118 once, with a remainder of two. However, five goes into ten twice,
19119 with no remainder: ten is an integral multiple of five.
19121 @node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis
19122 @appendixsubsec Side Trip: Compute a Remainder
19124 @findex % @r{(remainder function)}
19125 @cindex Remainder function, @code{%}
19126 In Lisp, the function for computing a remainder is @code{%}. The
19127 function returns the remainder of its first argument divided by its
19128 second argument. As it happens, @code{%} is a function in Emacs Lisp
19129 that you cannot discover using @code{apropos}: you find nothing if you
19130 type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
19131 learn of the existence of @code{%} is to read about it in a book such
19132 as this or in the Emacs Lisp sources. The @code{%} function is used
19133 in the code for @code{rotate-yank-pointer}, which is described in an
19134 appendix. (@xref{rotate-yk-ptr body, , The Body of
19135 @code{rotate-yank-pointer}}.)
19137 You can try the @code{%} function by evaluating the following two
19149 The first expression returns 2 and the second expression returns 0.
19151 To test whether the returned value is zero or some other number, we
19152 can use the @code{zerop} function. This function returns @code{t} if
19153 its argument, which must be a number, is zero.
19165 Thus, the following expression will return @code{t} if the height
19166 of the graph is evenly divisible by five:
19169 (zerop (% height 5))
19173 (The value of @code{height}, of course, can be found from @code{(apply
19174 'max numbers-list)}.)
19176 On the other hand, if the value of @code{height} is not a multiple of
19177 five, we want to reset the value to the next higher multiple of five.
19178 This is straightforward arithmetic using functions with which we are
19179 already familiar. First, we divide the value of @code{height} by five
19180 to determine how many times five goes into the number. Thus, five
19181 goes into twelve twice. If we add one to this quotient and multiply by
19182 five, we will obtain the value of the next multiple of five that is
19183 larger than the height. Five goes into twelve twice. Add one to two,
19184 and multiply by five; the result is fifteen, which is the next multiple
19185 of five that is higher than twelve. The Lisp expression for this is:
19188 (* (1+ (/ height 5)) 5)
19192 For example, if you evaluate the following, the result is 15:
19195 (* (1+ (/ 12 5)) 5)
19198 All through this discussion, we have been using `five' as the value
19199 for spacing labels on the Y axis; but we may want to use some other
19200 value. For generality, we should replace `five' with a variable to
19201 which we can assign a value. The best name I can think of for this
19202 variable is @code{Y-axis-label-spacing}.
19205 Using this term, and an @code{if} expression, we produce the
19210 (if (zerop (% height Y-axis-label-spacing))
19213 (* (1+ (/ height Y-axis-label-spacing))
19214 Y-axis-label-spacing))
19219 This expression returns the value of @code{height} itself if the height
19220 is an even multiple of the value of the @code{Y-axis-label-spacing} or
19221 else it computes and returns a value of @code{height} that is equal to
19222 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
19224 We can now include this expression in the @code{let} expression of the
19225 @code{print-graph} function (after first setting the value of
19226 @code{Y-axis-label-spacing}):
19227 @vindex Y-axis-label-spacing
19231 (defvar Y-axis-label-spacing 5
19232 "Number of lines from one Y axis label to next.")
19237 (let* ((height (apply 'max numbers-list))
19238 (height-of-top-line
19239 (if (zerop (% height Y-axis-label-spacing))
19244 (* (1+ (/ height Y-axis-label-spacing))
19245 Y-axis-label-spacing)))
19246 (symbol-width (length graph-blank))))
19252 (Note use of the @code{let*} function: the initial value of height is
19253 computed once by the @code{(apply 'max numbers-list)} expression and
19254 then the resulting value of @code{height} is used to compute its
19255 final value. @xref{fwd-para let, , The @code{let*} expression}, for
19256 more about @code{let*}.)
19258 @node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis
19259 @appendixsubsec Construct a Y Axis Element
19261 When we print the vertical axis, we want to insert strings such as
19262 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
19263 Moreover, we want the numbers and dashes to line up, so shorter
19264 numbers must be padded with leading spaces. If some of the strings
19265 use two digit numbers, the strings with single digit numbers must
19266 include a leading blank space before the number.
19268 @findex number-to-string
19269 To figure out the length of the number, the @code{length} function is
19270 used. But the @code{length} function works only with a string, not with
19271 a number. So the number has to be converted from being a number to
19272 being a string. This is done with the @code{number-to-string} function.
19277 (length (number-to-string 35))
19280 (length (number-to-string 100))
19286 (@code{number-to-string} is also called @code{int-to-string}; you will
19287 see this alternative name in various sources.)
19289 In addition, in each label, each number is followed by a string such
19290 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
19291 This variable is defined with @code{defvar}:
19296 (defvar Y-axis-tic " - "
19297 "String that follows number in a Y axis label.")
19301 The length of the Y label is the sum of the length of the Y axis tic
19302 mark and the length of the number of the top of the graph.
19305 (length (concat (number-to-string height) Y-axis-tic)))
19308 This value will be calculated by the @code{print-graph} function in
19309 its varlist as @code{full-Y-label-width} and passed on. (Note that we
19310 did not think to include this in the varlist when we first proposed it.)
19312 To make a complete vertical axis label, a tic mark is concatenated
19313 with a number; and the two together may be preceded by one or more
19314 spaces depending on how long the number is. The label consists of
19315 three parts: the (optional) leading spaces, the number, and the tic
19316 mark. The function is passed the value of the number for the specific
19317 row, and the value of the width of the top line, which is calculated
19318 (just once) by @code{print-graph}.
19322 (defun Y-axis-element (number full-Y-label-width)
19323 "Construct a NUMBERed label element.
19324 A numbered element looks like this ` 5 - ',
19325 and is padded as needed so all line up with
19326 the element for the largest number."
19329 (let* ((leading-spaces
19330 (- full-Y-label-width
19332 (concat (number-to-string number)
19337 (make-string leading-spaces ? )
19338 (number-to-string number)
19343 The @code{Y-axis-element} function concatenates together the leading
19344 spaces, if any; the number, as a string; and the tic mark.
19346 To figure out how many leading spaces the label will need, the
19347 function subtracts the actual length of the label---the length of the
19348 number plus the length of the tic mark---from the desired label width.
19350 @findex make-string
19351 Blank spaces are inserted using the @code{make-string} function. This
19352 function takes two arguments: the first tells it how long the string
19353 will be and the second is a symbol for the character to insert, in a
19354 special format. The format is a question mark followed by a blank
19355 space, like this, @samp{? }. @xref{Character Type, , Character Type,
19356 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
19357 syntax for characters.
19359 The @code{number-to-string} function is used in the concatenation
19360 expression, to convert the number to a string that is concatenated
19361 with the leading spaces and the tic mark.
19363 @node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis
19364 @appendixsubsec Create a Y Axis Column
19366 The preceding functions provide all the tools needed to construct a
19367 function that generates a list of numbered and blank strings to insert
19368 as the label for the vertical axis:
19370 @findex Y-axis-column
19373 (defun Y-axis-column (height width-of-label)
19374 "Construct list of Y axis labels and blank strings.
19375 For HEIGHT of line above base and WIDTH-OF-LABEL."
19379 (while (> height 1)
19380 (if (zerop (% height Y-axis-label-spacing))
19381 ;; @r{Insert label.}
19384 (Y-axis-element height width-of-label)
19388 ;; @r{Else, insert blanks.}
19391 (make-string width-of-label ? )
19393 (setq height (1- height)))
19394 ;; @r{Insert base line.}
19396 (cons (Y-axis-element 1 width-of-label) Y-axis))
19397 (nreverse Y-axis)))
19401 In this function, we start with the value of @code{height} and
19402 repetitively subtract one from its value. After each subtraction, we
19403 test to see whether the value is an integral multiple of the
19404 @code{Y-axis-label-spacing}. If it is, we construct a numbered label
19405 using the @code{Y-axis-element} function; if not, we construct a
19406 blank label using the @code{make-string} function. The base line
19407 consists of the number one followed by a tic mark.
19410 @node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis
19411 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
19413 The list constructed by the @code{Y-axis-column} function is passed to
19414 the @code{print-Y-axis} function, which inserts the list as a column.
19416 @findex print-Y-axis
19419 (defun print-Y-axis (height full-Y-label-width)
19420 "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
19421 Height must be the maximum height of the graph.
19422 Full width is the width of the highest label element."
19423 ;; Value of height and full-Y-label-width
19424 ;; are passed by `print-graph'.
19427 (let ((start (point)))
19429 (Y-axis-column height full-Y-label-width))
19430 ;; @r{Place point ready for inserting graph.}
19432 ;; @r{Move point forward by value of} full-Y-label-width
19433 (forward-char full-Y-label-width)))
19437 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
19438 insert the Y axis labels created by the @code{Y-axis-column} function.
19439 In addition, it places point at the correct position for printing the body of
19442 You can test @code{print-Y-axis}:
19450 Y-axis-label-spacing
19459 Copy the following expression:
19462 (print-Y-axis 12 5)
19466 Switch to the @file{*scratch*} buffer and place the cursor where you
19467 want the axis labels to start.
19470 Type @kbd{M-:} (@code{eval-expression}).
19473 Yank the @code{graph-body-print} expression into the minibuffer
19474 with @kbd{C-y} (@code{yank)}.
19477 Press @key{RET} to evaluate the expression.
19480 Emacs will print labels vertically, the top one being
19481 @w{@samp{10 -@w{ }}}. (The @code{print-graph} function
19482 will pass the value of @code{height-of-top-line}, which
19483 in this case would end up as 15.)
19486 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph
19487 @appendixsec The @code{print-X-axis} Function
19488 @cindex Axis, print horizontal
19489 @cindex X axis printing
19490 @cindex Print horizontal axis
19491 @cindex Horizontal axis printing
19493 X axis labels are much like Y axis labels, except that the ticks are on a
19494 line above the numbers. Labels should look like this:
19503 The first tic is under the first column of the graph and is preceded by
19504 several blank spaces. These spaces provide room in rows above for the Y
19505 axis labels. The second, third, fourth, and subsequent ticks are all
19506 spaced equally, according to the value of @code{X-axis-label-spacing}.
19508 The second row of the X axis consists of numbers, preceded by several
19509 blank spaces and also separated according to the value of the variable
19510 @code{X-axis-label-spacing}.
19512 The value of the variable @code{X-axis-label-spacing} should itself be
19513 measured in units of @code{symbol-width}, since you may want to change
19514 the width of the symbols that you are using to print the body of the
19515 graph without changing the ways the graph is labelled.
19518 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
19519 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
19522 @node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
19524 @unnumberedsubsec Similarities and differences
19527 The @code{print-X-axis} function is constructed in more or less the
19528 same fashion as the @code{print-Y-axis} function except that it has
19529 two lines: the line of tic marks and the numbers. We will write a
19530 separate function to print each line and then combine them within the
19531 @code{print-X-axis} function.
19533 This is a three step process:
19537 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
19540 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
19543 Write a function to print both lines, the @code{print-X-axis} function,
19544 using @code{print-X-axis-tic-line} and
19545 @code{print-X-axis-numbered-line}.
19548 @node X Axis Tic Marks, , Similarities differences, print-X-axis
19549 @appendixsubsec X Axis Tic Marks
19551 The first function should print the X axis tic marks. We must specify
19552 the tic marks themselves and their spacing:
19556 (defvar X-axis-label-spacing
19557 (if (boundp 'graph-blank)
19558 (* 5 (length graph-blank)) 5)
19559 "Number of units from one X axis label to next.")
19564 (Note that the value of @code{graph-blank} is set by another
19565 @code{defvar}. The @code{boundp} predicate checks whether it has
19566 already been set; @code{boundp} returns @code{nil} if it has not.
19567 If @code{graph-blank} were unbound and we did not use this conditional
19568 construction, in GNU Emacs 21, we would enter the debugger and see an
19569 error message saying
19570 @samp{@w{Debugger entered--Lisp error:} @w{(void-variable graph-blank)}}.)
19573 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
19577 (defvar X-axis-tic-symbol "|"
19578 "String to insert to point to a column in X axis.")
19583 The goal is to make a line that looks like this:
19589 The first tic is indented so that it is under the first column, which is
19590 indented to provide space for the Y axis labels.
19592 A tic element consists of the blank spaces that stretch from one tic to
19593 the next plus a tic symbol. The number of blanks is determined by the
19594 width of the tic symbol and the @code{X-axis-label-spacing}.
19597 The code looks like this:
19601 ;;; X-axis-tic-element
19605 ;; @r{Make a string of blanks.}
19606 (- (* symbol-width X-axis-label-spacing)
19607 (length X-axis-tic-symbol))
19609 ;; @r{Concatenate blanks with tic symbol.}
19615 Next, we determine how many blanks are needed to indent the first tic
19616 mark to the first column of the graph. This uses the value of
19617 @code{full-Y-label-width} passed it by the @code{print-graph} function.
19620 The code to make @code{X-axis-leading-spaces}
19625 ;; X-axis-leading-spaces
19627 (make-string full-Y-label-width ? )
19632 We also need to determine the length of the horizontal axis, which is
19633 the length of the numbers list, and the number of ticks in the horizontal
19640 (length numbers-list)
19646 (* symbol-width X-axis-label-spacing)
19650 ;; number-of-X-ticks
19651 (if (zerop (% (X-length tic-width)))
19652 (/ (X-length tic-width))
19653 (1+ (/ (X-length tic-width))))
19658 All this leads us directly to the function for printing the X axis tic line:
19660 @findex print-X-axis-tic-line
19663 (defun print-X-axis-tic-line
19664 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
19665 "Print ticks for X axis."
19666 (insert X-axis-leading-spaces)
19667 (insert X-axis-tic-symbol) ; @r{Under first column.}
19670 ;; @r{Insert second tic in the right spot.}
19673 (- (* symbol-width X-axis-label-spacing)
19674 ;; @r{Insert white space up to second tic symbol.}
19675 (* 2 (length X-axis-tic-symbol)))
19677 X-axis-tic-symbol))
19680 ;; @r{Insert remaining ticks.}
19681 (while (> number-of-X-tics 1)
19682 (insert X-axis-tic-element)
19683 (setq number-of-X-tics (1- number-of-X-tics))))
19687 The line of numbers is equally straightforward:
19690 First, we create a numbered element with blank spaces before each number:
19692 @findex X-axis-element
19695 (defun X-axis-element (number)
19696 "Construct a numbered X axis element."
19697 (let ((leading-spaces
19698 (- (* symbol-width X-axis-label-spacing)
19699 (length (number-to-string number)))))
19700 (concat (make-string leading-spaces ? )
19701 (number-to-string number))))
19705 Next, we create the function to print the numbered line, starting with
19706 the number ``1'' under the first column:
19708 @findex print-X-axis-numbered-line
19711 (defun print-X-axis-numbered-line
19712 (number-of-X-tics X-axis-leading-spaces)
19713 "Print line of X-axis numbers"
19714 (let ((number X-axis-label-spacing))
19715 (insert X-axis-leading-spaces)
19721 ;; @r{Insert white space up to next number.}
19722 (- (* symbol-width X-axis-label-spacing) 2)
19724 (number-to-string number)))
19727 ;; @r{Insert remaining numbers.}
19728 (setq number (+ number X-axis-label-spacing))
19729 (while (> number-of-X-tics 1)
19730 (insert (X-axis-element number))
19731 (setq number (+ number X-axis-label-spacing))
19732 (setq number-of-X-tics (1- number-of-X-tics)))))
19736 Finally, we need to write the @code{print-X-axis} that uses
19737 @code{print-X-axis-tic-line} and
19738 @code{print-X-axis-numbered-line}.
19740 The function must determine the local values of the variables used by both
19741 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
19742 then it must call them. Also, it must print the carriage return that
19743 separates the two lines.
19745 The function consists of a varlist that specifies five local variables,
19746 and calls to each of the two line printing functions:
19748 @findex print-X-axis
19751 (defun print-X-axis (numbers-list)
19752 "Print X axis labels to length of NUMBERS-LIST."
19753 (let* ((leading-spaces
19754 (make-string full-Y-label-width ? ))
19757 ;; symbol-width @r{is provided by} graph-body-print
19758 (tic-width (* symbol-width X-axis-label-spacing))
19759 (X-length (length numbers-list))
19767 ;; @r{Make a string of blanks.}
19768 (- (* symbol-width X-axis-label-spacing)
19769 (length X-axis-tic-symbol))
19773 ;; @r{Concatenate blanks with tic symbol.}
19774 X-axis-tic-symbol))
19778 (if (zerop (% X-length tic-width))
19779 (/ X-length tic-width)
19780 (1+ (/ X-length tic-width)))))
19783 (print-X-axis-tic-line tic-number leading-spaces X-tic)
19785 (print-X-axis-numbered-line tic-number leading-spaces)))
19790 You can test @code{print-X-axis}:
19794 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
19795 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
19796 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
19799 Copy the following expression:
19804 (let ((full-Y-label-width 5)
19807 '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
19812 Switch to the @file{*scratch*} buffer and place the cursor where you
19813 want the axis labels to start.
19816 Type @kbd{M-:} (@code{eval-expression}).
19819 Yank the test expression into the minibuffer
19820 with @kbd{C-y} (@code{yank)}.
19823 Press @key{RET} to evaluate the expression.
19827 Emacs will print the horizontal axis like this:
19837 @node Print Whole Graph, , print-X-axis, Full Graph
19838 @appendixsec Printing the Whole Graph
19839 @cindex Printing the whole graph
19840 @cindex Whole graph printing
19841 @cindex Graph, printing all
19843 Now we are nearly ready to print the whole graph.
19845 The function to print the graph with the proper labels follows the
19846 outline we created earlier (@pxref{Full Graph, , A Graph with Labelled
19847 Axes}), but with additions.
19850 Here is the outline:
19854 (defun print-graph (numbers-list)
19855 "@var{documentation}@dots{}"
19856 (let ((height @dots{}
19860 (print-Y-axis height @dots{} )
19861 (graph-body-print numbers-list)
19862 (print-X-axis @dots{} )))
19867 * The final version:: A few changes.
19868 * Test print-graph:: Run a short test.
19869 * Graphing words in defuns:: Executing the final code.
19870 * lambda:: How to write an anonymous function.
19871 * mapcar:: Apply a function to elements of a list.
19872 * Another Bug:: Yet another bug @dots{} most insidious.
19873 * Final printed graph:: The graph itself!
19876 @node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
19878 @unnumberedsubsec Changes for the Final Version
19881 The final version is different from what we planned in two ways:
19882 first, it contains additional values calculated once in the varlist;
19883 second, it carries an option to specify the labels' increment per row.
19884 This latter feature turns out to be essential; otherwise, a graph may
19885 have more rows than fit on a display or on a sheet of paper.
19888 This new feature requires a change to the @code{Y-axis-column}
19889 function, to add @code{vertical-step} to it. The function looks like
19892 @findex Y-axis-column @r{Final version.}
19895 ;;; @r{Final version.}
19896 (defun Y-axis-column
19897 (height width-of-label &optional vertical-step)
19898 "Construct list of labels for Y axis.
19899 HEIGHT is maximum height of graph.
19900 WIDTH-OF-LABEL is maximum width of label.
19901 VERTICAL-STEP, an option, is a positive integer
19902 that specifies how much a Y axis label increments
19903 for each line. For example, a step of 5 means
19904 that each line is five units of the graph."
19908 (number-per-line (or vertical-step 1)))
19909 (while (> height 1)
19910 (if (zerop (% height Y-axis-label-spacing))
19913 ;; @r{Insert label.}
19917 (* height number-per-line)
19922 ;; @r{Else, insert blanks.}
19925 (make-string width-of-label ? )
19927 (setq height (1- height)))
19930 ;; @r{Insert base line.}
19931 (setq Y-axis (cons (Y-axis-element
19932 (or vertical-step 1)
19935 (nreverse Y-axis)))
19939 The values for the maximum height of graph and the width of a symbol
19940 are computed by @code{print-graph} in its @code{let} expression; so
19941 @code{graph-body-print} must be changed to accept them.
19943 @findex graph-body-print @r{Final version.}
19946 ;;; @r{Final version.}
19947 (defun graph-body-print (numbers-list height symbol-width)
19948 "Print a bar graph of the NUMBERS-LIST.
19949 The numbers-list consists of the Y-axis values.
19950 HEIGHT is maximum height of graph.
19951 SYMBOL-WIDTH is number of each column."
19954 (let (from-position)
19955 (while numbers-list
19956 (setq from-position (point))
19958 (column-of-graph height (car numbers-list)))
19959 (goto-char from-position)
19960 (forward-char symbol-width)
19963 ;; @r{Draw graph column by column.}
19965 (setq numbers-list (cdr numbers-list)))
19966 ;; @r{Place point for X axis labels.}
19967 (forward-line height)
19973 Finally, the code for the @code{print-graph} function:
19975 @findex print-graph @r{Final version.}
19978 ;;; @r{Final version.}
19980 (numbers-list &optional vertical-step)
19981 "Print labelled bar graph of the NUMBERS-LIST.
19982 The numbers-list consists of the Y-axis values.
19986 Optionally, VERTICAL-STEP, a positive integer,
19987 specifies how much a Y axis label increments for
19988 each line. For example, a step of 5 means that
19989 each row is five units."
19992 (let* ((symbol-width (length graph-blank))
19993 ;; @code{height} @r{is both the largest number}
19994 ;; @r{and the number with the most digits.}
19995 (height (apply 'max numbers-list))
19998 (height-of-top-line
19999 (if (zerop (% height Y-axis-label-spacing))
20002 (* (1+ (/ height Y-axis-label-spacing))
20003 Y-axis-label-spacing)))
20006 (vertical-step (or vertical-step 1))
20007 (full-Y-label-width
20013 (* height-of-top-line vertical-step))
20019 height-of-top-line full-Y-label-width vertical-step)
20023 numbers-list height-of-top-line symbol-width)
20024 (print-X-axis numbers-list)))
20028 @node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph
20029 @appendixsubsec Testing @code{print-graph}
20032 We can test the @code{print-graph} function with a short list of numbers:
20036 Install the final versions of @code{Y-axis-column},
20037 @code{graph-body-print}, and @code{print-graph} (in addition to the
20041 Copy the following expression:
20044 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
20048 Switch to the @file{*scratch*} buffer and place the cursor where you
20049 want the axis labels to start.
20052 Type @kbd{M-:} (@code{eval-expression}).
20055 Yank the test expression into the minibuffer
20056 with @kbd{C-y} (@code{yank)}.
20059 Press @key{RET} to evaluate the expression.
20063 Emacs will print a graph that looks like this:
20084 On the other hand, if you pass @code{print-graph} a
20085 @code{vertical-step} value of 2, by evaluating this expression:
20088 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
20093 The graph looks like this:
20114 (A question: is the `2' on the bottom of the vertical axis a bug or a
20115 feature? If you think it is a bug, and should be a `1' instead, (or
20116 even a `0'), you can modify the sources.)
20118 @node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph
20119 @appendixsubsec Graphing Numbers of Words and Symbols
20121 Now for the graph for which all this code was written: a graph that
20122 shows how many function definitions contain fewer than 10 words and
20123 symbols, how many contain between 10 and 19 words and symbols, how
20124 many contain between 20 and 29 words and symbols, and so on.
20126 This is a multi-step process. First make sure you have loaded all the
20130 It is a good idea to reset the value of @code{top-of-ranges} in case
20131 you have set it to some different value. You can evaluate the
20136 (setq top-of-ranges
20139 110 120 130 140 150
20140 160 170 180 190 200
20141 210 220 230 240 250
20142 260 270 280 290 300)
20147 Next create a list of the number of words and symbols in each range.
20151 Evaluate the following:
20155 (setq list-for-graph
20158 (recursive-lengths-list-many-files
20159 (directory-files "/usr/local/emacs/lisp"
20167 On my old machine, this took about an hour. It looked though 303 Lisp
20168 files in my copy of Emacs version 19.23. After all that computing,
20169 the @code{list-for-graph} had this value:
20173 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
20174 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
20179 This means that my copy of Emacs had 537 function definitions with
20180 fewer than 10 words or symbols in them, 1,027 function definitions
20181 with 10 to 19 words or symbols in them, 955 function definitions with
20182 20 to 29 words or symbols in them, and so on.
20184 Clearly, just by looking at this list we can see that most function
20185 definitions contain ten to thirty words and symbols.
20187 Now for printing. We do @emph{not} want to print a graph that is
20188 1,030 lines high @dots{} Instead, we should print a graph that is
20189 fewer than twenty-five lines high. A graph that height can be
20190 displayed on almost any monitor, and easily printed on a sheet of paper.
20192 This means that each value in @code{list-for-graph} must be reduced to
20193 one-fiftieth its present value.
20195 Here is a short function to do just that, using two functions we have
20196 not yet seen, @code{mapcar} and @code{lambda}.
20200 (defun one-fiftieth (full-range)
20201 "Return list, each number one-fiftieth of previous."
20202 (mapcar '(lambda (arg) (/ arg 50)) full-range))
20206 @node lambda, mapcar, Graphing words in defuns, Print Whole Graph
20207 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
20208 @cindex Anonymous function
20211 @code{lambda} is the symbol for an anonymous function, a function
20212 without a name. Every time you use an anonymous function, you need to
20213 include its whole body.
20220 (lambda (arg) (/ arg 50))
20224 is a function definition that says `return the value resulting from
20225 dividing whatever is passed to me as @code{arg} by 50'.
20228 Earlier, for example, we had a function @code{multiply-by-seven}; it
20229 multiplied its argument by 7. This function is similar, except it
20230 divides its argument by 50; and, it has no name. The anonymous
20231 equivalent of @code{multiply-by-seven} is:
20234 (lambda (number) (* 7 number))
20238 (@xref{defun, , The @code{defun} Special Form}.)
20242 If we want to multiply 3 by 7, we can write:
20244 @c !!! Clear print-postscript-figures if the computer formatting this
20245 @c document is too small and cannot handle all the diagrams and figures.
20246 @c clear print-postscript-figures
20247 @c set print-postscript-figures
20248 @c lambda example diagram #1
20252 (multiply-by-seven 3)
20253 \_______________/ ^
20259 @ifset print-postscript-figures
20263 %%%% old method of including an image
20264 % \input /usr/local/lib/tex/inputs/psfig.tex
20265 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
20270 @ifclear print-postscript-figures
20274 (multiply-by-seven 3)
20275 \_______________/ ^
20284 This expression returns 21.
20288 Similarly, we can write:
20290 @c lambda example diagram #2
20294 ((lambda (number) (* 7 number)) 3)
20295 \____________________________/ ^
20297 anonymous function argument
20301 @ifset print-postscript-figures
20305 %%%% old method of including an image
20306 % \input /usr/local/lib/tex/inputs/psfig.tex
20307 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
20312 @ifclear print-postscript-figures
20316 ((lambda (number) (* 7 number)) 3)
20317 \____________________________/ ^
20319 anonymous function argument
20327 If we want to divide 100 by 50, we can write:
20329 @c lambda example diagram #3
20333 ((lambda (arg) (/ arg 50)) 100)
20334 \______________________/ \_/
20336 anonymous function argument
20340 @ifset print-postscript-figures
20344 %%%% old method of including an image
20345 % \input /usr/local/lib/tex/inputs/psfig.tex
20346 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
20351 @ifclear print-postscript-figures
20355 ((lambda (arg) (/ arg 50)) 100)
20356 \______________________/ \_/
20358 anonymous function argument
20365 This expression returns 2. The 100 is passed to the function, which
20366 divides that number by 50.
20368 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
20369 Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda
20370 expressions derive from the Lambda Calculus.
20372 @node mapcar, Another Bug, lambda, Print Whole Graph
20373 @appendixsubsec The @code{mapcar} Function
20376 @code{mapcar} is a function that calls its first argument with each
20377 element of its second argument, in turn. The second argument must be
20380 The @samp{map} part of the name comes from the mathematical phrase,
20381 `mapping over a domain', meaning to apply a function to each of the
20382 elements in a domain. The mathematical phrase is based on the
20383 metaphor of a surveyor walking, one step at a time, over an area he is
20384 mapping. And @samp{car}, of course, comes from the Lisp notion of the
20393 (mapcar '1+ '(2 4 6))
20399 The function @code{1+} which adds one to its argument, is executed on
20400 @emph{each} element of the list, and a new list is returned.
20402 Contrast this with @code{apply}, which applies its first argument to
20404 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
20408 In the definition of @code{one-fiftieth}, the first argument is the
20409 anonymous function:
20412 (lambda (arg) (/ arg 50))
20416 and the second argument is @code{full-range}, which will be bound to
20417 @code{list-for-graph}.
20420 The whole expression looks like this:
20423 (mapcar '(lambda (arg) (/ arg 50)) full-range))
20426 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
20427 Lisp Reference Manual}, for more about @code{mapcar}.
20429 Using the @code{one-fiftieth} function, we can generate a list in
20430 which each element is one-fiftieth the size of the corresponding
20431 element in @code{list-for-graph}.
20435 (setq fiftieth-list-for-graph
20436 (one-fiftieth list-for-graph))
20441 The resulting list looks like this:
20445 (10 20 19 15 11 9 6 5 4 3 3 2 2
20446 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
20451 This, we are almost ready to print! (We also notice the loss of
20452 information: many of the higher ranges are 0, meaning that fewer than
20453 50 defuns had that many words or symbols---but not necessarily meaning
20454 that none had that many words or symbols.)
20456 @node Another Bug, Final printed graph, mapcar, Print Whole Graph
20457 @appendixsubsec Another Bug @dots{} Most Insidious
20458 @cindex Bug, most insidious type
20459 @cindex Insidious type of bug
20461 I said `almost ready to print'! Of course, there is a bug in the
20462 @code{print-graph} function @dots{} It has a @code{vertical-step}
20463 option, but not a @code{horizontal-step} option. The
20464 @code{top-of-range} scale goes from 10 to 300 by tens. But the
20465 @code{print-graph} function will print only by ones.
20467 This is a classic example of what some consider the most insidious
20468 type of bug, the bug of omission. This is not the kind of bug you can
20469 find by studying the code, for it is not in the code; it is an omitted
20470 feature. Your best actions are to try your program early and often;
20471 and try to arrange, as much as you can, to write code that is easy to
20472 understand and easy to change. Try to be aware, whenever you can,
20473 that whatever you have written, @emph{will} be rewritten, if not soon,
20474 eventually. A hard maxim to follow.
20476 It is the @code{print-X-axis-numbered-line} function that needs the
20477 work; and then the @code{print-X-axis} and the @code{print-graph}
20478 functions need to be adapted. Not much needs to be done; there is one
20479 nicety: the numbers ought to line up under the tic marks. This takes
20483 Here is the corrected @code{print-X-axis-numbered-line}:
20487 (defun print-X-axis-numbered-line
20488 (number-of-X-tics X-axis-leading-spaces
20489 &optional horizontal-step)
20490 "Print line of X-axis numbers"
20491 (let ((number X-axis-label-spacing)
20492 (horizontal-step (or horizontal-step 1)))
20495 (insert X-axis-leading-spaces)
20496 ;; @r{Delete extra leading spaces.}
20499 (length (number-to-string horizontal-step)))))
20504 ;; @r{Insert white space.}
20506 X-axis-label-spacing)
20509 (number-to-string horizontal-step)))
20513 (* number horizontal-step))))
20516 ;; @r{Insert remaining numbers.}
20517 (setq number (+ number X-axis-label-spacing))
20518 (while (> number-of-X-tics 1)
20519 (insert (X-axis-element
20520 (* number horizontal-step)))
20521 (setq number (+ number X-axis-label-spacing))
20522 (setq number-of-X-tics (1- number-of-X-tics)))))
20527 If you are reading this in Info, you can see the new versions of
20528 @code{print-X-axis} @code{print-graph} and evaluate them. If you are
20529 reading this in a printed book, you can see the changed lines here
20530 (the full text is too much to print).
20535 (defun print-X-axis (numbers-list horizontal-step)
20537 (print-X-axis-numbered-line
20538 tic-number leading-spaces horizontal-step))
20546 &optional vertical-step horizontal-step)
20548 (print-X-axis numbers-list horizontal-step))
20556 (defun print-X-axis (numbers-list horizontal-step)
20557 "Print X axis labels to length of NUMBERS-LIST.
20558 Optionally, HORIZONTAL-STEP, a positive integer,
20559 specifies how much an X axis label increments for
20563 ;; Value of symbol-width and full-Y-label-width
20564 ;; are passed by `print-graph'.
20565 (let* ((leading-spaces
20566 (make-string full-Y-label-width ? ))
20567 ;; symbol-width @r{is provided by} graph-body-print
20568 (tic-width (* symbol-width X-axis-label-spacing))
20569 (X-length (length numbers-list))
20575 ;; @r{Make a string of blanks.}
20576 (- (* symbol-width X-axis-label-spacing)
20577 (length X-axis-tic-symbol))
20581 ;; @r{Concatenate blanks with tic symbol.}
20582 X-axis-tic-symbol))
20584 (if (zerop (% X-length tic-width))
20585 (/ X-length tic-width)
20586 (1+ (/ X-length tic-width)))))
20590 (print-X-axis-tic-line
20591 tic-number leading-spaces X-tic)
20593 (print-X-axis-numbered-line
20594 tic-number leading-spaces horizontal-step)))
20601 (numbers-list &optional vertical-step horizontal-step)
20602 "Print labelled bar graph of the NUMBERS-LIST.
20603 The numbers-list consists of the Y-axis values.
20607 Optionally, VERTICAL-STEP, a positive integer,
20608 specifies how much a Y axis label increments for
20609 each line. For example, a step of 5 means that
20610 each row is five units.
20614 Optionally, HORIZONTAL-STEP, a positive integer,
20615 specifies how much an X axis label increments for
20617 (let* ((symbol-width (length graph-blank))
20618 ;; @code{height} @r{is both the largest number}
20619 ;; @r{and the number with the most digits.}
20620 (height (apply 'max numbers-list))
20623 (height-of-top-line
20624 (if (zerop (% height Y-axis-label-spacing))
20627 (* (1+ (/ height Y-axis-label-spacing))
20628 Y-axis-label-spacing)))
20631 (vertical-step (or vertical-step 1))
20632 (full-Y-label-width
20636 (* height-of-top-line vertical-step))
20641 height-of-top-line full-Y-label-width vertical-step)
20643 numbers-list height-of-top-line symbol-width)
20644 (print-X-axis numbers-list horizontal-step)))
20651 Graphing Definitions Re-listed
20654 Here are all the graphing definitions in their final form:
20658 (defvar top-of-ranges
20661 110 120 130 140 150
20662 160 170 180 190 200
20663 210 220 230 240 250)
20664 "List specifying ranges for `defuns-per-range'.")
20668 (defvar graph-symbol "*"
20669 "String used as symbol in graph, usually an asterisk.")
20673 (defvar graph-blank " "
20674 "String used as blank in graph, usually a blank space.
20675 graph-blank must be the same number of columns wide
20680 (defvar Y-axis-tic " - "
20681 "String that follows number in a Y axis label.")
20685 (defvar Y-axis-label-spacing 5
20686 "Number of lines from one Y axis label to next.")
20690 (defvar X-axis-tic-symbol "|"
20691 "String to insert to point to a column in X axis.")
20695 (defvar X-axis-label-spacing
20696 (if (boundp 'graph-blank)
20697 (* 5 (length graph-blank)) 5)
20698 "Number of units from one X axis label to next.")
20704 (defun count-words-in-defun ()
20705 "Return the number of words and symbols in a defun."
20706 (beginning-of-defun)
20708 (end (save-excursion (end-of-defun) (point))))
20713 (and (< (point) end)
20715 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
20717 (setq count (1+ count)))
20724 (defun lengths-list-file (filename)
20725 "Return list of definitions' lengths within FILE.
20726 The returned list is a list of numbers.
20727 Each number is the number of words or
20728 symbols in one function definition."
20732 (message "Working on `%s' ... " filename)
20734 (let ((buffer (find-file-noselect filename))
20736 (set-buffer buffer)
20737 (setq buffer-read-only t)
20739 (goto-char (point-min))
20743 (while (re-search-forward "^(defun" nil t)
20745 (cons (count-words-in-defun) lengths-list)))
20746 (kill-buffer buffer)
20753 (defun lengths-list-many-files (list-of-files)
20754 "Return list of lengths of defuns in LIST-OF-FILES."
20755 (let (lengths-list)
20756 ;;; @r{true-or-false-test}
20757 (while list-of-files
20763 ;;; @r{Generate a lengths' list.}
20765 (expand-file-name (car list-of-files)))))
20766 ;;; @r{Make files' list shorter.}
20767 (setq list-of-files (cdr list-of-files)))
20768 ;;; @r{Return final value of lengths' list.}
20775 (defun defuns-per-range (sorted-lengths top-of-ranges)
20776 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
20777 (let ((top-of-range (car top-of-ranges))
20778 (number-within-range 0)
20779 defuns-per-range-list)
20784 (while top-of-ranges
20788 ;; @r{Need number for numeric test.}
20789 (car sorted-lengths)
20790 (< (car sorted-lengths) top-of-range))
20792 ;; @r{Count number of definitions within current range.}
20793 (setq number-within-range (1+ number-within-range))
20794 (setq sorted-lengths (cdr sorted-lengths)))
20798 ;; @r{Exit inner loop but remain within outer loop.}
20800 (setq defuns-per-range-list
20801 (cons number-within-range defuns-per-range-list))
20802 (setq number-within-range 0) ; @r{Reset count to zero.}
20804 ;; @r{Move to next range.}
20805 (setq top-of-ranges (cdr top-of-ranges))
20806 ;; @r{Specify next top of range value.}
20807 (setq top-of-range (car top-of-ranges)))
20811 ;; @r{Exit outer loop and count the number of defuns larger than}
20812 ;; @r{ the largest top-of-range value.}
20813 (setq defuns-per-range-list
20815 (length sorted-lengths)
20816 defuns-per-range-list))
20818 ;; @r{Return a list of the number of definitions within each range,}
20819 ;; @r{ smallest to largest.}
20820 (nreverse defuns-per-range-list)))
20826 (defun column-of-graph (max-graph-height actual-height)
20827 "Return list of MAX-GRAPH-HEIGHT strings;
20828 ACTUAL-HEIGHT are graph-symbols.
20829 The graph-symbols are contiguous entries at the end
20831 The list will be inserted as one column of a graph.
20832 The strings are either graph-blank or graph-symbol."
20836 (let ((insert-list nil)
20837 (number-of-top-blanks
20838 (- max-graph-height actual-height)))
20840 ;; @r{Fill in @code{graph-symbols}.}
20841 (while (> actual-height 0)
20842 (setq insert-list (cons graph-symbol insert-list))
20843 (setq actual-height (1- actual-height)))
20847 ;; @r{Fill in @code{graph-blanks}.}
20848 (while (> number-of-top-blanks 0)
20849 (setq insert-list (cons graph-blank insert-list))
20850 (setq number-of-top-blanks
20851 (1- number-of-top-blanks)))
20853 ;; @r{Return whole list.}
20860 (defun Y-axis-element (number full-Y-label-width)
20861 "Construct a NUMBERed label element.
20862 A numbered element looks like this ` 5 - ',
20863 and is padded as needed so all line up with
20864 the element for the largest number."
20867 (let* ((leading-spaces
20868 (- full-Y-label-width
20870 (concat (number-to-string number)
20875 (make-string leading-spaces ? )
20876 (number-to-string number)
20883 (defun print-Y-axis
20884 (height full-Y-label-width &optional vertical-step)
20885 "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
20886 Height must be the maximum height of the graph.
20887 Full width is the width of the highest label element.
20888 Optionally, print according to VERTICAL-STEP."
20891 ;; Value of height and full-Y-label-width
20892 ;; are passed by `print-graph'.
20893 (let ((start (point)))
20895 (Y-axis-column height full-Y-label-width vertical-step))
20898 ;; @r{Place point ready for inserting graph.}
20900 ;; @r{Move point forward by value of} full-Y-label-width
20901 (forward-char full-Y-label-width)))
20907 (defun print-X-axis-tic-line
20908 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
20909 "Print ticks for X axis."
20910 (insert X-axis-leading-spaces)
20911 (insert X-axis-tic-symbol) ; @r{Under first column.}
20914 ;; @r{Insert second tic in the right spot.}
20917 (- (* symbol-width X-axis-label-spacing)
20918 ;; @r{Insert white space up to second tic symbol.}
20919 (* 2 (length X-axis-tic-symbol)))
20921 X-axis-tic-symbol))
20924 ;; @r{Insert remaining ticks.}
20925 (while (> number-of-X-tics 1)
20926 (insert X-axis-tic-element)
20927 (setq number-of-X-tics (1- number-of-X-tics))))
20933 (defun X-axis-element (number)
20934 "Construct a numbered X axis element."
20935 (let ((leading-spaces
20936 (- (* symbol-width X-axis-label-spacing)
20937 (length (number-to-string number)))))
20938 (concat (make-string leading-spaces ? )
20939 (number-to-string number))))
20945 (defun graph-body-print (numbers-list height symbol-width)
20946 "Print a bar graph of the NUMBERS-LIST.
20947 The numbers-list consists of the Y-axis values.
20948 HEIGHT is maximum height of graph.
20949 SYMBOL-WIDTH is number of each column."
20952 (let (from-position)
20953 (while numbers-list
20954 (setq from-position (point))
20956 (column-of-graph height (car numbers-list)))
20957 (goto-char from-position)
20958 (forward-char symbol-width)
20961 ;; @r{Draw graph column by column.}
20963 (setq numbers-list (cdr numbers-list)))
20964 ;; @r{Place point for X axis labels.}
20965 (forward-line height)
20972 (defun Y-axis-column
20973 (height width-of-label &optional vertical-step)
20974 "Construct list of labels for Y axis.
20975 HEIGHT is maximum height of graph.
20976 WIDTH-OF-LABEL is maximum width of label.
20979 VERTICAL-STEP, an option, is a positive integer
20980 that specifies how much a Y axis label increments
20981 for each line. For example, a step of 5 means
20982 that each line is five units of the graph."
20984 (number-per-line (or vertical-step 1)))
20987 (while (> height 1)
20988 (if (zerop (% height Y-axis-label-spacing))
20989 ;; @r{Insert label.}
20993 (* height number-per-line)
20998 ;; @r{Else, insert blanks.}
21001 (make-string width-of-label ? )
21003 (setq height (1- height)))
21006 ;; @r{Insert base line.}
21007 (setq Y-axis (cons (Y-axis-element
21008 (or vertical-step 1)
21011 (nreverse Y-axis)))
21017 (defun print-X-axis-numbered-line
21018 (number-of-X-tics X-axis-leading-spaces
21019 &optional horizontal-step)
21020 "Print line of X-axis numbers"
21021 (let ((number X-axis-label-spacing)
21022 (horizontal-step (or horizontal-step 1)))
21025 (insert X-axis-leading-spaces)
21027 (delete-char (- (1- (length (number-to-string horizontal-step)))))
21030 ;; @r{Insert white space up to next number.}
21031 (- (* symbol-width X-axis-label-spacing)
21032 (1- (length (number-to-string horizontal-step)))
21035 (number-to-string (* number horizontal-step))))
21038 ;; @r{Insert remaining numbers.}
21039 (setq number (+ number X-axis-label-spacing))
21040 (while (> number-of-X-tics 1)
21041 (insert (X-axis-element (* number horizontal-step)))
21042 (setq number (+ number X-axis-label-spacing))
21043 (setq number-of-X-tics (1- number-of-X-tics)))))
21049 (defun print-X-axis (numbers-list horizontal-step)
21050 "Print X axis labels to length of NUMBERS-LIST.
21051 Optionally, HORIZONTAL-STEP, a positive integer,
21052 specifies how much an X axis label increments for
21056 ;; Value of symbol-width and full-Y-label-width
21057 ;; are passed by `print-graph'.
21058 (let* ((leading-spaces
21059 (make-string full-Y-label-width ? ))
21060 ;; symbol-width @r{is provided by} graph-body-print
21061 (tic-width (* symbol-width X-axis-label-spacing))
21062 (X-length (length numbers-list))
21068 ;; @r{Make a string of blanks.}
21069 (- (* symbol-width X-axis-label-spacing)
21070 (length X-axis-tic-symbol))
21074 ;; @r{Concatenate blanks with tic symbol.}
21075 X-axis-tic-symbol))
21077 (if (zerop (% X-length tic-width))
21078 (/ X-length tic-width)
21079 (1+ (/ X-length tic-width)))))
21083 (print-X-axis-tic-line
21084 tic-number leading-spaces X-tic)
21086 (print-X-axis-numbered-line
21087 tic-number leading-spaces horizontal-step)))
21093 (defun one-fiftieth (full-range)
21094 "Return list, each number of which is 1/50th previous."
21095 (mapcar '(lambda (arg) (/ arg 50)) full-range))
21102 (numbers-list &optional vertical-step horizontal-step)
21103 "Print labelled bar graph of the NUMBERS-LIST.
21104 The numbers-list consists of the Y-axis values.
21108 Optionally, VERTICAL-STEP, a positive integer,
21109 specifies how much a Y axis label increments for
21110 each line. For example, a step of 5 means that
21111 each row is five units.
21115 Optionally, HORIZONTAL-STEP, a positive integer,
21116 specifies how much an X axis label increments for
21118 (let* ((symbol-width (length graph-blank))
21119 ;; @code{height} @r{is both the largest number}
21120 ;; @r{and the number with the most digits.}
21121 (height (apply 'max numbers-list))
21124 (height-of-top-line
21125 (if (zerop (% height Y-axis-label-spacing))
21128 (* (1+ (/ height Y-axis-label-spacing))
21129 Y-axis-label-spacing)))
21132 (vertical-step (or vertical-step 1))
21133 (full-Y-label-width
21137 (* height-of-top-line vertical-step))
21143 height-of-top-line full-Y-label-width vertical-step)
21145 numbers-list height-of-top-line symbol-width)
21146 (print-X-axis numbers-list horizontal-step)))
21153 @node Final printed graph, , Another Bug, Print Whole Graph
21154 @appendixsubsec The Printed Graph
21156 When made and installed, you can call the @code{print-graph} command
21162 (print-graph fiftieth-list-for-graph 50 10)
21192 50 - ***************** * *
21194 10 50 100 150 200 250 300 350
21201 The largest group of functions contain 10 -- 19 words and symbols each.
21203 @node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top
21204 @appendix Free Software and Free Manuals
21206 @strong{by Richard M. Stallman}
21209 The biggest deficiency in free operating systems is not in the
21210 software---it is the lack of good free manuals that we can include in
21211 these systems. Many of our most important programs do not come with
21212 full manuals. Documentation is an essential part of any software
21213 package; when an important free software package does not come with a
21214 free manual, that is a major gap. We have many such gaps today.
21216 Once upon a time, many years ago, I thought I would learn Perl. I got
21217 a copy of a free manual, but I found it hard to read. When I asked
21218 Perl users about alternatives, they told me that there were better
21219 introductory manuals---but those were not free.
21221 Why was this? The authors of the good manuals had written them for
21222 O'Reilly Associates, which published them with restrictive terms---no
21223 copying, no modification, source files not available---which exclude
21224 them from the free software community.
21226 That wasn't the first time this sort of thing has happened, and (to
21227 our community's great loss) it was far from the last. Proprietary
21228 manual publishers have enticed a great many authors to restrict their
21229 manuals since then. Many times I have heard a GNU user eagerly tell me
21230 about a manual that he is writing, with which he expects to help the
21231 GNU project---and then had my hopes dashed, as he proceeded to explain
21232 that he had signed a contract with a publisher that would restrict it
21233 so that we cannot use it.
21235 Given that writing good English is a rare skill among programmers, we
21236 can ill afford to lose manuals this way.
21239 (The Free Software Foundation
21240 @uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, ,
21241 sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html,
21242 GNU manuals}, too.)
21244 Free documentation, like free software, is a matter of freedom, not
21245 price. The problem with these manuals was not that O'Reilly Associates
21246 charged a price for printed copies---that in itself is fine. (The Free
21247 Software Foundation sells printed copies of free GNU manuals, too.)
21248 But GNU manuals are available in source code form, while these manuals
21249 are available only on paper. GNU manuals come with permission to copy
21250 and modify; the Perl manuals do not. These restrictions are the
21253 The criterion for a free manual is pretty much the same as for free
21254 software: it is a matter of giving all users certain
21255 freedoms. Redistribution (including commercial redistribution) must be
21256 permitted, so that the manual can accompany every copy of the program,
21257 on-line or on paper. Permission for modification is crucial too.
21259 As a general rule, I don't believe that it is essential for people to
21260 have permission to modify all sorts of articles and books. The issues
21261 for writings are not necessarily the same as those for software. For
21262 example, I don't think you or I are obliged to give permission to
21263 modify articles like this one, which describe our actions and our
21266 But there is a particular reason why the freedom to modify is crucial
21267 for documentation for free software. When people exercise their right
21268 to modify the software, and add or change its features, if they are
21269 conscientious they will change the manual too---so they can provide
21270 accurate and usable documentation with the modified program. A manual
21271 which forbids programmers to be conscientious and finish the job, or
21272 more precisely requires them to write a new manual from scratch if
21273 they change the program, does not fill our community's needs.
21275 While a blanket prohibition on modification is unacceptable, some
21276 kinds of limits on the method of modification pose no problem. For
21277 example, requirements to preserve the original author's copyright
21278 notice, the distribution terms, or the list of authors, are ok. It is
21279 also no problem to require modified versions to include notice that
21280 they were modified, even to have entire sections that may not be
21281 deleted or changed, as long as these sections deal with nontechnical
21282 topics. (Some GNU manuals have them.)
21284 These kinds of restrictions are not a problem because, as a practical
21285 matter, they don't stop the conscientious programmer from adapting the
21286 manual to fit the modified program. In other words, they don't block
21287 the free software community from making full use of the manual.
21289 However, it must be possible to modify all the technical content of
21290 the manual, and then distribute the result in all the usual media,
21291 through all the usual channels; otherwise, the restrictions do block
21292 the community, the manual is not free, and so we need another manual.
21294 Unfortunately, it is often hard to find someone to write another
21295 manual when a proprietary manual exists. The obstacle is that many
21296 users think that a proprietary manual is good enough---so they don't
21297 see the need to write a free manual. They do not see that the free
21298 operating system has a gap that needs filling.
21300 Why do users think that proprietary manuals are good enough? Some have
21301 not considered the issue. I hope this article will do something to
21304 Other users consider proprietary manuals acceptable for the same
21305 reason so many people consider proprietary software acceptable: they
21306 judge in purely practical terms, not using freedom as a
21307 criterion. These people are entitled to their opinions, but since
21308 those opinions spring from values which do not include freedom, they
21309 are no guide for those of us who do value freedom.
21311 Please spread the word about this issue. We continue to lose manuals
21312 to proprietary publishing. If we spread the word that proprietary
21313 manuals are not sufficient, perhaps the next person who wants to help
21314 GNU by writing documentation will realize, before it is too late, that
21315 he must above all make it free.
21317 We can also encourage commercial publishers to sell free, copylefted
21318 manuals instead of proprietary ones. One way you can help this is to
21319 check the distribution terms of a manual before you buy it, and prefer
21320 copylefted manuals to non-copylefted ones.
21324 Note: The Free Software Foundation maintains a page on its Web site
21325 that lists free books available from other publishers:@*
21326 @uref{http://www.gnu.org/doc/other-free-books.html}
21329 @node GNU Free Documentation License, Index, Free Software and Free Manuals, Top
21330 @appendix GNU Free Documentation License
21332 @cindex FDL, GNU Free Documentation License
21333 @center Version 1.2, November 2002
21336 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
21337 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
21339 Everyone is permitted to copy and distribute verbatim copies
21340 of this license document, but changing it is not allowed.
21347 The purpose of this License is to make a manual, textbook, or other
21348 functional and useful document @dfn{free} in the sense of freedom: to
21349 assure everyone the effective freedom to copy and redistribute it,
21350 with or without modifying it, either commercially or noncommercially.
21351 Secondarily, this License preserves for the author and publisher a way
21352 to get credit for their work, while not being considered responsible
21353 for modifications made by others.
21355 This License is a kind of ``copyleft'', which means that derivative
21356 works of the document must themselves be free in the same sense. It
21357 complements the GNU General Public License, which is a copyleft
21358 license designed for free software.
21360 We have designed this License in order to use it for manuals for free
21361 software, because free software needs free documentation: a free
21362 program should come with manuals providing the same freedoms that the
21363 software does. But this License is not limited to software manuals;
21364 it can be used for any textual work, regardless of subject matter or
21365 whether it is published as a printed book. We recommend this License
21366 principally for works whose purpose is instruction or reference.
21369 APPLICABILITY AND DEFINITIONS
21371 This License applies to any manual or other work, in any medium, that
21372 contains a notice placed by the copyright holder saying it can be
21373 distributed under the terms of this License. Such a notice grants a
21374 world-wide, royalty-free license, unlimited in duration, to use that
21375 work under the conditions stated herein. The ``Document'', below,
21376 refers to any such manual or work. Any member of the public is a
21377 licensee, and is addressed as ``you''. You accept the license if you
21378 copy, modify or distribute the work in a way requiring permission
21379 under copyright law.
21381 A ``Modified Version'' of the Document means any work containing the
21382 Document or a portion of it, either copied verbatim, or with
21383 modifications and/or translated into another language.
21385 A ``Secondary Section'' is a named appendix or a front-matter section
21386 of the Document that deals exclusively with the relationship of the
21387 publishers or authors of the Document to the Document's overall
21388 subject (or to related matters) and contains nothing that could fall
21389 directly within that overall subject. (Thus, if the Document is in
21390 part a textbook of mathematics, a Secondary Section may not explain
21391 any mathematics.) The relationship could be a matter of historical
21392 connection with the subject or with related matters, or of legal,
21393 commercial, philosophical, ethical or political position regarding
21396 The ``Invariant Sections'' are certain Secondary Sections whose titles
21397 are designated, as being those of Invariant Sections, in the notice
21398 that says that the Document is released under this License. If a
21399 section does not fit the above definition of Secondary then it is not
21400 allowed to be designated as Invariant. The Document may contain zero
21401 Invariant Sections. If the Document does not identify any Invariant
21402 Sections then there are none.
21404 The ``Cover Texts'' are certain short passages of text that are listed,
21405 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
21406 the Document is released under this License. A Front-Cover Text may
21407 be at most 5 words, and a Back-Cover Text may be at most 25 words.
21409 A ``Transparent'' copy of the Document means a machine-readable copy,
21410 represented in a format whose specification is available to the
21411 general public, that is suitable for revising the document
21412 straightforwardly with generic text editors or (for images composed of
21413 pixels) generic paint programs or (for drawings) some widely available
21414 drawing editor, and that is suitable for input to text formatters or
21415 for automatic translation to a variety of formats suitable for input
21416 to text formatters. A copy made in an otherwise Transparent file
21417 format whose markup, or absence of markup, has been arranged to thwart
21418 or discourage subsequent modification by readers is not Transparent.
21419 An image format is not Transparent if used for any substantial amount
21420 of text. A copy that is not ``Transparent'' is called ``Opaque''.
21422 Examples of suitable formats for Transparent copies include plain
21423 @sc{ascii} without markup, Texinfo input format, La@TeX{} input
21424 format, @acronym{SGML} or @acronym{XML} using a publicly available
21425 @acronym{DTD}, and standard-conforming simple @acronym{HTML},
21426 PostScript or @acronym{PDF} designed for human modification. Examples
21427 of transparent image formats include @acronym{PNG}, @acronym{XCF} and
21428 @acronym{JPG}. Opaque formats include proprietary formats that can be
21429 read and edited only by proprietary word processors, @acronym{SGML} or
21430 @acronym{XML} for which the @acronym{DTD} and/or processing tools are
21431 not generally available, and the machine-generated @acronym{HTML},
21432 PostScript or @acronym{PDF} produced by some word processors for
21433 output purposes only.
21435 The ``Title Page'' means, for a printed book, the title page itself,
21436 plus such following pages as are needed to hold, legibly, the material
21437 this License requires to appear in the title page. For works in
21438 formats which do not have any title page as such, ``Title Page'' means
21439 the text near the most prominent appearance of the work's title,
21440 preceding the beginning of the body of the text.
21442 A section ``Entitled XYZ'' means a named subunit of the Document whose
21443 title either is precisely XYZ or contains XYZ in parentheses following
21444 text that translates XYZ in another language. (Here XYZ stands for a
21445 specific section name mentioned below, such as ``Acknowledgements'',
21446 ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
21447 of such a section when you modify the Document means that it remains a
21448 section ``Entitled XYZ'' according to this definition.
21450 The Document may include Warranty Disclaimers next to the notice which
21451 states that this License applies to the Document. These Warranty
21452 Disclaimers are considered to be included by reference in this
21453 License, but only as regards disclaiming warranties: any other
21454 implication that these Warranty Disclaimers may have is void and has
21455 no effect on the meaning of this License.
21460 You may copy and distribute the Document in any medium, either
21461 commercially or noncommercially, provided that this License, the
21462 copyright notices, and the license notice saying this License applies
21463 to the Document are reproduced in all copies, and that you add no other
21464 conditions whatsoever to those of this License. You may not use
21465 technical measures to obstruct or control the reading or further
21466 copying of the copies you make or distribute. However, you may accept
21467 compensation in exchange for copies. If you distribute a large enough
21468 number of copies you must also follow the conditions in section 3.
21470 You may also lend copies, under the same conditions stated above, and
21471 you may publicly display copies.
21474 COPYING IN QUANTITY
21476 If you publish printed copies (or copies in media that commonly have
21477 printed covers) of the Document, numbering more than 100, and the
21478 Document's license notice requires Cover Texts, you must enclose the
21479 copies in covers that carry, clearly and legibly, all these Cover
21480 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
21481 the back cover. Both covers must also clearly and legibly identify
21482 you as the publisher of these copies. The front cover must present
21483 the full title with all words of the title equally prominent and
21484 visible. You may add other material on the covers in addition.
21485 Copying with changes limited to the covers, as long as they preserve
21486 the title of the Document and satisfy these conditions, can be treated
21487 as verbatim copying in other respects.
21489 If the required texts for either cover are too voluminous to fit
21490 legibly, you should put the first ones listed (as many as fit
21491 reasonably) on the actual cover, and continue the rest onto adjacent
21494 If you publish or distribute Opaque copies of the Document numbering
21495 more than 100, you must either include a machine-readable Transparent
21496 copy along with each Opaque copy, or state in or with each Opaque copy
21497 a computer-network location from which the general network-using
21498 public has access to download using public-standard network protocols
21499 a complete Transparent copy of the Document, free of added material.
21500 If you use the latter option, you must take reasonably prudent steps,
21501 when you begin distribution of Opaque copies in quantity, to ensure
21502 that this Transparent copy will remain thus accessible at the stated
21503 location until at least one year after the last time you distribute an
21504 Opaque copy (directly or through your agents or retailers) of that
21505 edition to the public.
21507 It is requested, but not required, that you contact the authors of the
21508 Document well before redistributing any large number of copies, to give
21509 them a chance to provide you with an updated version of the Document.
21514 You may copy and distribute a Modified Version of the Document under
21515 the conditions of sections 2 and 3 above, provided that you release
21516 the Modified Version under precisely this License, with the Modified
21517 Version filling the role of the Document, thus licensing distribution
21518 and modification of the Modified Version to whoever possesses a copy
21519 of it. In addition, you must do these things in the Modified Version:
21523 Use in the Title Page (and on the covers, if any) a title distinct
21524 from that of the Document, and from those of previous versions
21525 (which should, if there were any, be listed in the History section
21526 of the Document). You may use the same title as a previous version
21527 if the original publisher of that version gives permission.
21530 List on the Title Page, as authors, one or more persons or entities
21531 responsible for authorship of the modifications in the Modified
21532 Version, together with at least five of the principal authors of the
21533 Document (all of its principal authors, if it has fewer than five),
21534 unless they release you from this requirement.
21537 State on the Title page the name of the publisher of the
21538 Modified Version, as the publisher.
21541 Preserve all the copyright notices of the Document.
21544 Add an appropriate copyright notice for your modifications
21545 adjacent to the other copyright notices.
21548 Include, immediately after the copyright notices, a license notice
21549 giving the public permission to use the Modified Version under the
21550 terms of this License, in the form shown in the Addendum below.
21553 Preserve in that license notice the full lists of Invariant Sections
21554 and required Cover Texts given in the Document's license notice.
21557 Include an unaltered copy of this License.
21560 Preserve the section Entitled ``History'', Preserve its Title, and add
21561 to it an item stating at least the title, year, new authors, and
21562 publisher of the Modified Version as given on the Title Page. If
21563 there is no section Entitled ``History'' in the Document, create one
21564 stating the title, year, authors, and publisher of the Document as
21565 given on its Title Page, then add an item describing the Modified
21566 Version as stated in the previous sentence.
21569 Preserve the network location, if any, given in the Document for
21570 public access to a Transparent copy of the Document, and likewise
21571 the network locations given in the Document for previous versions
21572 it was based on. These may be placed in the ``History'' section.
21573 You may omit a network location for a work that was published at
21574 least four years before the Document itself, or if the original
21575 publisher of the version it refers to gives permission.
21578 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
21579 the Title of the section, and preserve in the section all the
21580 substance and tone of each of the contributor acknowledgements and/or
21581 dedications given therein.
21584 Preserve all the Invariant Sections of the Document,
21585 unaltered in their text and in their titles. Section numbers
21586 or the equivalent are not considered part of the section titles.
21589 Delete any section Entitled ``Endorsements''. Such a section
21590 may not be included in the Modified Version.
21593 Do not retitle any existing section to be Entitled ``Endorsements'' or
21594 to conflict in title with any Invariant Section.
21597 Preserve any Warranty Disclaimers.
21600 If the Modified Version includes new front-matter sections or
21601 appendices that qualify as Secondary Sections and contain no material
21602 copied from the Document, you may at your option designate some or all
21603 of these sections as invariant. To do this, add their titles to the
21604 list of Invariant Sections in the Modified Version's license notice.
21605 These titles must be distinct from any other section titles.
21607 You may add a section Entitled ``Endorsements'', provided it contains
21608 nothing but endorsements of your Modified Version by various
21609 parties---for example, statements of peer review or that the text has
21610 been approved by an organization as the authoritative definition of a
21613 You may add a passage of up to five words as a Front-Cover Text, and a
21614 passage of up to 25 words as a Back-Cover Text, to the end of the list
21615 of Cover Texts in the Modified Version. Only one passage of
21616 Front-Cover Text and one of Back-Cover Text may be added by (or
21617 through arrangements made by) any one entity. If the Document already
21618 includes a cover text for the same cover, previously added by you or
21619 by arrangement made by the same entity you are acting on behalf of,
21620 you may not add another; but you may replace the old one, on explicit
21621 permission from the previous publisher that added the old one.
21623 The author(s) and publisher(s) of the Document do not by this License
21624 give permission to use their names for publicity for or to assert or
21625 imply endorsement of any Modified Version.
21628 COMBINING DOCUMENTS
21630 You may combine the Document with other documents released under this
21631 License, under the terms defined in section 4 above for modified
21632 versions, provided that you include in the combination all of the
21633 Invariant Sections of all of the original documents, unmodified, and
21634 list them all as Invariant Sections of your combined work in its
21635 license notice, and that you preserve all their Warranty Disclaimers.
21637 The combined work need only contain one copy of this License, and
21638 multiple identical Invariant Sections may be replaced with a single
21639 copy. If there are multiple Invariant Sections with the same name but
21640 different contents, make the title of each such section unique by
21641 adding at the end of it, in parentheses, the name of the original
21642 author or publisher of that section if known, or else a unique number.
21643 Make the same adjustment to the section titles in the list of
21644 Invariant Sections in the license notice of the combined work.
21646 In the combination, you must combine any sections Entitled ``History''
21647 in the various original documents, forming one section Entitled
21648 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
21649 and any sections Entitled ``Dedications''. You must delete all
21650 sections Entitled ``Endorsements.''
21653 COLLECTIONS OF DOCUMENTS
21655 You may make a collection consisting of the Document and other documents
21656 released under this License, and replace the individual copies of this
21657 License in the various documents with a single copy that is included in
21658 the collection, provided that you follow the rules of this License for
21659 verbatim copying of each of the documents in all other respects.
21661 You may extract a single document from such a collection, and distribute
21662 it individually under this License, provided you insert a copy of this
21663 License into the extracted document, and follow this License in all
21664 other respects regarding verbatim copying of that document.
21667 AGGREGATION WITH INDEPENDENT WORKS
21669 A compilation of the Document or its derivatives with other separate
21670 and independent documents or works, in or on a volume of a storage or
21671 distribution medium, is called an ``aggregate'' if the copyright
21672 resulting from the compilation is not used to limit the legal rights
21673 of the compilation's users beyond what the individual works permit.
21674 When the Document is included in an aggregate, this License does not
21675 apply to the other works in the aggregate which are not themselves
21676 derivative works of the Document.
21678 If the Cover Text requirement of section 3 is applicable to these
21679 copies of the Document, then if the Document is less than one half of
21680 the entire aggregate, the Document's Cover Texts may be placed on
21681 covers that bracket the Document within the aggregate, or the
21682 electronic equivalent of covers if the Document is in electronic form.
21683 Otherwise they must appear on printed covers that bracket the whole
21689 Translation is considered a kind of modification, so you may
21690 distribute translations of the Document under the terms of section 4.
21691 Replacing Invariant Sections with translations requires special
21692 permission from their copyright holders, but you may include
21693 translations of some or all Invariant Sections in addition to the
21694 original versions of these Invariant Sections. You may include a
21695 translation of this License, and all the license notices in the
21696 Document, and any Warranty Disclaimers, provided that you also include
21697 the original English version of this License and the original versions
21698 of those notices and disclaimers. In case of a disagreement between
21699 the translation and the original version of this License or a notice
21700 or disclaimer, the original version will prevail.
21702 If a section in the Document is Entitled ``Acknowledgements'',
21703 ``Dedications'', or ``History'', the requirement (section 4) to Preserve
21704 its Title (section 1) will typically require changing the actual
21710 You may not copy, modify, sublicense, or distribute the Document except
21711 as expressly provided for under this License. Any other attempt to
21712 copy, modify, sublicense or distribute the Document is void, and will
21713 automatically terminate your rights under this License. However,
21714 parties who have received copies, or rights, from you under this
21715 License will not have their licenses terminated so long as such
21716 parties remain in full compliance.
21719 FUTURE REVISIONS OF THIS LICENSE
21721 The Free Software Foundation may publish new, revised versions
21722 of the GNU Free Documentation License from time to time. Such new
21723 versions will be similar in spirit to the present version, but may
21724 differ in detail to address new problems or concerns. See
21725 @uref{http://www.gnu.org/copyleft/}.
21727 Each version of the License is given a distinguishing version number.
21728 If the Document specifies that a particular numbered version of this
21729 License ``or any later version'' applies to it, you have the option of
21730 following the terms and conditions either of that specified version or
21731 of any later version that has been published (not as a draft) by the
21732 Free Software Foundation. If the Document does not specify a version
21733 number of this License, you may choose any version ever published (not
21734 as a draft) by the Free Software Foundation.
21738 @appendixsubsec ADDENDUM: How to use this License for your documents
21740 To use this License in a document you have written, include a copy of
21741 the License in the document and put the following copyright and
21742 license notices just after the title page:
21746 Copyright (C) @var{year} @var{your name}.
21747 Permission is granted to copy, distribute and/or modify this document
21748 under the terms of the GNU Free Documentation License, Version 1.2
21749 or any later version published by the Free Software Foundation;
21750 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
21751 A copy of the license is included in the section entitled ``GNU
21752 Free Documentation License''.
21756 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
21757 replace the ``with...Texts.'' line with this:
21761 with the Invariant Sections being @var{list their titles}, with
21762 the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
21767 If you have Invariant Sections without Cover Texts, or some other
21768 combination of the three, merge those two alternatives to suit the
21771 If your document contains nontrivial examples of program code, we
21772 recommend releasing these examples in parallel under your choice of
21773 free software license, such as the GNU General Public License,
21774 to permit their use in free software.
21776 @node Index, About the Author, GNU Free Documentation License, Top
21777 @comment node-name, next, previous, up
21781 MENU ENTRY: NODE NAME.
21787 @c Place biographical information on right-hand (verso) page
21791 \par\vfill\supereject
21792 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
21793 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
21796 \par\vfill\supereject
21797 \par\vfill\supereject
21798 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
21799 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
21808 @c ================ Biographical information ================
21812 @center About the Author
21817 @node About the Author, , Index, Top
21818 @unnumbered About the Author
21822 Robert J. Chassell has worked with GNU Emacs since 1985. He writes
21823 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
21824 world on software freedom. Chassell was a founding Director and
21825 Treasurer of the Free Software Foundation, Inc. He is co-author of
21826 the @cite{Texinfo} manual, and has edited more than a dozen other
21827 books. He graduated from Cambridge University, in England. He has an
21828 abiding interest in social and economic history and flies his own
21835 @c Prevent page number on blank verso, so eject it first.
21837 \par\vfill\supereject
21842 @evenheading @thispage @| @| @thistitle
21843 @oddheading @| @| @thispage
21849 arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf